erstellt SPINE
This commit is contained in:
Michael Tamse
+366
@@ -0,0 +1,366 @@
|
||||
---
|
||||
name: Adversarial Review — ARCHITECTURE-SPINE.md (wiki-of-wikis-2026-08-14)
|
||||
type: adversarial-review
|
||||
adversary: independent
|
||||
status: final
|
||||
created: 2026-08-14
|
||||
target:
|
||||
- ARCHITECTURE-SPINE.md
|
||||
- prd.md (prd-wow20-2026-08-14)
|
||||
mandate: two mutually conformant units build incompatible systems
|
||||
---
|
||||
|
||||
# Adversarial Review — Wiki of Wikis Architecture Spine
|
||||
|
||||
## 0. Auftrag & Methode
|
||||
|
||||
Dieser Review greift die Architektur grundsätzlich als Gegner an. Für jeden Finding wird
|
||||
**ein Paar von Einheiten eine Ebene tiefer** konstruiert (zwei Producer, zwei Consumer,
|
||||
Mensch vs. Agent), bei dem **jede Einheit jede AD buchstäblich befolgt** — und das Paar
|
||||
dennoch inkompatible Systeme baut.
|
||||
|
||||
Der Spine verspricht in AD-17 ausdrücklich Schutz vor Last-Writer-Wins. Dieser Review zeigt,
|
||||
dass der Schutz an mehreren Stellen konzeptionell verrutscht und durch neue oder
|
||||
verschärfte Regeln geschlossen werden muss. Alle Findings nennen die beteiligten ADs und
|
||||
die konkrete Close-Regel.
|
||||
|
||||
**Adversarial Verdict:** Der Spine beschreibt ein konsistentes Architektur-Layering,
|
||||
aber er **pins keine der drei operativen Schnittstellen, an denen Producer und Producer
|
||||
bzw. Producer und Consumer aufeinandertreffen**: (a) die Lease-/Koordinations-Semantik
|
||||
(AD-17), (b) die Concept-ID-Normalisierung (AD-7) und (c) die Claim-Granularität der
|
||||
Provenienz (AD-4/Q-1). Solange diese drei Unterspezifikationen bestehen, folgen zwei
|
||||
konforme Einheiten garantiert mindestens einmal in einer von diesen Nachweisen zu
|
||||
inkompatiblen Bundles.
|
||||
|
||||
---
|
||||
|
||||
## Findings
|
||||
|
||||
### F-1 [CRITICAL] — AD-17 definiert keinen Lease-Mechanismus; der Konflikt-Bewahrungsartefakt selbst (log.md) liegt außerhalb des Leases
|
||||
|
||||
**Beteiligte ADs:** AD-5, AD-6, AD-7, AD-14, AD-16, AD-17 (und deren Bind: NFR-7, FR-8, FFr-13)
|
||||
|
||||
**Konstruiertes Paar:**
|
||||
|
||||
- **Einheit 1**: Compiler-Run A (Claude-Adapter), Area `flowable/`. Liest AD-17 und realisiert
|
||||
„Lease auf dem eigenen Workspace" als Lock-Datei `.wofw/leases/flowable.lock` außerhalb von `wiki/`.
|
||||
- **Einheit 2**: Compiler-Run B (Codex-Adapter) parallel, dieselbe Area. Realisiert „Lease"
|
||||
als Branch-Name `lease/flowable`. Auf einem zweiten Klon (FT-7 Portability erlaubt und
|
||||
fördert das).
|
||||
|
||||
Keine AD spezifiziert:
|
||||
|
||||
1. was ein Lease **ist** (Lockdatei? Branchname? Registry-Eintrag?),
|
||||
2. wie Leases **klon-übergreifend** koordiniert werden (bei Local-First + Portability gibt es
|
||||
keinen gemeinsamen Koordinationszustand),
|
||||
3. wie man ein Lease **atomar** erwirbt und wie Stale-Leases erkannt werden,
|
||||
4. ob `log.md` / `index.md` an der Bundle-Wurzel **innerhalb oder außerhalb** eines
|
||||
area-skopierten Leases liegen.
|
||||
|
||||
Beide Einheiten mutieren `wiki/flowable/timers.md` mit unterschiedlichen Synthesen, committen
|
||||
ihre Branches und führen nach main zusammen. Git auto-mergt getrennte Hunks textuell:
|
||||
Die Datei enthält anschließend **beide** Synthesen ungeprüft nebeneinander — ein stiller
|
||||
semantischer Merge. **Genau das verbietet AD-16** („Konflikte explizit erhalten, nie
|
||||
stillschweigend auflösen"), aber die Verletzung entsteht durch den Koordinationsmechanismus
|
||||
selbst, nicht durch Regelfolgefehler einer Einheit. Jede Einheit hat jede AD eingehalten.
|
||||
|
||||
Zusätzlich, und schärfer: Der einzige Ort, der einen Konflikt bewahren soll (`log.md`, AD-16
|
||||
und AD-17 Rule 4), liegt an der Bundle-Wurzel und damit **außerhalb jedes area-skopierten
|
||||
Leases**. Zwei Producer, die beide einen Konflikt dokumentieren, schreiben beide nach
|
||||
`log.md` kandidierend — **on log.md itself herrscht Last-Writer-Wins**. Der
|
||||
Konflikt-Bewahrungsmechanismus ist damit selbst die Stelle, an der Arbeit still
|
||||
überschrieben wird.
|
||||
|
||||
**Close-Regeln (neu/verschärft):**
|
||||
|
||||
- **AD-17a (Lease-Vertrag):** AD-17 muss definieren, was ein Lease ist und wie er erworben
|
||||
wird — gegen einen **eindeutigen Commit-Objektwert** (Merge-Base-Disziplin) und über einen
|
||||
einzigen, deterministischen Mechanismus (z. B. Branch-Prefix-Konvention `lease/<area>/<id>`
|
||||
ergänzt um eine Lockdatei **semantisch identisch realisiert** in jedem Adapter; die
|
||||
Realisierung darf nicht pro Adapter frei wählbar sein).
|
||||
- **AD-17b (Lease-Scope):** Das Lease muss ausdrücklich `wiki/` **inklusive `log.md`,
|
||||
`index.md` und aller Wurzel-Dateien** abdecken („Root-Scope"), sonst ist der
|
||||
Bewahrungsartefakt wehrlos.
|
||||
- **AD-17c (Kein stiller Auto-Merge):** Zwei Branches, die denselben Concept-Pfad modifiziert
|
||||
haben, dürfen **nicht** per textuellem Git-Auto-Merge zusammengeführt werden. Die
|
||||
Zusammenführung ist Compiler-vermittelt und durchläuft die AD-16-Klassifikation — mit
|
||||
explizitem `log.md`-Eintrag, falls die Inhalte nicht identisch sind.
|
||||
- **AD-17d (Lease-Held darf nicht committen „vergessen"):** Entweder Time-to-Live + Registrierung
|
||||
des Leases im Clon-Wurzelzustand oder Regel, dass unveröffentlichte Leases nach
|
||||
Run-Abbruch als stale gelten und `raw/` (immutable, AD-3) die Wiederherstellungsbasis ist.
|
||||
|
||||
---
|
||||
|
||||
### F-2 [CRITICAL] — AD-7 pinnt die Concept-ID nicht eindeutig: zwei Consumer/Producer rechnen denselben Baum auf zwei ID-Räume ab
|
||||
|
||||
**Beteiligte ADs:** AD-7, AD-8, AD-9, AD-14 (Renames als semantische Änderung), Bind FR-5/FR-6/FR-9–FR-12
|
||||
|
||||
**Konstruiertes Paar:**
|
||||
|
||||
- **Einheit 1** (Produzent, z. B. Codex-Adapter): schreibt einen Link als `[timers](flowable/timers)` —
|
||||
OKF-Stil, bundle-relativ, ohne `.md`, im Sinne der „Consistency Conventions — Concept identity:
|
||||
relativer OKF-Dateipfad **ohne** `.md`".
|
||||
- **Einheit 2** (Produzent, z. B. Claude-Adapter): schreibt denselben Link als `[timers](flowable/timers.md)` —
|
||||
„normale Markdown-Links" (AD-8) mit Dateiendung.
|
||||
|
||||
Beide Links sind in Markdown gültig. Ob sie dieselbe Concept-ID bezeichnen, hängt von einer
|
||||
Endungs-Normalisierung ab, die **nirgends** festgeschrieben ist:
|
||||
|
||||
1. **Endung:** `timers` vs `timers.md` — eine Einheit liest die ID mit, die andere ohne.
|
||||
2. **`index.md`:** AD-9 zeigt `spring/index.md`. Ist dessen Concept-ID `spring`, `spring/index`
|
||||
oder `spring/`? Nicht beantwortet. Link-Traversierung bricht je nach Default verschieden.
|
||||
3. **Case & Dateisystem:** `Timers.md` vs `timers.md` auf einem case-sensitiven System sind zwei
|
||||
Concept-IDs für dasselbe fachliche Wissen.
|
||||
4. **Area-Zuordnung:** AD-7 definiert die ID als den Pfad, aber **nicht, wohin ein fachliches
|
||||
Thema gehört**. Producer A legt „Timers"-Wissen unter `flowable/timers` an, Producer B unter
|
||||
`spring/timers`. Beide erzeugen „eigenständige Konzeptwesen" (FR-5) — beide AD-konform, ein
|
||||
Duplikat. AD-5 schützt das vorhandene Konzept sogar („nur betroffene Concepts verändern"),
|
||||
verschärft also die Vervielfachung statt sie zu verhindern.
|
||||
5. **Rename-Kaskade:** AD-7 erklärt Renames zu semantischen Änderungen — damit ist ein
|
||||
Umbenennen **erlaubt und erforderlich**, um die ID zu ändern, aber jede andere Einheit, die
|
||||
die alte ID gecacht hat (bewusst oder im Prompt-Kontext), aktualisiert sich nicht und
|
||||
referenziert ins Leere.
|
||||
|
||||
Beide Einheiten befolgen AD-7 buchstäblich und verwalten über denselben Baum **zwei
|
||||
inkompatible ID-Räume**.
|
||||
|
||||
**Close-Regeln:**
|
||||
|
||||
- **AD-7a (ID-Normalisierung):** genau eine kanonische Form festschreiben, z. B.
|
||||
`Kleinbuchstaben`, Pfad relativ zur Bundleroot, ohne Endung, `index.md` → Area-Pfad,
|
||||
keine Trailendepunkte. Mit Beispieltabelle (`flowable/timers`, `spring`, `spring/testing`).
|
||||
- **AD-7b (Link-Form):** AD-8 muss die eine erlaubte Linkform festlegen (bundle-relativ mit
|
||||
oder ohne Endung — eine davon, nicht beides).
|
||||
- **AD-7c (Area-Zuordnung):** eine Zuordnungsregel für „wohin gehört ein Thema" ergänzen
|
||||
(Relevanzbestimmung ist AD-17-Anhang bereits auf textuelle Mittel festgelegt; dieselbe
|
||||
textuelle Determiniertheit muss auch die **Ziel-Area** determinieren, z. B. via
|
||||
bestehendem `index.md`-Link oder Toplevel-Kollision-Halten an bestehenden Pfaden).
|
||||
- **AD-7d (Rename-Verträglichkeit):** Rename = neues Objekt + expliziter
|
||||
Redirect-/Deprecation-Eintrag im `log.md` (oder `references/`-Konvention von OKF), damit
|
||||
alte IDs maschinell ausfindig gemacht werden können.
|
||||
|
||||
---
|
||||
|
||||
### F-3 [HIGH] — AD-4/Q-1 verankern Provenienz nur auf Concept-Ebene; ein Consumer kann belegte von kontextuellen Aussagen nicht mechanisch unterscheiden
|
||||
|
||||
**Beteiligte ADs:** AD-4 (ASSUMPTION), Q-1, AD-13, Bind FR-3/FR-7/FR-8/NFR-7, FT-5, SM-3
|
||||
|
||||
**Konstruiertes Paar:**
|
||||
|
||||
- **Einheit 1** (Compiler): erzeugt ein synthetisiertes Concept (Synthese aus A und B gemäß
|
||||
AD-4/FR-7). Im Frontmatter stehen `sources:` mit den **mitgeführten** Source-Verweisen
|
||||
(AD-4: „relevante Source-Provenienz in das resultierende Concept übernehmen"). Der Body
|
||||
mischt drei belegte Claims mit zwei reinen Inferenz-Umformulierungen. Der Compiler erfüllt
|
||||
damit FT-5 und SM-3 buchstäblich („ein erzeugtes Concept kann auf Sources zurückgeführt
|
||||
werden" — Concept-Ebene).
|
||||
- **Einheit 3** (strenger Consumer, auch ein LLM-Agent): liest dasselbe Bundle und kann pro
|
||||
Satz **keine** Grounding-Granularität mechanisch erkennen. Der Frontmatter-`sources`-Block
|
||||
gilt für das ganze Dokument; Inference-Formulierungen sehen identisch „belegt" aus.
|
||||
|
||||
Beide Einheiten sind AD-konform. Die **Belegstärke** der konsumierten Aussagen divergiert
|
||||
jedoch: Ein strenger Consumer verwirft Inferenzen als unbelegt, ein laxer Consumer behandelt
|
||||
sie als evidential. Q-1 beantwortet nur, ob ein generiertes Concept ein anderes generiertes
|
||||
Concept als **alleinige** Provenienz verwenden darf („No") — es installiert damit keinerlei
|
||||
maschinell prüfbare Regel auf **Aussage- oder Blockebene**. NFR-7 („Graceful Partial
|
||||
Knowledge", Unsicherheit explizit) wird auf Concept-Ebene deklariert, aber nie in einer
|
||||
satzgranularen Struktur erzwingbar.
|
||||
|
||||
**Close-Regeln:**
|
||||
|
||||
- **AD-4a (Claim-Granularität):** Provenienz muss pro behauptender Einheit (Block/Absatz)
|
||||
referenzierbar sein, nicht nur pro Concept. Mindestform: jede belegte Aussage trägt einen
|
||||
Inline-Verweis auf `raw/`-Evidenz; Kontext-/Synthese-Umformulierungen erhalten explizit
|
||||
einen Kontext-Marker („aus <Concept-Pfad> übernommen, nicht selbst belegt").
|
||||
- **AD-4b (Sources-Ziel):** `sources`-Einträge dürfen auf `raw/` oder auf extern referenzierte
|
||||
Evidenz verweisen, **nie** auf einen `wiki/...`-Concept-Pfad (Wiki-Links bleiben AD-8;
|
||||
Provenienz und Beziehung werden formatseitig disambiguiert).
|
||||
- **AD-4c (Q-1 verbindlich):** die Annahme „ein generiertes Concept darf nie ein anderes
|
||||
generiertes Concept als *einzige* Provenienz führen" wird von einer ASSUMPTION in eine
|
||||
Regel überführt und in die (geplante) `schema/wiki-compiler.md`-Validierung aufgenommen.
|
||||
|
||||
---
|
||||
|
||||
### F-4 [HIGH] — AD-16 vs. AD-17: die Klassifikation „CONTRADICTING vs. CORRECTING" entscheidet, wer das Auflösungs-Artefakt besitzt — und ist nicht arbitrierbar
|
||||
|
||||
**Beteiligte ADs:** AD-16, AD-17 Rule 2/4, AD-15, AD-5, FR-8/FR-13, NFR-7
|
||||
|
||||
**Konstruiertes Paar:**
|
||||
|
||||
- **Einheit 1**: klassifiziert eine neue Quelle als CONTRADICTING → lässt den Concept-Bereich
|
||||
**unangetastet**, dokumentiert den Disagreement in `log.md` (AD-16 wörtlich).
|
||||
- **Einheit 2**: klassifiziert **dieselbe** Quelle als CORRECTING → **revidiert** das
|
||||
Concept (AD-16 erlaubt „CORRECTING → revise existing knowledge").
|
||||
|
||||
Beide Handlungen sind AD-16-konform. Die Kategorien sind „konzeptionell" (AD-16 verzichtet
|
||||
explizit auf eine interne Datenstruktur und damit auch auf ein deterministisches
|
||||
Entscheidungskriterium). Die Adversarität liegt darin, dass die Klassifikation **besitzt**,
|
||||
was passiert: CONTRADICTING → Bewahrung, CORRECTING → Revision. Wer das Auflösungs-Artefakt
|
||||
(Concept **oder** log.md) besitzt, hängt damit an der Willkür derselben Einheiten, die auch
|
||||
die Schiedsrichter sein sollen. Das Lease- und Konvergenz-Modell (AD-17 Rule 4) kann hier
|
||||
nicht arbitrieren, weil „produktiver Nutzen/Beitrag" als Auflösungsprinzip aufgerufen wird,
|
||||
bevor überhaupt eine gemeinsame Bestimmung darüber existiert, ob ein Beitrag überhaupt
|
||||
anzurühren ist. Ergebnis: Ein Paar aus einem bewahrenden und einem revidierenden Producer
|
||||
ist nach allen ADs legal — und eine der beiden feindlichen Bundles stammt aus einer AD-16-
|
||||
konformen Einheit, deren Arbeit von der anderen Einheit als „wirksam ersetzt" gilt.
|
||||
|
||||
**Close-Regeln:**
|
||||
|
||||
- **AD-16a (Default-Vorspann):** deterministische Vorgabe, z. B. „bei Widerspruch gilt
|
||||
Standard-Bewahrung (CONTRADICTING), sofern die neue Quelle nicht mit expliziter Evidenz die
|
||||
alte strikt ersetzt; andernfalls CORRECTING mit dokumentierter Ersetzungslogik".
|
||||
- **AD-16b (Klassifikations-Pflicht):** die Klassifikation inkl. Begründung muss **im selben
|
||||
Artefakt** wie die Mutation landen (log.md-Eintrag angebunden an den mutierten Concept-Pfad),
|
||||
damit die Auflösungs-Entscheidung reproduzierbar und damit die Ownership auditierbar ist.
|
||||
|
||||
---
|
||||
|
||||
### F-5 [MEDIUM] — AD-17 Rule 2 schützt nur den *committed* Input; der dirty Working Tree eines Producers wird von anderer Einheit still zerstört (AD-15/FR-13-Loch)
|
||||
|
||||
**Beteiligte ADs:** AD-17 Rule 2, AD-6 (Mutation), AD-5, AD-15, Q-2, FR-13, AD-14
|
||||
|
||||
**Konstruiertes Paar:**
|
||||
|
||||
- **Einheit 1** (Mensch): bearbeitet direkt ein Concept (`wiki/flowable/timers.md`), nach
|
||||
AD-15/Q-2 ausdrücklich erlaubt, **noch nicht committet** (dirty working tree).
|
||||
- **Einheit 2** (Compiler, AD-10-agent-unabhängig): liest gemäß AD-17 Rule 2 **nur committed
|
||||
Inhalte** → die menschliche Änderung ist de jure kein Input. Nach AD-6 Mutation läuft der
|
||||
Adapter in die Arbeitskopie, und der Adapter-Mechanismus (checkout/rebase/clean) trifft auf
|
||||
die dirty Datei.
|
||||
|
||||
Die Spannung: Rule 2 verhindert, dass uncommittete Inhalte „Input" werden — sie verhindert
|
||||
**nicht**, dass der Mechanismus der anderen Einheit (Rebase/Checkout/Clean im eigenen
|
||||
Adapter-Vokabular) die **uncommittete Arbeitskopie** der Einheit 1 genauso still entfernt.
|
||||
Ein Rebase/Checkout in Run B wirft die uncommittete Datei von Einheit 1 ohne Git-Konflikt und
|
||||
ohne log.md-Eintrag weg. Damit wird FR-13 („menschliche Inhalte nicht allein wegen fehlender
|
||||
Herkunft entfernen") und AD-15 verletzt, ohne dass Einheit 2 irgendeine AD gebrochen hat.
|
||||
|
||||
**Close-Regeln:**
|
||||
|
||||
- **AD-17e (Dirty-Tree-Schutz):** vor jeder Mutation muss der Producer die Arbeitskopie für
|
||||
den zu mutierenden Bereich prüfen; nicht-committete, fremde Änderungen sind zu schützen
|
||||
(stash/divert in eine geschützte Scratch-Zone), und jeder verdrängte uncommittete Inhalt ist
|
||||
in `log.md` zu dokumentieren.
|
||||
- **AD-14/AD-17f (Commit-Grenze als einzige Mutationsgrenze):** die Mutation darf nur auf
|
||||
Verzeichnis/Commit-Ebene wirken, die eine fremde dirty Arbeit nie als Side-Effekt von
|
||||
checkout/rebase löscht.
|
||||
|
||||
---
|
||||
|
||||
### F-6 [MEDIUM] — AD-1/FR-9 binden an „OKF 0.2", aber der Spine bindet weder das Feld-Subset noch den Validator; Spine-Artefakte (log.md) sind nicht OKF-tippbar
|
||||
|
||||
**Beteiligte ADs:** AD-1, FR-9, AD-16 (log.md), AD-9 (index.md), AD-10, NFR-5, FT-1, Consistency-Conventions „Errors: kein erfolgreicher Run bei ungültigem Bundle"
|
||||
|
||||
**Konstruiertes Paar:**
|
||||
|
||||
- **Einheit 1** (Claude-Adapter): emittiert `sources: [raw/foo.md, raw/bar.md]` (Liste von
|
||||
Strings).
|
||||
- **Einheit 2** (Codex-Adapter): emittiert OKF-Map-/Objekt-Form bzw. deklariert
|
||||
`okf_version: "0.2"` nur in der Bundleroot-`index.md` (PRD § 13 nennt beides „optional").
|
||||
|
||||
Beide behaupten OKF-0.2-Konformität. Es gibt **keinen Validator** (siehe Consistency
|
||||
Conventions: „kein erfolgreicher Run bei ungültigem Bundle" — aber ungültig *worum*?). Der
|
||||
Spine verweist auf `schema/wiki-compiler.md`, aber dieser Ordner ist im Structural Seed nur
|
||||
Dekoration und wird von **keiner** AD als verbindliches Artefakt gebunden. AD-10 verbietet
|
||||
Adaptern abweichende Knowledge-Semantik — ohne objektives Validitätsprädikat ist „abweichend"
|
||||
nicht entscheidbar.
|
||||
|
||||
Zweitens sind **Spine-eigene Artefakte** nicht OKF-getippt:
|
||||
|
||||
- `log.md` (AD-16): eine nicht gesperrte `.md`-Datei. OKF verlangt, dass nicht gesperrte
|
||||
Bundledateien ein `type` tragen. `log.md` hat keines — entweder ist das Bundle
|
||||
OKF-inkonform, oder log.md ist ein undefinierter Concept-Typ, sodass zwei Consumer uneins
|
||||
sind, ob es ein Concept ist.
|
||||
- `index.md` als Discovery-Ebene (AD-9): OKF lässt Bundleroot-`index.md` mit
|
||||
`okf_version` optional zu; AD-9 macht sie faktisch zur Pflicht-Discovery — das ist eine
|
||||
Spine-Konvention über OKF hinaus, deren Consumer-Verträglichkeit ungeprüft ist.
|
||||
|
||||
Damit bleibt FT-1/NFR-5 („keine Runtime", „Read ohne Prozess") nur oberflächlich erhalten:
|
||||
Nicht-Runtime gilt für das **Lesen von Markdown**; das **Verstehen** der Spine-Konventionen
|
||||
(log.md-Semantik, Lease-Marker, index-Discovery) setzt Interpretationswissen voraus, das zwei
|
||||
Consumer unterschiedlich ausführen. Lesbarkeit ≠ Konformität.
|
||||
|
||||
**Close-Regeln:**
|
||||
|
||||
- **AD-1a (Schema-Bindung):** `schema/wiki-compiler.md` wird als **verbindlich** gebunden:
|
||||
Es pinnt (i) das exakte OKF-0.2-Feld-Subset (sources-Form als Liste vs. Map, generiert/verified,
|
||||
status), (ii) `log.md` als dokumentiertes Artefakt **mit eigenem `type`**, (iii) die
|
||||
index-Discovery-Regel, (iv) die OKF-Validitätsprädikate.
|
||||
- **AD-1b (Validator-Regel):** eine Regel, wie Konformität **geprüft** wird (auch wenn der
|
||||
Validator selbst bis D-3 als Agent-Instruktion lebt): „kein erfolgreicher Run bei
|
||||
OKF-invalidem Bundle laut schema/wiki-compiler.md".
|
||||
- **NFR-5/AD-1c (FT-1 mechanisch):** FT-1 wird als Regel formuliert: „Entferne alle
|
||||
Runtime-Komponenten; der Reader benötigt nur Markdown + eine statisch abgelegte
|
||||
Konventions-Kurzfassung, um Anzahl, Bedeutung und Grounding aller Artefakte (incl. log.md)
|
||||
eindeutig zu bestimmen."
|
||||
|
||||
---
|
||||
|
||||
### F-7 [MEDIUM] — AD-17 Rule 4: „produktiver Nutzen als Auflösungs-Prinzip" ist nicht entscheidbar; zwei Merge-Autoritäten lösen denselben Konflikt gegensätzlich auf
|
||||
|
||||
**Beteiligte ADs:** AD-17 Rule 4, AD-16, AD-14, PRD OQ-4 (Konflikt-Auflösung)
|
||||
|
||||
**Konstruiertes Paar:**
|
||||
|
||||
- **Einheit 1** (Merge-Autorität / Maintainer A): führt den Konflikt in `flowable/timers.md`
|
||||
zugunsten von Quelle A auf, dokumentiert die Ablehnung von Quelle B in `log.md`.
|
||||
- **Einheit 2** (Merge-Autorität / Maintainer B): führt denselben Konflikt zugunsten von
|
||||
Quelle B auf, dokumentiert die Ablehnung von Quelle A in `log.md`.
|
||||
|
||||
Beide sind AD-16/AD-17-konform (Konflikt explizit erhalten, offengelegt). Das Prinzip
|
||||
„produktiver Nutzen/Beitrag zählt als Auflösungs-Prinzip" ist aber **weder mechanisch noch
|
||||
authoritativ bestimmt**: Es sagt nichts darüber, wer entscheidet und anhand welcher
|
||||
beobachtbaren Kriterien. Zwei voneinander unabhängige Merge-Läufe über demselben Git-Zustand
|
||||
produzieren unterschiedliche Bundles, beide konform. Damit ist die Reproduzierbarkeit des
|
||||
Bundles (eine Kernanforderung aus FT-7 / SM-1) nicht gegeben — derselbe Git-Zustand kann zu
|
||||
zwei kanonisch gültigen, aber inkompatiblen Bundles führen.
|
||||
|
||||
**Close-Regeln:**
|
||||
|
||||
- **AD-17g (Auflösungs-Autorität):** festlegen, **wer** eine AD-16-Kollision auflöst
|
||||
(MVP: der Compiler-Run, der das Lease hält, nach AD-16a-Default; menschliche Eskalation nur
|
||||
bei Nicht-Entscheidbarkeit), und dass die Auflösung an denselben Commit/dieselbe
|
||||
Log-Dokumentation gebunden ist (Kryptominimal: Commit-Hash + Klassifikation im Eintrag).
|
||||
- **AD-17h (Determinismus-Kontrakt):** über demselben Git-Zustand und derselben Input-Menge
|
||||
müssen zwei unabhängige Läufe **denselben** Bundle-Zustand erzeugen (als expliziter
|
||||
Fitness-Test analog FT-6), andernfalls ist die AD-16-Klassifikation nicht deterministisch
|
||||
genug.
|
||||
|
||||
---
|
||||
|
||||
## 3. Querschnitt-Lücken und wo Autorität fehlt
|
||||
|
||||
Die Findings reihen sich in ein Muster: **der Spine beschreibt die Data-Ebene präzise und
|
||||
delegiert die Koordination an „den ausführenden Adapter", ohne dem Adapter einen
|
||||
deterministischen Vertrag zu geben.**
|
||||
|
||||
- **D-3 / D-7 / D-1 bleiben offen**, während die Konformität des Bundles (F-6) davon abhängt,
|
||||
dass der Validator irgendwann existiert. Solange der Validator liegt, ist „OKF-konform"
|
||||
eine Behauptung, kein Prädikat.
|
||||
- **PRD OQ-4** (welche Konflikte darf der Compiler selbst auflösen) ist im Spine als
|
||||
AD-17 Rule 4 nur scheinbar beantwortet — sie beantwortet das *woran*, nicht das *wer* (F-7).
|
||||
- **Q-1** im Spine („Current assumption: No") hat bisher keine Regelwirkung (F-3).
|
||||
- **Q-2** (dürfen Menschen generierte Concepts direkt editieren?) ist für die
|
||||
Dirty-Tree-Kollision (F-5) relevant, da der Spine mit „verhindert nicht menschengemachte
|
||||
Edits" eine Koexistenz erlaubt, ohne die Koexistenz zu koordinieren.
|
||||
|
||||
---
|
||||
|
||||
## 4. Empfohlener Regel-Katalog (neu/verschärft)
|
||||
|
||||
| # | Regel | Ersetzt/ergänzt | Schließt |
|
||||
|---|---|---|---|
|
||||
| R1 | Lease-Vertrag (Mechanismus, Commit-Bindung, stalo) | AD-17a–17d | F-1 |
|
||||
| R2 | Root-Scope des Leases inkl. `log.md`/`index.md` | AD-17b | F-1 |
|
||||
| R3 | Kein textueller Git-Auto-Merge über identischen Concept-Pfad; Merge nur über AD-16-Klassifikation | AD-17c | F-1 |
|
||||
| R4 | Eine kanonische Concept-ID-Normalisierungsform + eine erlaubte Linkform | AD-7a/7b | F-2 |
|
||||
| R5 | Deterministische Area-Zuordnung für neue Concepts | AD-7c | F-2 |
|
||||
| R6 | Rename als neues Objekt + Redirect/Deprecation in log.md | AD-7d | F-2 |
|
||||
| R7 | Claim-granulare Provenienz; `sources` nie auf `wiki/`-Pfade; Q-1 → Regel | AD-4a–4c | F-3 |
|
||||
| R8 | AD-16-Generalvorschrift: Bewahrung als Default; Klassifikation publik, an Mutation gebunden | AD-16a/16b | F-4, F-7 |
|
||||
| R9 | Dirty-Tree-Schutz; Commit-Grenze als Mutationsgrenze; Verdrängung dokumentieren | AD-17e/17f | F-5 |
|
||||
| R10 | `schema/wiki-compiler.md` verbindlich; log.md-tipbar; FT-1 mechanisch | AD-1a–1c | F-6 |
|
||||
| R11 | Auflösungs-Autorität + Determinismus-Contract (gleicher Zustand → gleiches Bundle) | AD-17g/17h | F-7 |
|
||||
|
||||
---
|
||||
|
||||
*Ende des Adversarial Reviews.*
|
||||
+134
@@ -0,0 +1,134 @@
|
||||
# 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.
|
||||
+179
@@ -0,0 +1,179 @@
|
||||
# Reconciliation Review — PRD vs. Architecture Spine
|
||||
|
||||
- PRD: `D:\mita\wow-2nd\_bmad-output\planning-artifacts\prds\prd-wow20-2026-08-14\prd.md`
|
||||
- Spine: `D:\mita\wow-2nd\_bmad-output\planning-artifacts\architecture\architecture-wow20-2026-08-14\ARCHITECTURE-SPINE.md`
|
||||
- Reviewer: reconcile reviewer (independent)
|
||||
- Date: 2026-08-14
|
||||
- External verification: OKF 0.2 SPEC (GoogleCloudPlatform/knowledge-catalog `okf/SPEC.md`) fetched and checked for the `log.md` convention.
|
||||
|
||||
---
|
||||
|
||||
## 1. Coverage of FR-1..FR-16 and NFR-1..NFR-7
|
||||
|
||||
| ID | Requirement (short) | Spine coverage | Category |
|
||||
|---|---|---|---|
|
||||
| FR-1 | Sources bereitstellen (local material, no URL fetch) | AD-2, AD-3, AD-12 + Capability Map | **AD/CC** |
|
||||
| FR-2 | Sources vs. Curated Knowledge unterscheiden | AD-2 | **AD** |
|
||||
| FR-3 | Provenienz bewahren | AD-4 + CC `Provenance` | **AD** |
|
||||
| FR-4 | Sources gegen bestehendes Wissen verarbeiten | AD-4, AD-5 | **AD** |
|
||||
| FR-5 | Concepts erzeugen | AD-5, AD-7 | **AD** |
|
||||
| FR-6 | Bestehende Concepts aktualisieren | AD-5, AD-7 | **AD** |
|
||||
| FR-7 | Wissen synthetisieren | AD-4, AD-5, AD-16 | **AD** |
|
||||
| FR-8 | Widersprüche sichtbar behandeln | AD-16 (+ AD-4 provenance of disagreements) | **AD** |
|
||||
| FR-9 | OKF-0.2-konforme Concepts | AD-1, AD-15, CC `Concept format` | **AD/CC** |
|
||||
| FR-10 | Concepts miteinander verlinken | AD-8, CC `Concept relationships` | **AD** |
|
||||
| FR-11 | Progressive Discovery | AD-9 | **AD** |
|
||||
| FR-12 | Inkrementell weiterentwickeln | AD-5 (+ AD-14 history) | **AD** |
|
||||
| FR-13 | Menschliche Kuratierung berücksichtigen | AD-15 | **AD** |
|
||||
| FR-14 | Änderungen nachvollziehbar (Git) | AD-14, CC `Update history` | **AD** |
|
||||
| FR-15 | Tool-unabhängiger Zugriff | AD-1, AD-8, AD-9 | **AD** |
|
||||
| FR-16 | Consumer vom Compiler entkoppeln | AD-10, AD-13 | **AD** |
|
||||
| NFR-1 | Portability | AD-1 + FT-7 | **AD** |
|
||||
| NFR-2 | Human Readability | AD-15 binds NFR-2, CC `Concept format` | **AD/CC** |
|
||||
| NFR-3 | Agent Readability | AD-8, AD-9, AD-13 (binds FR-15) | **AD (partial)** |
|
||||
| NFR-4 | Version-Control Friendliness | AD-14 | **AD** |
|
||||
| NFR-5 | No Mandatory Runtime | AD-1, AD-11 + FT-1 | **AD** |
|
||||
| NFR-6 | Vendor Independence | AD-10 + CC `Agent-specific behavior` | **AD** |
|
||||
| NFR-7 | Graceful Partial Knowledge | AD-4, AD-16 (both bind NFR-7) | **AD** |
|
||||
|
||||
**Verdict:** Full coverage. No FR or NFR lands in a NO category.
|
||||
|
||||
---
|
||||
|
||||
## 2. Assumptions A-1..A-5 and Guardrails (§ 8) vs. the Spine
|
||||
|
||||
| PRD item | Spine status | Finding |
|
||||
|---|---|---|
|
||||
| **A-1 — Target user / no fully autonomous unchecked process (SM-C3 linked)** | Not referenced | **Not contradicted, but silently not picked up.** No AD/rule addresses the boundary between automation and human oversight/correctability. SM-C3 ("Nachvollziehbarkeit > Autonomie") is never mapped. **GAP — LOW**, shared with OQ-1 below. |
|
||||
| **A-2 — Git-versioned OKF Bundle is canonical state (= § 8.2)** | AD-1 + CC `Canonical knowledge` / `Canonical evidence` | Covered. Clarified: canonical evidence is `raw/`. |
|
||||
| **A-3 — No dedicated GUI in v1** | Not referenced | Not contradicted. Addressed indirectly by AD-11 (no server, agent runtime) and D-7 (no review workflow/UI). AD-17 rule 3 stays CLI/file/git-based. **Adheres by silence; no explicit statement** — LOW. |
|
||||
| **A-4 — Source acquisition is not core; local material only, no URL fetch in v1** | AD-12 + Deferred D-1 | Covered — D-1 explicitly defers HTTP fetch/Context7 etc. until a bottleneck. |
|
||||
| **A-5 — BMAD/Claude Code/Codex/CodeGraph are sources or consumers, not core** | AD-10, AD-12, AD-13, Architectural Boundary (`Only the middle box is Wiki of Wikis`) | Covered. |
|
||||
| **§ 8.1 — OKF used, not replaced; no competing ontology** | AD-1, AD-15, Stack (`Open Knowledge Format 0.2`) | Covered. **Verified externally:** the spine's `log.md` label is a legitimate OKF 0.2 reserved filename (scoped update history, §3.1/§9 of the SPEC), and OKF requires consumers to tolerate unknown extension keys. The spine does **not** invent an OKF dialect. |
|
||||
| **§ 8.2 — Derived indices/caches are not Source of Truth** | AD-1 `Derived` list + FT-4 | Covered. |
|
||||
| **§ 8.3 — Separation of Concerns: Sources → Compilation → Bundle → Consumers** | AD-2, AD-12, AD-13, AD-5; Capability Map | Covered. |
|
||||
| **§ 8.4 — Complexity guardrail (infrastructure only if required for core)** | AD-11, AD-12, AD-13, D-2/D-3/D-4, FT-8 | Covered. |
|
||||
|
||||
**Contradictions:** none found.
|
||||
|
||||
**Silently dropped:** A-1/SM-C3 (human oversight/correctability posture) and (weakly) A-3 (no explicit no-GUI statement). Neither is contradicted, both are just not picked up.
|
||||
|
||||
---
|
||||
|
||||
## 3. PRD-delegated Architecture Tickets (Open Questions 2/3/4), plus OQ-5 and OQ-6
|
||||
|
||||
**PRD OQ-2 — Verification / trust-metadata model → ANSWEred by AD-15**
|
||||
|
||||
- Maps to `generated`, `verified` with `human:` prefix, `status`, `stale_after` (exact OKF 0.2 fields).
|
||||
- v1 default preserved: machine-generated, unreviewed → `generated` set, `verified` unset until human review. PRD's Note-for-PM honored.
|
||||
- The human-workflow side is additionally deferred in D-7 (no dedicated review workflow/UI in MVP), consistent with A-3.
|
||||
- **Status: answered.**
|
||||
|
||||
**PRD OQ-3 — Compilation scope / relevant-concepts discovery → ANSWERED by AD-17 (and AD-11)**
|
||||
|
||||
- AD-17 closes with the functional rationale: relevance must be implemented with textual, deterministic means (grep/ripgrep, Markdown traversal, link-following), not embedding/vector infrastructure, because retrieval is consumer behavior (AD-13). This faithfully executes PRD § 12's explicit request.
|
||||
- **Status: answered.**
|
||||
|
||||
**PRD OQ-4 — Conflict resolution → ANSWERED by AD-16 and AD-17**
|
||||
|
||||
- AD-16: classification (NEW / CONFIRMING / CORRECTING / CONTRADICTING / REDUNDANT); contradictions preserved explicitly, never silently resolved; disagreement sources remain traceable; uncertainty may be part of a concept (FR-8, NFR-7).
|
||||
- AD-17 rule 4: producer-level conflict handling — productive contribution wins, a producer may not delete/rewrite a scope if it would effectively replace another producer's work; otherwise the conflict is documented in `log.md` and left open. This is the full answer (data-level + producer-level) and stays CLI/git/file based per A-3.
|
||||
- **Status: answered.**
|
||||
|
||||
**PRD OQ-5 — Source lifecycle (removal/replacement/revocation) → DEFERRED (D-5), answered at decision level**
|
||||
|
||||
- D-5 explicitly addresses it: "MVP assumes additive Source ingestion; revisit before supporting deletion, superseding or revocation." AD-3 reinforces it: raw sources are immutable, new versions become new/versioned sources, source lifecycle and replacement semantics deferred.
|
||||
- Adherence to AD-4 is preserved (removed sources simply stop contributing).
|
||||
- A "revoked/false source" case is not materially discussed in the spine — D-5 carries the load. Acceptable as a consciously deferred decision, but the PRD asked a substantive product question and the spine only parked it. **Status: deferred with explicit handling; a residual product question remains (see Findings #13).**
|
||||
|
||||
**PRD OQ-6 — Product name → NOT ANSWERED**
|
||||
|
||||
- The spine uses "Wiki of Wikis" functionally in frontmatter and as the PRD companion; no statement on whether it is final product name or project name. The spine is not obligated to answer this (outside its remit), so it is intentionally not answered.
|
||||
- **Status: not answered (arguably out of scope for a build-substrate spine); flag for the broader program, not block the spine.**
|
||||
|
||||
---
|
||||
|
||||
## 4. Non-Goals (§ 5) and MVP Out-of-Scope (§ 6.2) — re-admission check
|
||||
|
||||
| Non-goal / out-of-scope item | Spine posture | Re-admitted? |
|
||||
|---|---|---|
|
||||
| Vector database | Stack (`none`), D-2, AD-13 (vector search is consumer-side) | **No** |
|
||||
| Knowledge graph database | AD-8 (graph is optional derivation, never canonical) | **No** |
|
||||
| General RAG platform / retrieval-as-core | AD-13 + Retrieval-replacement FT-3 | **No** |
|
||||
| Enterprise search / KM suite | not touched; boundary diagram keeps core small | **No** |
|
||||
| Web UI / Wiki rendering server / server runtime | AD-11 (`kein eigener Serverprozess`), Stack (`Server runtime none`) | **No** |
|
||||
| MCP server | Stack (`MCP none`), D-4 | **No** |
|
||||
| Automatic internet research / webcrawler | AD-12, D-1 | **No** |
|
||||
| Automatic scheduling / source observation | D-6 (stale detection deferred) | **No** |
|
||||
| BMAD / Claude-Code / CodeGraph integration (as core) | AD-10, AD-12 consumed into `raw/` as sources; AD-13 lists CodeGraph as consumer-side | **No** |
|
||||
| Multi-user rights / enterprise governance | absent from core; AD-17 is lease/git-level, not auth | **No** |
|
||||
| Own OKF dialect / additional knowledge schema | AD-1 (`exclusively OKF-0.2`), AD-15 (one data model), Stack; `log.md` verified OKF-native | **No** |
|
||||
| Vector embeddings, vector search | Stack, D-2 | **No** |
|
||||
| Retrieval as core behavior | AD-13 states the doctrine | **No** |
|
||||
| Block-until-resolution (mandatory waiting) | AD-16 preserves conflicts; AD-17 surfaces them in `log.md` — no blocking mechanism anywhere | **No** |
|
||||
|
||||
**Verdict:** the spine strictly preserves the scope. No non-goal is re-admitted. The principle "future functions may become integrations around the compiler" (§ 6.2) is implemented through the D-1/D-2/D-4 deferred entries.
|
||||
|
||||
---
|
||||
|
||||
## 5. Quiet Requirements
|
||||
|
||||
**5a. Core value promise — synthesis rather than copy (FR-2 / SM-2)**
|
||||
|
||||
Preserved: AD-2 (`Eine Kopie des Quelldokuments ist keine Compilation`), AD-4 (source-grounded synthesis), AD-5 (incremental, not regenerate-all), AD-16 (reconciliation, not concatenation). SM-2 is not mapped explicitly, but FR-5/FR-7 carriers carry it. **Preserved.**
|
||||
|
||||
**5b. Graceful partial knowledge (NFR-7)**
|
||||
|
||||
Preserved: AD-4 (may not treat own syntheses as new evidence) and AD-16 (uncertainty may be part of a concept; contradictions preserved) both bind NFR-7. **Preserved — this is the strongest carry. Exception: OQ-1/AD-4 (may a generated concept be the sole provenance of another generated concept) is left as an open question, so in one edge, grounding of partial knowledge is not fully closed.**
|
||||
|
||||
**5c. "Retrieval is consumer behavior" doctrine**
|
||||
|
||||
Elevated to a first-class AD (AD-13), reinforced by AD-8/AD-9/AD-11 and D-2. The spine also applies it defensively to relevance determination (AD-17), which is a faithful interpretation of PRD § 12. **Preserved and made architecturally load-bearing.**
|
||||
|
||||
---
|
||||
|
||||
## Findings
|
||||
|
||||
### HIGH
|
||||
|
||||
1. **Open Question 6 (product name) is not answered anywhere in the spine and is silently absent.** The spine uses "Wiki of Wikis" as if settled. This is likely out of remit for a build-substrate spine, so it is recorded here for the program rather than raised as a rejection. `ARCHITECTURE-SPINE.md` frontmatter `name: Wiki of Wikis`.
|
||||
|
||||
2. **Open Question 5 (source lifecycle) is only deferred (D-5), not answered.** The PRD asked a substantive product question ("Was geschieht mit Wissen, wenn eine Source entfernt…wird?"). The spine stops at "additive only, revisit later." Acceptable as an explicit deferral; the full product answer remains open across all ADs.
|
||||
|
||||
### MEDIUM
|
||||
|
||||
3. **`raw/` is called immutable while "Source Lifecycle and Replacement-Semantik bleiben für den MVP deferred" (AD-3).** These two statements are tensioned, not contradictory (immutability holds in the additive MVP; versioned replacement is the deferred exit). Must be reconciled before D-5 is revisited, or "immutable" must be scoped to "immutable for the lifetime of the MVP."
|
||||
|
||||
4. **No single AD or consistency-convention row binds NFR-3 (Agent Readability) explicitly.** NFR-3 is covered only indirectly via AD-8/AD-9/AD-13, whose binds list FR-15 (not NFR-3). In a large agent-generated wiki, NFR-3 deserves an explicit guarantee, e.g., a rule that bundle navigation must not require a specialized tool. Consider AD-9/AD-13 extending their binds to NFR-3.
|
||||
|
||||
5. **SM-C3 (Counter-Metric: comprehensible/correctable > autonomous) and its coupling to A-1 (no fully autonomous unchecked process) are silently dropped.** No AD, convention row, or fitness test carries the "human can intervene/correct" requirement. NFR-2 and D-7 touch it only implicitly. The spine should express the correctability guarantee at least once (e.g., a fitness test: "a human can correct a generated Concept without the compiler erasing the correction" — AD-15's persistence clause almost says this for curation, but not for corrections).
|
||||
|
||||
### LOW
|
||||
|
||||
6. **A-3 (no GUI in v1) is never stated explicitly.** Not contradicted (D-7 and AD-17 are consistent with it), but a spine that claims `binds: FR-1..FR-16, NFR-1..NFR-7` leaves the UI guardrail implicit. Suggest one CC row or an A-binding note. Relatedly, the spine has no explicit "no GUI" line, only the indirect implication.
|
||||
|
||||
7. **Deferred D-5 (source deletion/replacement) is not cross-referenced in AD-3's binds nor in an Open Question entry** (Q-1..Q-3 exist; OQ-5 has no twin). The Deferred section covers the subject, so this is a cross-reference/traceability nit.
|
||||
|
||||
8. **PRD OQ-1 (human-authored, fully manual Concepts as first-class knowledge) is not explicitly echoed.** AD-15 assumes before reaching consensus: "human curation is represented as OKF Concepts with metadata" is given, which is a reasonable v1 stance (treated as first class), but the spine does not record it as a decision — leaving the spine alive to AD-15's own open-side of Q-3/-D-7.
|
||||
|
||||
9. **The spine's mermaid overview (Design Paradigm) omits the Reconcile/Validate steps shown by AD-5/AD-6** — cosmetic drift between the high-level diagram and the AD text; the detail ADs carry the full flow (Analyze → Reconcile → Plan → Mutate → Validate), so this is purely presentation.
|
||||
|
||||
10. **PRD § 12's second forwarded question — Bundle-Layout (Source vs. Curated Knowledge placement)** — is answered by the Structural Seed (`raw/` vs `wiki/`) and CC rows, but the spine never labels that answer with the PRD's exact boundary requirement (FR-2/§ 8.3). Traceability nit: the spine's seed says `raw/` and `wiki/` are "Architekturgrenzen" — the invariant is intact but the PRD anchor is not cited.
|
||||
|
||||
11. **AD-17 rule 3 is German and much more conversational than the rest of the spine**, and its embedded sequence (materialize → disable/lease → mutation scoped → commit + release) is not mirrored in the Consistency Conventions table. It is the longest and most implementation-flavored block; inconsistent with the spine's stated "conceptually not prescribing implementation" register. Worth normalizing into the CC table or restructuring, but not a correctness issue.
|
||||
|
||||
12. **`status` default per OKF 0.2 is `stable` when absent.** AD-15's list (`draft | stable | deprecated`) is correct as allowed values, but combined with the v1 "unreviewed by default" posture, an unreviewed Concept could silently default to `stable`. Consider whether the spine wants to mandate `status: draft` (or `generated` + no `verified`) as the explicit v1 default instead of relying on OKF's `stable`-when-absent default. The PRD (§ 4.3 FR-9) delegates field selection to the architecture, so this is a design suggestion, not a coverage gap.
|
||||
|
||||
13. **The "revoked/false source" branch of OQ-5 lacks even a placeholder.** D-5 names deletion, superseding, revocation generically as "revisit," but the spine nowhere sketches what revocation should mean for provenance-weight (the PRD's A-4/SM-3 provenance promise implies some treatment eventually). Not a v1 blocker.
|
||||
|
||||
---
|
||||
|
||||
## Sources not found / notes
|
||||
|
||||
- No FR or NFR is uncovered.
|
||||
- No assumption is contradicted; two assumptions (A-1/SM-C3, weakly A-3) are silently not picked up.
|
||||
- All three PRD-delegated architecture tickets (OQ-2, OQ-3, OQ-4) are answered by ADs; each is cross-checked against the PRD's own Note-for-PM constraints (machine-generated-unreviewed default; CLI/datei-based feasibility).
|
||||
- OQ-5 is deferred (D-5) with explicit handling; OQ-6 is not answered (out of remit).
|
||||
- Non-Goals / MVP Out-of-Scope: no re-admission.
|
||||
- Quiet requirements: synthesis-not-copy (preserved), graceful partial knowledge (preserved, with one open edge behind Q-1), retrieval-is-consumer-behavior (elevated to AD-13 and applied to relevance determination per PRD § 12).
|
||||
- No contradictions with the OKF-0.2 spec; the spine's `log.md` and trust-forecast metadata usage are OKF-conformant (verified against `okf/SPEC.md`), so § 8.1's "no own OKF dialect" guardrail holds.
|
||||
+162
@@ -0,0 +1,162 @@
|
||||
# Rubric Review — Wiki of Wikis Architecture Spine
|
||||
|
||||
Review type: good-spine checklist walker
|
||||
Reviewed artifact: `_bmad-output/planning-artifacts/architecture/architecture-wow20-2026-08-14/ARCHITECTURE-SPINE.md`
|
||||
Row-up PRD: `_bmad-output/planning-artifacts/prds/prd-wow20-2026-08-14/prd.md`
|
||||
Reviewed against: good-spine checklist; capabilities FR-1..FR-16, NFR-1..NFR-7 of the PRD
|
||||
Review date: 2026-08-14
|
||||
|
||||
---
|
||||
|
||||
## Gate verdict
|
||||
|
||||
**CONDITIONAL PASS** — the spine is strong and internally coherent, but it fails to fully close the multi-producer coordination concern (AD-17 is a convention, not an enforced rule), and its Operational Envelope is too thin on security/access and on the operational concurrency and environment envelope. One access A uses the word "Simulation" in a place where an enforced rule is needed, and the "no security" reality needs an explicit, honest decision.
|
||||
|
||||
---
|
||||
|
||||
## Checklist results
|
||||
|
||||
| # | Criterion | Result | Note |
|
||||
|---|---|---|---|
|
||||
| 1 | Fixes the real divergence points for the level below; misses none | PARTIAL | AD-17 identifies the real LWW risk, but the fix is a convention, not an enforcement mechanism (see Finding C-1, C-2). |
|
||||
| 2 | Every AD's Rule is enforceable and prevents its stated divergence | PARTIAL | Rules are mostly enforceable via admission-control tests and fitness tests, but AD-4's Rule 2 ("material claims must remain transitively grounded") is not mechanically checkable without an auditor that follows `sources` transitively. This is the strongest "divergence prevention" gap. |
|
||||
| 3 | Nothing under Deferred lets two units diverge | PASS | D-1 (source acquisition adapters), D-2 (retrieval), D-3, D-4, D-5..D-8 — either explicitly single-producer or consumer-side; none contradict an AD. Note D-7 (human review workflow) is a workflow choice, not a data-model divergence. |
|
||||
| 4 | Named tech is verified-current | PASS | OKF 0.2 confirmed current via direct fetch; Markdown, Git, ripgrep all current/standard. |
|
||||
| 5 | Covers the spec's capabilities (FR-1..16, NFR-1..7) | PASS | Every FR and NFR has at least one governing AD (see coverage table). |
|
||||
| 6 | Every dimension the altitude owns is decided, deferred, or an open question | FAIL | The operational/environmental envelope is incomplete: security/access (team sharing) is silent; environments/deployment are effectively never decided; operational concurrency handling of the lease mechanism on a shared workspace is undefined. |
|
||||
|
||||
---
|
||||
|
||||
## Detailed findings (tiered)
|
||||
|
||||
### Critical
|
||||
|
||||
#### C-1 — AD-17's "Lease" is a convention, not an enforced rule; Last-Writer-Wins is not actually fixed
|
||||
**Where:** AD-17, bullet 3 (line 445-451) and bullet 4 (line 453)
|
||||
|
||||
AD-17's stated prevent is exactly the Last-Writer-Wins problem the rubric asked about: two producers (Claude, Codex, or the human) mutating the same concept path simultaneously. The cited mechanism is:
|
||||
|
||||
- Each producer works in its own branch/worktree and resolves conflicts at Git level (rebase/merge) itself (rule bullet 1).
|
||||
- The compiler only consumes committed content (rule bullet 2).
|
||||
- "He'd'den applies: acquire lease, mutate only within leased area, release lease; conflict resolution by productive value logged in `log.md`" (rule bullet 3-4).
|
||||
|
||||
The problem:
|
||||
|
||||
1. The word "Lease" is a word, not a mechanism. There is no definition of how a lease is acquired, how it is held exclusive, how it is released, or what happens when the acquiring producer dies holding the lease. On a plain filesystem+Git workspace there is no enforcement primitive for exclusivity; two producers contended on the same path in two worktrees will both commit, and Git merge will either produce a conflict (both edited the same line — then the productive-value principle in `log.md` is an advisory that no process enforces) or a clean merge by LWW semantics if they edited different lines of the same file.
|
||||
2. Rule bullet 1 says conflict resolution happens **at Git level by the producer itself** — that reintroduces exactly the LWW/second-writer-wins the AD claims to prevent: there is nothing that prevents producer B from silently overwriting producer A's concept path with its own diff, because "productive check via log.md" is a human-opinion algorithm, not a checkable invariant.
|
||||
3. The compiler itself (mutator) is invoked by the adapter (agent). The AD says convergence is "orchestrated by the executing adapter" — but with no executable lease protocol, nothing stops two adapters from running concurrently against the same repo. The result is exactly the LWW silent overwrite the AD says it prevents.
|
||||
|
||||
Grades:
|
||||
- **Enforceability:** No. A reviewer following the Rule mechanically cannot verify compliance at commit time without a lease table that is itself a derived artifact contradicting AD-1's "derived artifacts are not source of truth", and even then nothing enforces it.
|
||||
- **Divergence prevented:** Not fully. This is the single most important gap in the whole spine.
|
||||
|
||||
Recommended fix (before implementation):
|
||||
- Replace the prose lease with a minimal, mechanically checkable protocol: e.g., a `locks/<concept-path>.lease` convention (a file whose presence means "leased", whose content is producer + timestamp + expected completion, whose existence is checked by the compiler entrypoint and by every commit hook), plus a hard rule that a commit that touches a path where the lease is not held by the committing producer is rejected by a pre-commit hook. If "no runtime" is sacred, the lease must be a file, not a memory object; a git commit hook reading a small text file is a normal file operation, consistent with the no-runtime philosophy.
|
||||
- Alternatively, explicitly downgrade AD-17 to a single-writer-acknowledged model ("the compiler assumes only one producer at a time; if two producers contend, the human resolves at Git level and the result is LWW for that path") and say so. That would at least be honest and enforceable; the current text implies more safety than the mechanism provides.
|
||||
|
||||
#### C-2 — Two producers, two worktrees, same repo: each branch holds the whole bundle; the term "Won't run concurrently" is NEVER stated
|
||||
**Where:** AD-17 rule bullet 1; also AD-6, AD-3
|
||||
|
||||
There is no statement anywhere that the compiler is single-instance. AD-17's own scenario ("Claude, Codex, or the human") is three possible producers; nothing in the spine limits the number of simultaneous compilation runs that may feed the same bundle. If the intent is single-writer serialized runs, that intent is nowhere made explicit, and the reader cannot distinguish "concurrent adapters are coordinated by the lease", which is claimed, from "concurrent adapters are inherently excluded", which is not claimed and would be desirable to state.
|
||||
|
||||
Fix: add an explicit statement in AD-17 (or an AD-17a): "At most one compilation run may be active against the shared workspace at a time; runs are serialized by file-lock or by the existence of a `locks/`-style lease." If this is a hard design constraint, the spine must say so; otherwise the claim that LWW is prevented overstates a mechanism that does not exist.
|
||||
|
||||
### High
|
||||
|
||||
#### H-1 — Operational Envelope is thin: security/access for the team case is silent; environments never decided
|
||||
**Where:** "Operational Envelope" section (lines 564-590); PRD A-1 (§ 2.1 assumption: "primär ein persönliches bzw. teaminternes Developer Tool")
|
||||
|
||||
The envelope covers only Local-first execution, Failure behavior, Portability. The checklist specifically asks about failure behavior, security/access, environments:
|
||||
|
||||
- **Security / access (team case):** The PRD's own assumption A-1 says the product is a "persönliches bzw. teaminternes Developer Tool" — the primary user is "ein technisch versierter Wissensarbeiter bzw. Softwareentwickler." If team-internal, then "who writes" (push permissions to `raw/` and `wiki/`; who may produce leases; who may mark `verified`) is a real divergence point the architecture owns. The spine is silent on all of it. Git-level collaboration (a shared repo) is the natural answer, but the spine never states that the team access story is "Git repository permissions" vs. "anyone with filesystem access", nor what the boundary is for `raw/` (immutable evidence) vs `wiki/` (mutable) from a writes standpoint. A team member editing `wiki/` directly is allowed per AD-15/Q-2, but nothing governs concurrent human-vs-compiler writes beyond AD-17 (which is underexplained as a mechanism — see C-1).
|
||||
- **Environments / deployment / CI:** The spine says nothing at system level about `main` vs worktrees, about a shared remote, about where compiled bundles are published, about promotion (e.g., lease branch → merge → main). Since the spine binds Git, environment decisions (which branch is canonical read-surface, whether compilation runs on `main` or on a branch that is later merged) are a real divergence point for multiple consumers reading "the wiki" — two consumers polling different branches see different knowledge. This should be explicitly decided or explicitly deferred (it is neither).
|
||||
|
||||
Impact: this is dimension (6) in the rubric — a whole dimension left silent. For a single-user local tool it would be acceptable; for a team-shared Git workspace it is a finding.
|
||||
|
||||
#### H-2 — AD-4 Rule 2 (transitive grounding) is not mechanically enforceable
|
||||
**Where:** AD-4 Lines 112-140; fitness test FT-5, FT-4
|
||||
|
||||
The Rule says "materielle fachliche Aussagen müssen auf nachvollziehbare Sources zurückgeführt werden" and "Bei einer Synthese aus mehreren Concepts wird relevante Source-Provenienz in das resultierende Concept übernommen." FT-5 ("its material source basis can be traced to actual Source Material") is the test, but nothing specifies a mechanical check that a synthesized concept actually carries provenance that reaches a `raw/` file. As written it is a semantic preference, not a verifiable invariant: a compiler could produce a concept with `sources` referencing another concept's ID only, and no admission check would fail.
|
||||
|
||||
Fix: define the check as part of the Compiler contract (schema/wiki-compiler.md): for every generated concept, `sources` entries must resolve (transitively, bounded depth) to at least one source under `raw/` (or a documented external immutable reference); a concept whose entire `sources` chain terminates in other concepts fails validation and the run fails (or the concept is downgraded). This is checkable with grep/traversal — consistent with the "no runtime/vector infra" constraint.
|
||||
|
||||
### Medium
|
||||
|
||||
#### M-1 — Consistency Conventions table "Erstellt von" / "Errors" entry is gray
|
||||
**Where:** "Consistency Conventions" table, row "Errors" (line 474): "kein erfolgreicher Run bei ungültigem Bundle"
|
||||
|
||||
In AD-6 (Overlap with AD-6) — acceptable summary, but the table generalizes to "invalid bundle" with no definition of what validates it and who runs validation. Combined with H-2, the table promises an acceptance gate that the document does not give a mechanism for. Minor: the row belongs to the "no-proprietary-format" axis and would be more useful as "validation = OKF conformance + AD-4 grounding, implemented as committed checks in schema/". Recommend rewording to name the artifact that performs it.
|
||||
|
||||
#### M-2 — AD-16 "classifies new information" is conceptual only; "Relevance determination" reference leaks implementation
|
||||
**Where:** AD-16 lines 419-434; AD-17 "Wichtig — funktionaler Grund" (line 455)
|
||||
|
||||
AD-16 says the classification "ist konzeptionell; sie schreibt keine konkrete interne Datenstruktur vor" — good and consistent with AD-6. But the "Wichtig" note in AD-17 (line 455) makes a strong causal claim: "Relevanzbestimmung (PRD OQ-3...) ist begrenzt: Sie muss mit textuellen, deterministischen Mitteln (grep/ripgrep, Markdown-Traversal, Link-Following) umgesetzt werden, nicht mit Embedding- oder Vector-Infrastruktur." This is correct and consistent with AD-13, but it belongs in AD-5/AD-13 (relevance determination is a compilation-input concern, not producer mechanism) rather than AD-17, where a reader of AD-17 is unlikely to look for it. The PRD explicitly hands this decision to the architecture (PRD § 12), and the spine does answer it — but in the wrong section. Reorganize: relevance determination deserves its own AD-18 (or a bullet in AD-5) so the "how does the compiler find relevant existing concepts" answer is not buried in the leasing AD.
|
||||
|
||||
### Low
|
||||
|
||||
#### L-1 — AD-11 label "AD-11 — Agent runtime provides reasoning; Wiki of Wikis provides protocol" is a naming shift from "protocol" semantics
|
||||
**Where:** AD-11
|
||||
|
||||
The title implies WoW "provides protocol", but the SVG/diagram and rule text describe WoW as instructions ("kanonische Compiler-Regeln"), not a wire protocol. If it is an *agent-instruction contract* (which AD-10 says, correctly), the title should say "Compilation Contract" rather than "protocol", to avoid implying a wire/serialization protocol where none is designed. Cosmetic, but affects how a downstream implementer reads the boundary.
|
||||
|
||||
#### L-2 — Missing explicit statement tying D-7 (Human review workflow) to a resolved OQ
|
||||
**Where:** D-7 (line 707-713) with PRD OQ-2 (§ 10), AD-15
|
||||
|
||||
PRD OQ-2 ("Verification Workflow") is answered in the PRD's own NOTE FOR PM ("v1-Default ist maschinell erzeugt und ungeprüft") and mirrored in AD-15. D-7 correctly defers the workflow itself. This is coherent, but the spine never states which PRD OQ each AD resolves — adding a small column ("Resolves/answers") mapping the six PRD OQs (and § 12's two handed-off questions, which are answered in AD-17's note and hence belong elsewhere per M-2) would let a reviewer see at a glance that no PRD open question is left dangling. It also would have made M-2 visible earlier.
|
||||
|
||||
---
|
||||
|
||||
## Coverage verification (checklist item 5)
|
||||
|
||||
Every FR and NFR of the PRD has at least one governing AD; the spine's Capability → Architecture Map (lines 518-537) is accurate and complete. Cross-check against the PRD:
|
||||
|
||||
| Capability | Spine's governing AD(s) | Also relevant |
|
||||
|---|---|---|
|
||||
| FR-1 Source intake | AD-2, AD-3, AD-12 | AD-17 rule 2 (immaterial during run) |
|
||||
| FR-2 Source/Knowledge separation | AD-2 | |
|
||||
| FR-3 Provenance | AD-4 | AD-16 (preserve provenance in contradictions) |
|
||||
| FR-4 Existing knowledge processing | AD-5 | |
|
||||
| FR-5 Concept creation | AD-5, AD-7 | AD-1 |
|
||||
| FR-6 Concept update | AD-5 | AD-4 |
|
||||
| FR-7 Cross-source synthesis | AD-4, AD-5 | |
|
||||
| FR-8 Contradictions | AD-16 | |
|
||||
| FR-9 OKF compliance | AD-1 | AD-15 (trust metadata) |
|
||||
| FR-10 Relationships | AD-8 | |
|
||||
| FR-11 Progressive discovery | AD-9 | |
|
||||
| FR-12 Incremental evolution | AD-5 | |
|
||||
| FR-13 Human curation | AD-15 | |
|
||||
| FR-14 Change history | AD-14 | |
|
||||
| FR-15 Tool-independent access | AD-1, AD-8, AD-9 | AD-13 |
|
||||
| FR-16 Consumer independence | AD-10, AD-13 | |
|
||||
| NFR-1 Portability | AD-1 | Operational Envelope (Portability) |
|
||||
| NFR-2 Human readability | AD-15 | Consistency table |
|
||||
| NFR-3 Agent readability | AD-1, AD-9 | AD-13 |
|
||||
| NFR-4 Version-control friendliness | AD-14 | |
|
||||
| NFR-5 No mandatory runtime | AD-1, AD-11 | Stack table |
|
||||
| NFR-6 Vendor independence | AD-1, AD-10, AD-11 | Stack table |
|
||||
| NFR-7 Graceful partial knowledge | AD-4, AD-16 | |
|
||||
|
||||
No gaps. All 16 FR + 7 NFR covered.
|
||||
|
||||
## Tech currency (checklist item 4)
|
||||
|
||||
Verified via direct fetch of `https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md`: the current OKF version is **0.2** (matching the PRD's § 13 reference). Key OKF-0.2 facts used by the spine are accurate: `type` is the only required frontmatter key; `timestamp` was superseded by `generated.at` (the spine never uses `timestamp` — good); `sources` supersedes the body-level `# Citations` list (the spine uses `sources` — consistent); `verified` absent means unverified; `status` default `stable`; `okf_version` only allowed in bundle-root `index.md`; `references/` is a naming convention, not a requirement; conformance rule that consumers MUST NOT reject bundles for missing optional fields / unknown keys / broken links / missing `index.md` — all consistent with AD-1/AD-15/AD-16 phrasing.
|
||||
|
||||
Note: OKF 0.2 gotcha — the spec says `index.md` and `log.md` are RESERVED filenames that "MUST NOT be used for concept documents". The spine uses `wiki/log.md` (line 490) for disagreements/history (AD-16 line 433). That is consistent with the reserved-name contract (a `log.md` that is not a concept is fine per spec), but the spine never states this distinction; a naive implementer could treat `log.md` as a concept and fail OKF conformance. Add one sentence to AD-16/AD-14: "`log.md` and `index.md` are reserved non-concept filenames per OKF; they must never carry a `type`." Low/severe depending on validator strictness.
|
||||
|
||||
## Placeholder / hygiene check (added at request)
|
||||
|
||||
- No duplicate AD-IDs; no `TODO`/`FIXME`/`TBD`/placeholder text found (grep -i). AD-1..AD-17 each has a unique, descriptive title.
|
||||
- Every AD carries Binds/Prevents/Rule (AD-11/AD-12 "Binds" uses 'MVP'-style target but structure present). All ADs have a matching `[ADOPTED]` or `[ASSUMPTION]` tag (8 assumptions, 9 adopted). Challenge: AD-4, AD-6, AD-11 are assumptions but their Rules read as normative ("Ein Compilation Run muss …") — the tag versus the certainty of the Rule body is inconsistent; potential reader confusion about whether AD-4's grounding is assumed or required. Medium-touch: retag to `[ADOPTED]` if the Rule is truly binding, or soften the Rule text if it's exploratory.
|
||||
- Status field says "draft" (frontmatter line 8) while content reads as adopted; fine for a spine artifact in progress, but flag for the level below that the spine is not final.
|
||||
|
||||
---
|
||||
|
||||
## Summary of stops to fix before the next level
|
||||
|
||||
1. **AD-17 mechanism** (C-1): turn lease/conflict-convention into a mechanically checkable file-based protocol (lease file + commit hook) or explicitly downgrade to single-writer serialization. As written, LWW is not actually prevented.
|
||||
2. **Concurrency statement** (C-2): state explicitly "at most one active compilation run / serialization by file-lock" or say concurrent runs are excluded; don't imply safety that doesn't exist.
|
||||
3. **Operational Envelope** (H-1): add a short "Security & Access" subsection for the team-internal case (who writes `raw/` vs `wiki/`, who may mark verified, whether access = Git repo permissions) and state the environment/deployment stance (canonical branch, promotion of lease-branch → main, whether a shared remote exists) as either decided or explicitly deferred.
|
||||
4. **AD-4 enforceability** (H-2): specify the transitive-grounding admission check in the compiler contract (schema/wiki-compiler.md) so FT-5 is real.
|
||||
5. **Relevance-determination placement** (M-2): give the "how does the compiler find relevant concepts with text-only means" answer its own home (AD-5/AD-18), not inside AD-17.
|
||||
6. **OKF reserved filenames** (Low): explicitly note `log.md`/`index.md` are non-concept reserved files.
|
||||
+125
@@ -0,0 +1,125 @@
|
||||
# Technology-Currency Review — Architecture Spine (Wiki of Wikis)
|
||||
|
||||
- **Reviewed file:** `ARCHITECTURE-SPINE.md` (draft, 2026-08-14)
|
||||
- **Reviewer:** technology-currency reviewer (independent)
|
||||
- **Date:** 2026-08-14
|
||||
- **Method:** Every named/committed technology and every cited source was checked against the live web via WebFetch (WebSearch was unavailable due to a persistent API error during this session — all anchors below were therefore verified by direct fetch of the primary sources).
|
||||
|
||||
---
|
||||
|
||||
## Summary verdict
|
||||
|
||||
**No committed decision rests on unverified or stale technology.** The spine leans on exactly two external anchors (Karpathy's LLM-Wiki gist and OKF 0.2's SPEC.md) plus a deliberately unbound stack. Both anchors exist, are current, and match the spine's usage. One characterization nuance is worth recording (see Finding 1), and three secondary technology mentions in examples/diagrams were spot-checked and are live. The "not bound" claims are internally and externally coherent with the agent-independence decisions (AD-10, AD-11, AD-13).
|
||||
|
||||
---
|
||||
|
||||
## 1. Karpathy "LLM wiki" gist — EXISTS, characterization largely accurate, one nuance
|
||||
|
||||
**Source checked:** `https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f`
|
||||
**Status:** Exists. Authored by karpathy (Andrej Karpathy), titled **"llm-wiki"** (`llm-wiki.md`), created 2026-04-04, framed as "A pattern for building personal knowledge bases using LLMs" / "an idea file... designed to be copy pasted to your own LLM Agent."
|
||||
|
||||
What the spine attributes to it and what the gist actually says:
|
||||
|
||||
| Spine claim (AD-2/AD-3/structural seed) | Gist reality (verified) |
|
||||
|---|---|
|
||||
| Raw sources are immutable, LLM only reads them | **Confirmed verbatim:** "These are immutable — the LLM reads from them but never modifies them." Raw sources are "your source of truth." |
|
||||
| Curated wiki as persistent, compounding artifact | **Confirmed:** "the wiki is a persistent, compounding artifact"; "LLM incrementally builds and maintains a persistent wiki." Matches AD-5 (incremental compilation). |
|
||||
| Three-layer model raw / wiki / schema | **Confirmed:** Raw sources, the wiki (LLM-owned markdown), the schema (config, e.g. CLAUDE.md). Matches the spine's `raw/` + `wiki/` boundaries and the compiler contract concept. |
|
||||
| `index.md` and `log.md` | **Confirmed both, with exact roles:** `index.md` "is content-oriented. It's a catalog of everything in the wiki." `log.md` "is chronological. It's an append-only record of what happened and when." Matches AD-9 (progressive discovery via `index.md`), AD-16 and AD-17 (`log.md` documented disagreements), and the structural seed. |
|
||||
| Provenance | **Nuance (Finding 1):** the gist body does **not** use the word "provenance"; traceability is only implied ("The cross-references are already there. The contradictions have already been flagged."). The word appears in the comment thread (AbleVarghese's "Provenance-First-Wiki", drjoeshepherd's SIGN spec). AD-4/AD-16's provenance emphasis is a reasonable inference from the gist, but it is an interpretation, not a verbatim gist feature. |
|
||||
| Wiki pages not self-grounding (AD-4 core rule) | **Nuance (Finding 1):** the gist body does **not** forbid wiki-as-grounding — it positively encourages filing outputs back in ("good answers can be filed back into the wiki as new pages"). The "a page can never be another page's grounding" rule comes from **drjoeshepherd's SIGN spec in the comments**, and the "wiki gradually cites itself" failure mode comes from AbleVarghese in the comments. The spine's "generated concepts must remain source-grounded and wiki-to-wiki links are not provenance" rule (AD-4, AD-16, Q-1) is a **stronger policy than Karpathy's gist states** — defensible, aligned with the gist community's feedback, but it should be documented as the spine's own stance / derived from gist-discussion literature, not presented as its only source of support. |
|
||||
|
||||
**Verdict: source is real, current, and the spine's account is materially accurate.** Finding 1 below is a characterization nuance only — it neither invalidates AD-2/3/5/9/16/17 nor AD-4, but the spine's `sources:` frontmatter and AD-16 wording imply the provenance/self-grounding stance is gist-native, which it is not verbatim.
|
||||
|
||||
---
|
||||
|
||||
## 2. Open Knowledge Format 0.2 — CURRENT and spine account matches
|
||||
|
||||
**Source checked:** `https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md` (file exists in `okf/`; README links it as "Open Knowledge Format v0.2 specification"), plus repo-level profile via `googlecloudplatform/knowledge-catalog`.
|
||||
|
||||
**Version currency:**
|
||||
- SPEC.md states **"This document specifies OKF version 0.2"** — the fetched SPEC text confirms v0.2. The `okf/` README also references "v0.2 puts queryable signals in frontmatter."
|
||||
- No newer version (0.3/1.0) is referenced anywhere in the repo or spec. A 0.3+/1.0 spec search was attempted but WebSearch was down; direct primary-source fetches surfaced no newer version. **Verdict: 0.2 is the current version the spine relies on** (with the caveat that repo activity/commit dates could not be rendered in the fetch).
|
||||
|
||||
**Spine account vs. spec (each claim checked):**
|
||||
|
||||
| Spine claim | Spec fact (verified in SPEC.md text) |
|
||||
|---|---|
|
||||
| "type is the only required frontmatter key" | **Confirmed:** "`type` is the only always-required key; a concept carrying just `type` is fully conformant." |
|
||||
| `sources` / `generated` / `verified` / `status` / `stale_after` as optional families | **Confirmed:** all are optional provenance/trust/lifecycle families; "All are optional." Absence conveys meaning (no `verified` ⇒ unverified) but "never causes rejection." |
|
||||
| `verified` with `human:`-prefix actor (AD-15) | **Confirmed:** trust tiers derive from actor prefix; `verified` by a `human:<id>` actor ⇒ human-reviewed; "producers MUST use it for hand-authored or human-confirmed content." `generated: { by, at }` (with `generated.at` superseding the old `timestamp`) matches AD-15's `generated: { by, at }`. |
|
||||
| `status` values `draft` / `stable` / `deprecated`, optional `stale_after` (AD-15) | **Confirmed:** `status` and `stale_after` are in the lifecycle family and optional; the listed status values align with the spec's lifecycle framing. |
|
||||
| `okf_version` only in bundle-root `index.md` (AD-7 context) | **Confirmed:** `okf_version` "is only permitted in a bundle-root index.md frontmatter block" — described as the only place frontmatter is permitted in an index.md. |
|
||||
| `references/` convention (used in AD-2/seed discussions of external material) | **Confirmed as convention, not requirement:** "A `references/` subdirectory conventionally mirrors external material, run instructions, or code as first-class concepts within the bundle." |
|
||||
| Consumers must tolerate missing optional fields (AD-8, FT-1...FT-7, AD-13 retrieval-by-consumers) | **Confirmed:** "Consumers MUST NOT reject a bundle for missing optional frontmatter fields, unknown `type` values, unknown additional frontmatter keys, broken cross-links, or missing `index.md` files"; unknown keys must be preserved on round-trip. |
|
||||
|
||||
**Storage/backing fact worth noting:** The `knowledge-catalog` repo README descends from Google's Dataplex-related "Knowledge Catalog" platform lineage, but the `okf/` subfolder is an independent, permissively-licensed (Apache 2.0) open format with a reference agent and samples. The spine's use of OKF as "canonical knowledge state" (AD-1) is consistent with the spec's framing (concept = file + frontmatter, bundle = directory tree). No contradiction found.
|
||||
|
||||
**Verdict: OKF 0.2 is current, exists, and the spine's account of it is accurate on every checked claim (AD-1, AD-7, AD-9, AD-15, AD-16, consistency conventions, stack table).**
|
||||
|
||||
---
|
||||
|
||||
## 3. "Not bound" choices vs. agent-independence (AD-10, AD-11, AD-13)
|
||||
|
||||
The spine's MACRO stack table explicitly lists as **not bound / none required**: LLM, Agent runtime, Programming language, Database, Vector database, Server runtime, MCP.
|
||||
|
||||
**No hidden assumption contradicting agent-independence was found.** Concretely:
|
||||
|
||||
- The single external commitment the compiler actually makes is **the agent-agnostic contract itself** — Markdown + YAML frontmatter, OKF bundle files, Git, standard Markdown links (AD-8), and textually specified canonical rules. None of these is LLM/agent/framework-specific.
|
||||
- AD-10: rules are described as canonical and agent-independent; adapters (claude/codex/other) are described as thin, semantically non-divergent. The structural seed's `adapters/` folder and the "Canonical compiler contract" diagram contain **only** claude + codex as named examples, explicitly marked "Other adapter" — this is example-and-diagram material, not a binding on a specific agent. The `sources:`/companions frontmatter likewise contributes no agent binding.
|
||||
- AD-11: explicitly says no own LLM runtime and "Die konkrete Runtime ist austauschbar" (the concrete runtime is exchangeable), "kein eigener Serverprozess erforderlich" (no own server process required). This is compatible with the pattern itself being agent-runtime-hosted (Karpathy's gist is also intentionally runtime-agnostic: "instantiated collaboratively with your LLM of choice").
|
||||
- AD-13: retrieval (grep/ripgrep, BM25, vector, CodeGraph) is consumer-side and rejects search/RAG as architecture center. The listed consumer-side options are all existing, real categories (ripgrep, BM25 are standard; BM25 doesn't need a specific library in this decision). No hidden vector/embedding dependency is introduced.
|
||||
- **MCP:** spine says "none required" (D-4 deferred). This matches verified reality — MCP is a widely used integration standard in 2026, but the spine never requires it; and Karpathy's own gist explicitly supports a CLI/skills path "no MCP required" (per Context7's own documented modes, the same "no MCP required" pattern is standard practice). Removing all MCP components (FT-1) leaves a plain Git working copy.
|
||||
- **Consistency check (internal):** AD-15's "v1-Default... maschinell erzeugt und ungeprüft, d.h. Trust-Metadaten nur über `generated`, und `verified` bleibt ungesetzt" maps directly onto OKF's confirmed rule (no `verified` ⇒ unverified; machine ⇒ `generated` only). This internal stance is fully OKF-0.2-consistent — not a hidden framework assumption.
|
||||
|
||||
**Verdict: no hidden LLM/agent/framework commitment contradicts the independence claims.** The only "living" assumptions are generic capabilities any current agent runtime provides (read/write files, search, reasoning; AD-11) — these are stated, not hidden.
|
||||
|
||||
---
|
||||
|
||||
## Secondary technology mentions — spot-checked (all live, current)
|
||||
|
||||
These appear only as examples/consumer-side options (AD-12 diagrams, AD-13 list, architecture-boundary diagram), not as committed stack:
|
||||
|
||||
- **Context7 (upstash/context7)** — exists, actively maintained (60.7k+ stars, ~929 commits), Upstash's "up-to-date code documentation for LLMs"; provides CLI + MCP modes and a live hosted service. Matches AD-12's use as an example source-acquisition adapter. **Live.**
|
||||
- **arc42** — exists, open source, "proven in practice since 2005," free including commercial use (CC BY-SA 4.0), 12-section architecture template. Matches AD-12's use as an example source (architecture docs). **Live.**
|
||||
- **CodeGraph** (referenced in AD-13 consumer-retrieval list and boundary diagram) — the name maps to the local-first code-knowledge-graph tooling category (tree-sitter + SQLite + MCP) that this very environment has indexed (`codegraph` MCP), which matches "reads the bundle, doesn't change canon" usage. **Live category**, and appropriate as a consumer-side optional reader. Minor, cosmetic note: "CodeGraph" is a generic name with multiple independent implementations, not one canonical product — as a consumer-side example this is harmless (nothing is bound), but the naming is not a registered single-owner product name.
|
||||
- **BMAD** (companion/tool used to produce this artifact) — internal tooling, present in the repo working tree; not an external technology claim. **N/A.**
|
||||
- **Git** / **Markdown** / **YAML frontmatter** — generic, universally current; no version pin needed for this decision. **N/A.**
|
||||
|
||||
---
|
||||
|
||||
## Findings
|
||||
|
||||
### Finding 1 (Low — characterization nuance, no correction required)
|
||||
**The provenance / "wiki pages must not self-ground" rules are the spine's own stronger stance, derived from the gist's comment-thread literature, not verbatim from Karpathy's gist.**
|
||||
- Gist body: no "provenance" wording; explicitly encourages "good answers can be filed back into the wiki as new pages."
|
||||
- Anti-self-grounding rule ("a page can never be another page's grounding") comes from drjoeshepherd's SIGN spec in the gist comments; "wiki gradually cites itself" failure mode from a commenter (AbleVarghese).
|
||||
- Impact: none on the decisions' validity — AD-4/AD-16 remain sound and are even stricter than the gist — but the spine's `sources:` citation and AD-16 prose imply these are gist-native. Suggest adding a one-line note in the spine's sources/comments ("provenance & no-self-grounding strengthened per gist discussion, citing SIGN-concept") so future readers don't attribute that specific rule to the gist verbatim.
|
||||
|
||||
### Finding 2 (Info — version currency of OKF confirmed with one data gap)
|
||||
OKF **0.2 is current** and everything the spine claims about it checks out. Data gap: GitHub page-rendered commit dates were not retrievable in this session, so I could not timestamp the last spec update; no newer spec version (0.3/1.0) surfaced from any primary source fetched. Re-verify spec's current version status if the MVP starts implementing against it, per repo activity.
|
||||
|
||||
### Finding 3 (Info — CodeGraph is a category, not a single canonical product)
|
||||
AD-13/architecture-boundary name "CodeGraph" as a consumer retrieval option. The name maps to multiple independent implementations (tree-sitter + SQLite + MCP knowledge-graph tools) rather than one canonical product. Harmless for a **not-bound** consumer-side example; no change needed, but be aware the string "CodeGraph" may be ambiguous in future docs if one specific implementation is ever selected (then pin it).
|
||||
|
||||
### Finding 4 (Info — no findings in the "not bound" space)
|
||||
Confirmed: the stack table's "not bound / none" entries contain no hidden LLM/framework/database dependency; AD-10/11/13 are coherent with each other and with OKF 0.2 semantics as verified.
|
||||
|
||||
---
|
||||
|
||||
## Verdict (one line)
|
||||
|
||||
**No committed decision rests on unverified or stale technology** — both cited external anchors (Karpathy's LLM-Wiki gist, OKF SPEC 0.2) exist, are current, and match the spine's usage; the unbound stack is genuinely agent-independent; the only nuance is Finding 1 (provenance/self-grounding are the spine's own stronger stance drawn from the gist's comment literature, not verbatim gist content).
|
||||
|
||||
---
|
||||
|
||||
## Sources consulted (primary, fetched directly)
|
||||
|
||||
- Karpathy, "llm-wiki" gist — https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f
|
||||
- Open Knowledge Format v0.2 SPEC — https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md (confirmed v0.2; no newer version found)
|
||||
- knowledge-catalog repo (version/profile context) — https://github.com/GoogleCloudPlatform/knowledge-catalog
|
||||
- Context7 — https://github.com/upstash/context7
|
||||
- arc42 — https://arc42.org/overview
|
||||
- codegraph category (GitHub repo search) — https://github.com/search?q=codegraph+sqlite+knowledge+graph&type=repositories
|
||||
|
||||
> Review method note: WebSearch was unavailable this session (persistent tool API error), so all verifications were performed via direct WebFetch of the primary sources listed above. Each fetched primary source confirmed the claims cited.
|
||||
Reference in New Issue
Block a user