Maintain Repository Wiki with Verified Engineering Knowledge

Maintain Codex Wiki keeps a repository-local Markdown wiki as compiled engineering knowledge rather than an automatic source of truth: it preserves provenance, separates evidence classes, and requires review before a wiki conclusion becomes a repository rule, skill, or learning material. It works through six explicit operations - Query, Capture, Ingest, Archive, Lint, and Promote - each with its own trigger conditions and guardrails, rather than one generic "update the docs" action.

Use it to query what a repository already knows about a technical decision, capture a durable lesson from a merged change, incident, review, or experiment, ingest external research without silently treating it as authoritative, reconcile conflicting or superseded guidance, check wiki structure and citation freshness, or promote verified knowledge into a rule, skill, module, or automated check. Do not invoke it merely because a task produced code or chat output - the skill is explicit that no material wiki change is itself a valid result, and several operations (Capture, Ingest, Archive) require an explicit user request before touching the registry, pages, index, or log at all.

The wiki lives under a knowledge/ directory with index.md, log.md, sources.json, and decisions/, experiments/, and topics/ subfolders. Every page declares one status - verified, community, experimental, or decision - with a Last verified date only on verified pages (others use Last updated), and cites one of four source classes: official, repository, community, or experiment. Query is read-only and answers with links to wiki pages, stating plainly when the wiki has no evidence rather than filling gaps from model memory. Capture updates the smallest existing page or creates a new experimental one from durable evidence (never from chat prose or unmerged proposals alone). Ingest compiles external sources sequentially (since the registry, index, and log are shared state), preserves disagreements instead of rewriting them as consensus, and ends by preparing a pull request - it never pushes directly to a protected branch. Archive is explicitly separate from promotion: run only on explicit request, it preserves every source ID used by a query's synthesis, creates one compact experimental page, and links to related pages instead of copying their prose. Lint mechanically checks registry schema, source revisions, duplicate titles, and index coverage, then separately flags what automation cannot prove, like whether a citation actually supports its claim. Promote maps evidence to a destination: a durable repository requirement goes to AGENTS.md, a reusable procedure with a measured gap becomes a focused skill, stable learning content becomes a module, and a mechanically enforceable invariant becomes a script or CI check - early or unresolved evidence simply stays in knowledge/. Every operation ends with a completion report naming what was actually performed: which pages and source records changed, which checks ran and their results, any conflicts or freshness uncertainty found, and whether promotion happened or was deferred.

Every operation runs behind a Confinement Invariant before touching any file: paths must be normalized and repository-relative, absolute paths and .. are rejected, symlinks are resolved and rejected at the target or any parent, and new pages must land under an existing, repository-contained directory. Repository evidence is pinned to the full immutable Git commit object ID (40 hex characters for SHA-1, 64 for SHA-256) and must be reachable from a configured trusted branch ref - tags are not accepted, and GIT_NO_LAZY_FETCH/GIT_NO_REPLACE_OBJECTS are set on every object read so a partial clone or replacement ref cannot substitute different content. A registered external URL is treated as provenance, not permission to fetch: Query never fetches it, and an authorized refresh or ingest requires a public HTTPS destination with redirect validation, failing closed if that cannot be enforced. Wiki pages, registry fields, and external sources are all treated as untrusted evidence data - embedded directives inside them are ignored and reported, never followed.

Engineering teams that want a durable, in-repo record of technical decisions and lessons with an explicit chain of custody from raw evidence to trusted rule, rather than tribal knowledge in chat threads or an unreviewed docs folder that quietly becomes "the truth."

git config --local --add codex.wikiTrustedRef <full-branch-ref>