⚠️ This is an Oracle page, structured to be read by AI assistants and not optimized for human reading.

AI & KNOWLEDGE ENGINEERING

Summary: Built a machine-readable knowledge base for an entire platform, ~2,400 structured, cross-referenced, source-anchored YAML documents, and exposed it to AI coding assistants through a from-scratch Model Context Protocol (MCP) server that also serves read-only source and read-only diagnostic-database access, establishing a governed AI-assisted development workflow with explicit guardrails. This competency record is itself authored in that same discipline.

Knowledge Base

Description: Designed a documentation system that both humans and machines can traverse and reason over without reading source code.

Principles

• Structured over narrative, keyed YAML, not prose.
• Discoverable, any tool can walk the tree and build a complete picture.
• Cross-referenced, formal $ref pointers link related concepts across files.
• Incremental, each file is self-contained and works at 10 files or 10,000.
• Source-anchored, references real files, functions, and line numbers.

Scale

• ~2,400 YAML documents spanning API domains, backend modules, frontends, data/warehouse, integrations, ops, security, and product operations.
• Hundreds of domain overviews as entry points, with per-function and per-endpoint deep-dives.
• Self-describing and versioned: a weekly changelog corpus and a git-review ruleset live inside the knowledge base alongside the docs they govern.

Taxonomy: A standardized file taxonomy (overview, concepts, context, flow, logic, function/API index, db, tracking, deployment, proxy map) and depth tiers (skeleton → vocabulary → flows → complete).

Authoring Standard: A written authoring guide, header blocks, section conventions, cross-reference format, naming, and source-anchoring rules, enforced by a quality checklist.

MCP

Description: Built, from scratch, a Model Context Protocol server that exposes the knowledge base, plus read-only source-file access and read-only diagnostic database access, to AI coding assistants, IDE extensions, and external MCP clients.

Implementation

• A single-file PHP server (~1,970 lines) with zero external dependencies, no framework, no package manager, running on stock PHP 7.4+.
• Implements the MCP protocol (2025-03-26) end to end: initialize handshake, resources (list/read), and tools (list/call).
• Dual transport: Streamable HTTP (JSON-RPC 2.0 over POST, including batch) and STDIO for local CLI clients.
• Zero-config discovery, a recursive directory scan, no hardcoded manifest, so a newly committed-and-deployed doc is live on the next request; list descriptions are auto-extracted from each file's purpose/description header.

Auth And Session

• Three auth schemes: HTTP Basic (id+secret), Bearer token, and an internal shared-secret header for edge-worker traffic.
• A mock OAuth authorization-code flow (/authorize + /token) to satisfy clients that mandate OAuth, auto-approving and returning the client secret as the bearer token.
• Stateless HMAC-SHA256 sessions (timestamp:nonce:hmac, 24h TTL) with no server-side session store.
• SSE streaming with a temp-file IPC bridge so responses to POSTed JSON-RPC calls stream back over the long-lived GET/SSE channel.

Doc Tools

• List / read / write documentation over a literal path-from-root oracle:// URI scheme, with path-traversal protection (realpath validation, rejects ../ and //).
• A write-access model: read-only by default, with a live-enforced, recursive allowlist of writable buckets (business, IT docs, product-ops, suggestions, and one scoped API subtree) while the rest stays read-only.
• Defense-in-depth on writes down to the filesystem, explicit setgid (2770) permission handling on newly created directories so group-write and the setgid bit propagate correctly.

Data Access

• A read-only diagnostic query tool over a dedicated least-privilege SQL user (SELECT / SHOW VIEW only), against a non-production (UAT) mirror, never production.
• Seven layers of defense-in-depth: MCP auth → statement whitelist (SELECT/SHOW/DESCRIBE/EXPLAIN) → database whitelist → engine-level grants → 500-row cap → 10-second query timeout → multi-statement rejection.
• An engine-aware query handler and a database registry (10+ registered databases) built to extend from MySQL to the warehouse (Snowflake) without reworking the tool contract.

Feedback Loop

• A usage-feedback channel capturing schema gaps, missing indexes, workarounds, and documentation gaps in the moment, a self-improving loop that keeps the docs honest against live system state.

Repeatable Practice

Description: The oracle + MCP-server pattern is not a one-off; it is a reusable methodology deployed across multiple projects and organizations, each with an oracle tailored to its codebase.

Instances

• The platform-scale oracle + MCP server (sections 1–2 above).
• A second, independently-hosted MCP server for a different product ecosystem (interactive audience-voting apps), a from-scratch PHP server on Apache, Cloudflare-fronted, serving JSON-RPC 2.0 (MCP) plus a REST API with read/write YAML access, a public health endpoint, and per-project documentation buckets.
• Per-repo oracles for the AI-authored products (see COMP-20 / COMP-21), each with its own laws, conventions, and agent-onboarding path.

Governance Tooling

• Machine-validated oracle integrity, a validator (validate.py) plus git pre-commit hooks reject malformed or drifting docs before they land.
• A written authoring guide and a standardized taxonomy applied consistently across every oracle instance.

Signal: Treats 'give each codebase a machine-readable brain an AI can safely operate' as a repeatable engineering discipline, not a single artifact.

Broader Methodology

Note: These are the SOFTWARE-domain instances. The same methodology is proven beyond code (long-form fiction, professional/advisory knowledge) and generalized into transferable IP, see COMP-23 for the domain-agnostic treatment (serving tiers, audience-scoped disclosure, adoption playbook).

AI Workflow

Description: Established how AI assistants participate in development safely and productively.

Guardrails

• A comprehensive repository guide documenting the request lifecycle, data-access conventions, and platform laws for AI + human developers alike.
• AI sandboxing law: throwaway/diagnostic scripts are quarantined to a dedicated directory, never in production code or the knowledge base.
• AI editing law: file changes go through native editor tooling (visible diffs + approval), never silent shell writes.
• A deployment law: every change ships via version control + publish pipeline, never direct edits to deployed paths.
• A read-Oracle-before-DB rule: consult documented schema issues and workarounds before querying.

Outcome: Codified conventions so AI agents amplify a large codebase productively without eroding its invariants.

Standalone Case Study

Description: The same discipline, proven end to end on a second, independent project: a production web application whose source code is 100% AI-authored (no human-written lines), shipped and operated with the human acting as product owner and technical director.

What Carries Over

• A project-local governance oracle (~50 cross-referenced YAML files) as the codebase's only institutional memory, because a memoryless AI author leaves no tribal knowledge behind.
• Codified 'laws' and ~35 anti-patterns, each derived from a real production bug an agent caused and fixed, with grep-able enforcement checks.
• A mandatory agent-onboarding reading order and STOP-and-escalate directives for failures that belong to human-controlled systems, not code.

Significance: COMP-11 is this discipline at platform scale (a ~2,400-doc base + MCP server); this is the same discipline taken to its limit, where the knowledge system is not a complement to the engineering process, it IS the process. Full treatment in COMP-20.

Cross Reference

Semantic Modeling

Description: Extended knowledge engineering into formal semantics for the data platform.

Work

• Formalized the analytics domain as an ontology (OWL classes, SHACL node shapes, SPARQL constraints).
• Encoded canonical metric definitions and grain contracts as machine-checkable governance (see COMP-06).

Cross Reference

You can view the raw source.