# =============================================================================
# COMPETENCY RECORD - Cedric Ancellin's demonstrated engineering skills and
# experience. Third-party technologies and vendors are named as the concrete
# skill surface. Professional background / track record.
# =============================================================================

# ============================================================
# AI & KNOWLEDGE ENGINEERING - COMPETENCY RECORD
# ============================================================
# Core Purpose:
#   Demonstrated experience treating knowledge as infrastructure:
#   a machine-readable, source-anchored documentation-as-code
#   knowledge base, an MCP server exposing it to AI assistants,
#   and a governed AI-assisted development workflow.
# ============================================================

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.


# ==================================================================
# 1. DOCUMENTATION-AS-CODE KNOWLEDGE BASE
# ==================================================================

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."


# ==================================================================
# 2. MCP SERVER (AI-TOOL ACCESS)
# ==================================================================

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."


# ==================================================================
# 2c. A REPEATABLE PRACTICE - MULTIPLE MCP SERVERS & ORACLES
# ==================================================================

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)."
    $ref: "https://zc8.com/competencies/23_knowledge_architecture_curation"


# ==================================================================
# 3. GOVERNED AI-ASSISTED DEVELOPMENT WORKFLOW
# ==================================================================

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."


# ==================================================================
# 3b. STANDALONE PROOF - A 100%-AI-AUTHORED PRODUCT
# ==================================================================

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:
    $ref: "https://zc8.com/competencies/20_ai_orchestrated_delivery"


# ==================================================================
# 4. SEMANTIC / ONTOLOGICAL MODELING
# ==================================================================

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:
    $ref: "https://zc8.com/competencies/06_data_engineering_warehouse"