Schema Engineering

The schema file is the agent’s operating contract. It should be short enough to obey, specific enough to route work, and strict enough to protect raw sources, source-backed claims, review gates, and final reporting.

Primary artifact: `AGENTS.md` or `CLAUDE.md` at the project root.
Support files: `readme.human`, page templates, `index.md`, `log.md`, and lint rules.
Failure target: stop drift before it becomes durable wiki truth.

What the schema must control

Boundary

Read-only versus writable paths

Name `raw/` as immutable source evidence, `wiki/` as compiled synthesis, and protected files such as `index.md` and `log.md` as special operating records.

Shape

Page types and required metadata

Require type, status, source state, related links, and last-reviewed data so pages can be routed, linted, and compared across sessions.

Loop

Ingest, query, and lint as separate jobs

Ingest compiles sources, query answers from the graph, and lint finds broken links, stale claims, contradictions, orphan pages, and missing evidence.

Review

Claim status before persistence

Unsupported, stale, contradicted, draft, reviewed, and human-approved claims should remain visibly different instead of collapsing into one confident voice.

Report

Final changed-files and checks summary

The agent should end with changed files, sources consulted, contradictions found, checks run, and anything blocked by policy or missing evidence.

Human

Plain steering advice outside the schema

Use `readme.human` for what people should clarify before steering the AI. Keep the root agent file operational, not philosophical.

Operating contract matrix

Artifact	Schema rule	Why it exists	Failure if omitted
`raw/`	Read-only; never edit, move, rename, or delete without explicit approval.	Preserves the evidence trail and lets reviewers re-check synthesis.	The wiki can silently rewrite its source base.
`wiki/`	Writable compiled knowledge graph with page templates and status fields.	Gives the agent a durable place to improve summaries, concepts, entities, and syntheses.	Every session starts from scratch or writes inconsistent notes.
`wiki/index.md`	Required routing catalog; update after approved writes.	Lets the next agent find pages deterministically without guessing.	Useful pages become invisible and orphaned.
`wiki/log.md`	Append-only action log; do not rewrite prior entries.	Records ingest, query, lint, conflicts, approvals, and rejected changes.	Maintenance history disappears and mistakes repeat.
`AGENTS.md`	Short operating contract for paths, loops, permissions, final report, and checks.	Turns a general agent into a project-specific maintainer.	The agent follows generic habits instead of wiki rules.
`readme.human`	Human briefing, not an override; says what people need to clarify.	Prevents humans from assuming the AI knows support boundaries or approval lines.	People steer the project through private context that later sessions cannot see.

Starter root schema outline

# Agent Instructions

## Purpose
Maintain this LLM Wiki by compiling immutable sources into durable, linked markdown.

## Directories
- raw/: read-only evidence. Never edit without explicit approval.
- wiki/: writable compiled pages under the page schema below.
- wiki/index.md: required routing catalog. Update after approved writes.
- wiki/log.md: append-only action log. Never rewrite old entries.

## Page Schema
Required fields: title, type, status, source_status, related, last_reviewed.
Allowed type: source-summary, concept, entity, synthesis, contradiction, runbook.
Allowed status: draft, reviewed, needs-update, contradicted, archived.

## Workflows
Ingest: summarize source, extract claims, update pages, update index, append log.
Query: read index first, answer from smallest useful page set, mark unsupported claims.
Lint: check broken links, orphan pages, stale claims, contradictions, missing sources.

## Final Response
Report changed files, sources used, contradictions found, checks run, and blockers.

Failure modes to make visible

Source overwrite: the agent edits original evidence instead of writing compiled notes.
Confidence drift: draft synthesis starts reading like reviewed fact.
Route drift: pages exist but `index.md` does not point to them.
Silent contradiction: a new source conflicts with an old page but no contradiction record is created.
Unbounded instructions: the root file becomes an essay and the agent stops obeying the important rules.
No final audit: the human cannot tell what changed, why, or which checks actually ran.

Copy-ready