Maintaining markdown for AI
AI collapsed the cost of writing documentation and raised the cost of verifying it. The work moved — and the verifying half is nobody else's job.
Markdown in AI workflows
A single format carrying three of the six context types: Knowledge, Instructions, and Memory.
A plain text file with nothing mechanical underneath. What matters is how and when it is consumed: as knowledge, as instructions, as memory — and whether the agent pays for it on every turn or only when it reaches for it.
docs/handbook/onboarding.md
Retrieved on demandFront matter header
---
type: Handbook
stale_after: 2026-07-01
owner: "@people-ops"
---Document body
# Employee onboarding
Handbook for first-week setup. Dynamic context: the agent pays token costs only when a question reaches for it.
1. Collect laptop from IT on day one
2. Complete security training module
3. Meet your onboarding buddy
Retrieved on demand. Stale pages answer just as fluently as fresh ones.
KnowledgeRetrieved on demand
Pay only when fetched
InstructionsUser or model invoked
Progressive disclosure
MemoryAlways loaded
Paid on every turn
Volume outruns review
On one document, maintenance effort decays while drift climbs — that crossing is where the work moved. Across a corpus, the maintenance surface grows faster than the file count.
Two different things get harder. On a single document, maintenance effort decays while drift keeps climbing. Across a corpus, the maintenance surface grows faster than the file count.
Where the effort goes
What a machine can check, what AI can help with, and what only a human can check.
Three boundaries: what a machine automates, what AI accelerates, and what only a human can decide.
What the machine verifies
Syntactic and structural checks that run deterministically in milliseconds without an LLM.
Machine checkResolves cleanly
✓Syntax: valid YAML frontmatter delimiter (---) & structure
✓Resource: present and well-formed URI (https://intranet.example.com/people-ops/handbook#onboarding)
✓Staleness: 2026-07-01T00:00:00Z parses with valid ISO timestamp
Machine checking proves the file is mechanically sound. It cannot determine if the policy is still active.
What AI accelerates
Cross-referencing prose against source handbooks to flag discrepancies for human review.
Machine check✓ Resolved cleanly
AI recommendation⚠ Discrepancy flagged (needs check)
Observation
Compared onboarding.md against linked People Ops handbook. Section 4 of the handbook updated equipment lead times from 5 working days to 7 working days.
Proposal
Recommend updating line 15 and notifying the hiring manager.
The recommendation is rapid and insightful, but remains an unverified claim itself.
What remains human
Is the policy still in force? Is the owner correct? Ground truth that no machine or model can know.
Machine check✓ Resolved cleanly
AI recommendation⚠ Discrepancy flagged
Human judgmentOpen · Unresolved
?Does the buddy coffee on day one still match team practice?
?Does People Ops still close provisional accounts on Friday 5pm?
?Is the stated owner (@people-ops) still the accountable team?
Ground truth that no machine or language model can know. You are the one accountable when it is wrong.
Google OKF
Full OKF v0.2 frontmatter schema governing provenance, trust, and lifecycle.
A standardized frontmatter schema to govern AI knowledge bases. Provenance, trust tiers, and lifecycle fields sit directly in markdown alongside the content.
| 1 | --- | |
| 2 | # --- Provenance (§5.1) --- | |
| 3 | title: <Concept name> | # REQUIRED — Human-readable concept title |
| 4 | version: 0.2.0 | # SemVer concept version |
| 5 | description: <Summary> | # Summary statement for agent indexing |
| 6 | tags: [onboarding, ops] | # Categorical indexing keys |
| 7 | sources: | # Optional — materials this concept derives from |
| 8 | - id: <citation-key> | # Stable citation key for claim attribution |
| 9 | resource: <URI> | # REQUIRED within entry — URI or path |
| 10 | # --- Trust (§5.2, §5.3) --- | |
| 11 | generated: | # Content production record |
| 12 | by: <Actor> | # REQUIRED within generated — agent or human |
| 13 | at: <ISO 8601> | # Timestamp of generation |
| 14 | verified: | # Content verification event log |
| 15 | - by: <Actor> | # REQUIRED — reviewer who sets trust tier |
| 16 | at: <ISO 8601> | # Timestamp of verification |
| 17 | # --- Lifecycle (§5.4) --- | |
| 18 | stale_after: <ISO 8601> | # Temporal expiration date |
| 19 | owner: "@people-ops" | # Accountable team or user |
| 20 | --- |
OKF
Official Open Knowledge Format Specification (v0.2)
Open specification by Google Cloud Platform for agent-maintained knowledge repositories.
Steering the AI
markdown-harness steers the machine half
A document can tell you how much of itself to believe. Not full trust — a floor that holds, and a reliable signal when a human needs to act.
Runs on a 100% deterministic core
One mechanism, three triggers, one deterministic core.
3 Entry Triggers
1. Agent read
Pre-read hook intercepts document read before injection.
2. Git commit
Pre-commit husky gate blocks invalid frontmatter.
3. Manual / CI run
CLI command `mh check` verifies entire corpus.
the same core, every time
Retrieve configurationconfig.yaml ↗
↓
Deterministic validationpure function
3 Corresponding Outcomes
Steer or block
Injects freshness warning or denies stale knowledge.
Prevent drift
Rejects commits lacking mandatory metadata fields.
Report corpus health
Outputs JSON violation summary for build pipelines.
Live demo
The check, run live.
File under test
docs/handbook/onboarding.md
Asked of the agent
“What are the first-week onboarding steps for a new hire?”
Comparative contrast in terminal
Unhooked panel answers confidently from stale documentation. Hooked panels either warn the agent with steering instructions or deny access entirely.
Feature Roadmap
Three shipped, three planned.
v0.0.4 Shipped✓ Available now
- ✓Frontmatter linting — field constraints declared per path
- ✓Staleness checking — stale_after against a stated instant
- ✓Markdown harness skill — skill to install and configure harness
Planned RoadmapIn progress
- ○Drift detection — semantic checks against git commit diffs
- ○Corpus validation — cross-file reference integrity
- ○GitHub Action — automated verification in CI pipelines
The verifying half is yours
Back to the Venn, with the human region lit and the rest dimmed. Nothing new to read.
The work moved. It moved to you.
the AI region is my hypothesis — still unsettled
markdown-harness · github.com/hancrafted/markdown-harness