16 KiB
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 thelog.mdconvention.
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,verifiedwithhuman:prefix,status,stale_after(exact OKF 0.2 fields). - v1 default preserved: machine-generated, unreviewed →
generatedset,verifiedunset 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.mdand 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
-
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.mdfrontmattername: Wiki of Wikis. -
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
-
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." -
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.
-
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
-
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-7leaves 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. -
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.
-
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.
-
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.
-
PRD § 12's second forwarded question — Bundle-Layout (Source vs. Curated Knowledge placement) — is answered by the Structural Seed (
raw/vswiki/) 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 saysraw/andwiki/are "Architekturgrenzen" — the invariant is intact but the PRD anchor is not cited. -
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.
-
statusdefault per OKF 0.2 isstablewhen 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 tostable. Consider whether the spine wants to mandatestatus: draft(orgenerated+ noverified) as the explicit v1 default instead of relying on OKF'sstable-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. -
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.mdand trust-forecast metadata usage are OKF-conformant (verified againstokf/SPEC.md), so § 8.1's "no own OKF dialect" guardrail holds.