feat: implement Knowledge Wiki retrieval layer (pre-generation grounding)

[devfloor9]

Summary

Implement the Knowledge Wiki layer described as a design proposal in docs/docs/knowledge-wiki.md. Today that page is explicitly marked "design proposal, not yet shipped" — this issue tracks turning it into an implemented layer.

Motivation

The Ontology axis validates after generation (oma validate rejects a malformed entity), and the Harness enforces before a tool runs. Neither tells an agent, before it authors a typed artifact, what the domain already knows (existing enums, prior ADR rationale, naming conventions). This is the same root cause behind the canonical "deployment target" drift (one skill meant a cluster name, another meant the eks|ec2|lambda enum) — validation only caught the clash after both documents already diverged.

A semantic retrieval layer queried before generation grounds the agent in established intent, preventing drift at the source instead of catching it at handoff.

Layer positioning (complementary, not competing)

Layer	Question	When it acts	Status
Knowledge Wiki	"what is already known?"	before generation (grounding)	🔭 this issue
Ontology (8 schemas)	"is this true?"	after generation (validation)	✅ shipped
Harness (PreToolUse)	(execution deny)	before a tool runs (enforcement)	✅ shipped

Open design questions (resolve in an ADR before implementation)

1. Source of truth — the wiki MUST derive from the schemas + ADR/Spec docs, never the reverse, or it becomes a competing definition and reintroduces the drift it is meant to prevent.
2. Staleness — a retrieval layer lagging the schemas is worse than none; ingestion must re-run on every ontology change (Inner-Loop hook).
3. Retrieval surface — MCP tool vs. skill vs. build-time index; each has different harness implications.

Acceptance criteria (draft)

• ADR authored resolving the three open design questions above
• Wiki corpus derives from schemas/ontology/ + ADR/Spec documents (one-way)
• Re-ingestion hook wired to ontology changes (staleness guard)
• Retrieval interface decided and implemented per the ADR
• self-improving-loop consumes accumulated domain knowledge as a second input alongside operational signal
• docs/docs/knowledge-wiki.md status banner updated from "design proposal" to shipped

References

• docs/docs/knowledge-wiki.md — the design proposal
• docs/docs/ontology.md — 8-entity schema + evolution rules
• docs/docs/ontology-engineering.md — triple feedback loop the wiki feeds into

---

Detailed implementation to be carried out in a separate working session.

[devfloor9]

Cross-link from a plugin-UX re-verification: the wiki layer should be packaged so /plugin install delivers it (inside aidlc or a new knowledge plugin), not left as repo-root tooling. This is the same delivery gap tracked in #60 — schemas/seed/session-hook currently live outside the plugin dirs and so are not shipped by the marketplace path. Whatever retrieval surface the ADR picks (MCP vs skill vs build-time index), it must land inside a plugin root to satisfy "install a plugin → get the third accuracy layer."

(#61 filed the same request and has been closed as a duplicate of this issue.)

[devfloor9]

Prior art for the ADR: Graphify (graphify.net)

Evaluated Graphify (safishamsi/graphify, MIT, pip install graphifyy) as a reference implementation against this issue's three open design questions. It is a multi-modal knowledge-graph builder (Tree-sitter AST + LLM semantic extraction → NetworkX graph, Leiden community detection, no vector embeddings) that ships as an AI-coding-assistant skill.

It concretely answers two of the three open questions:

Open question (this issue)	Graphify capability
Q2 — Staleness / re-ingestion hook	--update (re-extract changed files, merge) and --watch (auto-sync); on Claude Code it also installs a PreToolUse hook
Q3 — Retrieval surface (MCP vs skill vs build-time index)	Offers all three: /graphify query (skill), --mcp (stdio MCP server), graph.json (persistent build-time index)
Q1 — Source of truth (one-way from schemas/ADR)	Extraction is strictly one-way (code/docs → graph, never writes back) — directionally compatible

It also exceeds the proposal on two points worth folding into the ADR: provenance tagging (every edge marked EXTRACTED / INFERRED / AMBIGUOUS with a confidence score) and rationale nodes (rationale_for edges from docstrings, # WHY: comments, and design discussion) — which is exactly the "decision narratives that structured links cannot hold" path in knowledge-wiki.md. There is even a --wiki mode that emits Wikipedia-style markdown per community.

Why it is prior art, not a drop-in adoption:

1. Scope/shape mismatch. Graphify builds a whole-repo code graph (god nodes, community detection). This issue wants definition retrieval over a narrow curated corpus (schemas/ontology/ + ADR/Spec only) — "what enum values does Deployment.target allow, has this Risk been classified before." Using Graphify here means scoping it to the ontology corpus and using a fraction of its capability; graph-shaped ≠ definition-retrieval-shaped.
2. Maturity / sustainability. Released 2026-04-03, single maintainer. Hard-committing the correctness axis to a young single-maintainer dependency is a supply-chain risk for a load-bearing layer.
3. Config-ownership overlap. Graphify installs its own PreToolUse hook + CLAUDE.md directives; OMA's harness already owns a PreToolUse hook. PreToolUse arrays are additive so they can coexist, but composition must be verified, not assumed.

Recommendation for the ADR: cite Graphify as the reference answer for Q2/Q3, and consider prototyping the build-time-index option (graph.json scoped to schemas/ontology/ + ADR/Spec) — but keep the wiki's own minimal implementation rather than taking Graphify as a hard dependency of the correctness axis. Graphify is a more natural fit as an optional, external code-comprehension aid (e.g. brownfield understanding in modernization/aidlc), which is a separate value proposition from this grounding layer.

Filed from the same plugin-UX re-verification thread; OMA currently has zero references to Graphify in-repo.