Decision: Wiki Maintenance Contract

Context

The prior wiki implementation provided basic markdown rendering and a lightweight manifest, but lacked schema guarantees, provenance checks, and graph health reporting.

Decision

Enforce wiki frontmatter fields for kind, status, summary, and source paths.
Expose wiki graph and quality checks through GET /api/wiki/health.
Treat wiki upkeep as part of normal code changes through ingest, query, and lint operations in AGENTS.md.

Design Rationale

The core question was: how do you keep engineering documentation accurate in a fast-moving monorepo without dedicated technical writers? The answer is to treat wiki pages like code — give them schemas, provenance, and automated health checks.

Several alternatives were considered:

External wiki (Notion, Confluence): rejected because external tools drift from the codebase. There is no enforceable link between a Notion page and the source file it describes, so staleness is invisible until someone trips over it. Keeping the wiki in-repo means documentation changes can be reviewed in the same PR as code changes.
Inline code comments only: insufficient for cross-cutting concerns. A pipeline that spans engine/ingest/, engine/srd_level_up/, and server/ needs a single page that synthesizes the full picture — something inline comments cannot do.
Unstructured markdown with no schema: the prior state. Without required frontmatter, pages lacked provenance (source_paths), categorization (kind), and freshness signals (status). The health endpoint had nothing to check against.

The chosen approach — structured frontmatter with automated health reporting — sits in a middle ground: lightweight enough that agents and developers can maintain it as part of normal workflow, but structured enough that tooling can detect rot.

Assumptions & Constraints

Agent-driven maintenance is the norm. The contract in AGENTS.md assumes that most wiki updates are performed by AI agents during code tasks, not by humans in a separate documentation pass. This means the schema must be simple enough for agents to populate correctly without ambiguity.
Source paths are stable identifiers. The stale-detection mechanism compares file modification times against page modification times. This assumes source_paths entries point to files that exist and whose paths don't change frequently. Major refactors that rename directories can invalidate many pages at once.
The health endpoint is advisory, not blocking. GET /api/wiki/health reports issues but does not gate deployments or merges. This is a deliberate choice — blocking on wiki health would create friction disproportionate to the value, especially during rapid iteration. The assumption is that stale pages are tolerable short-term as long as the tooling surfaces them.
Six kind values are sufficient. The fixed set (overview, subsystem, api, runbook, decision, glossary) was chosen to cover the categories that recur in this project. Adding a new kind requires updating both server/wiki.py and AGENTS.md.

Conceptual Model

The wiki maintenance contract establishes a feedback loop between code and documentation:

Trigger: a code change touches a file in a monitored subsystem (server routes, pipeline logic, schemas, manifests).
Ingest: the agent updates affected wiki pages, refreshing behavior descriptions, invariants, and source references.
Health check: the /api/wiki/health endpoint compares page timestamps against source file timestamps, detects broken links, and flags orphan pages.
Lint: periodic lint operations catch drift that incremental ingest missed — for example, when a source file is deleted but the wiki page still references it.

The relationship between source_paths and wiki content is analogous to foreign keys in a database: they create a declared dependency between a documentation artifact and the code it describes. When the code changes, the dependency makes the documentation's staleness detectable rather than silent.

The three operations (ingest, query, lint) map to different maintenance cadences. Ingest is synchronous with code changes. Query is opportunistic — it captures durable knowledge that emerges from ad-hoc investigation. Lint is periodic and defensive, catching whatever ingest and query missed.

Consequences

Wiki pages now carry stronger metadata and source linkage.
API consumers can surface stale documentation and missing provenance.
Engineering tasks touching key areas must include wiki updates and log entries.
The wiki/log.md append-only log provides an audit trail of what changed and why, making it possible to trace documentation evolution alongside code history.