126 lines
15 KiB
Markdown
126 lines
15 KiB
Markdown
# 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.
|