Skip to content

SPECIFICATION · UKMC.V1

Universal Knowledge Master Contract (UKMC.v1)

A strict, machine-enforced contract ensuring every knowledge artifact has deterministic routing metadata, cryptographic provenance, and an external-content flag in frontmatter.

1. Machine Frontmatter Schema (YAML)

All generated knowledge files MUST begin with standard YAML frontmatter:

---
id: "knowledge-entry-id"
title: "Human Readable Descriptive Title"
domain: "architecture | backend | ai-engineering | ui-ux"
description: "One actionable sentence describing what this knowledge file provides to an AI router."
when:
  - "Condition or keyword 1"
  - "Condition or keyword 2"
trust_tier: "draft"
version: "1.0.0"
source_attribution:
  - uri: "_evidence/run/sources/spec.md"
    sha256: "4f53cda18c2baa0c0354bb5f9a3ecbe5ed12ab4d8e11ba873c2f11161202b945"
---

2. Mandatory Structural Sections

Every UKMC document must contain exactly these 4 mandatory H2 sections:

  1. Purpose: Exactly 1-2 crisp sentences stating the concrete problem this document solves.
  2. When to Use / When NOT: Bilateral rules defining ALLOWED scenarios and explicit NOT ALLOWED boundary anti-patterns.
  3. Core Knowledge Content: Sourced facts with cryptographic source anchors (<!-- ease:source line/anchor -->).
  4. Failure Modes (Mandatory): Observable failure cases, edge conditions, and actionable remediation steps.

3. Untrusted content flag

The emitter records whether the unit is external. Ingest does not wrap scraped text in comment markers, and the flag does not change the agent's task.

quarantine:
  is_external_untrusted: false

External text stays data.