Wiki-code alignment loop
A drift-control pattern for keeping founder intent, wiki terminology, MCP behavior, repo docs, and tests synchronized.
TL;DR: Founder intent should become named wiki concepts; named concepts should map to code contracts; code contracts should be backed by tests and repo docs. When any layer drifts, fix the smallest durable artifact instead of leaving the correction in chat.
Status as of 2026-05-14: Adopted as the operating pattern for the Hussh wiki app and MCP repo.
The loop
- Founder thesis — the durable idea, constraint, or product language.
- Wiki page — the human-readable concept with sources and relations.
- Code contract — the runtime behavior that makes the concept real.
- Repo doc — the engineering map for future maintainers.
- Verification — a test, lint, runtime check, or deployment smoke test.
The loop is complete only when a future agent can read the wiki, inspect the repo, and understand why the system behaves the way it does.
What belongs where
| Artifact | Belongs in | Example |
|---|---|---|
| Public product/R&D concept | wiki/concepts/ | Public/private surfaces, wiki-as-app architecture, artifact capture. |
| Private operating rule | Top-level private docs or private wiki pages | Non-negotiables, schema, verification findings. |
| Implementation map | Architecture docs | Project craft, auth, storage, capture pipeline. |
| Operational sequence | Runbooks | Connector setup, deploy, rollback, token rotation. |
| Runtime guarantee | Code + tests | MCP tool tiering, clean wiki URLs, Material 3 Expressive state layer. |
Drift examples
- If a public wiki page says anonymous users see 7 tools but code returns 8, update the page and the architecture docs.
- If the reader shows
/wiki/wiki/..., fix the route helper and tests, then update connector/deploy docs. - If MCP resources expose private operating docs anonymously, fix the resource tiering before claiming the public/private boundary is safe.
- If an internal memory-system label appears in public prose, fix the write safety path and clean the affected page.
Why this matters
Karpathy's LLM Wiki pattern makes good answers persistent. Hussh adds a development discipline: good answers must also stay executable. The wiki is not just documentation after the fact; it is the shared vocabulary that lets the founder, the developer, and future agents converge on the same system.
Enterprise architecture streamlining run
- Current repo truth: architecture claims must reconcile against internal docs, code, tests, generated contracts, and deployment proof before becoming partner-facing truth.
- North-star direction: Founder Wiki remains a validation lane for concept intent, not standalone implementation proof.
- Not shipped / not implied: wiki concepts do not by themselves prove enterprise partner integrations, full One/Nav runtime, or local private-compute implementation.
- Source notes: internal architecture source notes and generated-contract boundaries.
- Audit artifact: private enterprise architecture truth streamlining audit from 2026-05-19.
Sources
- LLM Wiki pattern — origin pattern: raw sources → wiki → schema.
- Wiki-as-app architecture — live app/MCP runtime.
- Public vs private surfaces — current auth-tier contract.
- Internal architecture docs — repo-facing implementation and drift-control map.
- MCP implementation notes — tool/resource/prompt tiering.
- Reader test notes — reader UX contract.
- MCP test notes — contract and visibility regression suite.