{"slug": "show-hn-markdown-gatekeeper-one-current-source-per-topic-for-ai-agents", "title": "Show HN: Markdown Gatekeeper – one current source per topic for AI agents", "summary": "Markdown Gatekeeper, a new open-source tool from nanlogic, enforces a single current source of truth per topic for Markdown documents in projects where humans and AI agents like Claude and Codex collaborate. The tool, available now via GitHub with an npm release pending, adds a rule that documents only become authoritative through explicit review and publication, using local Git for history and rollback. It provides CLI commands such as `mdg init .` for zero-touch project adoption and `mdg publish` for approving proposals, aiming to prevent conflicting edits from multiple agents.", "body_md": "Markdown Gatekeeper is a local-first authority layer for projects where humans, Claude, Codex, and other agents create overlapping Markdown documents.\n\nIt keeps ordinary Markdown and local Git. It adds one rule: a document does not become current authority merely because an agent calls it authoritative.\n\nThis repository is the first dogfood implementation. It intentionally has no cloud service and no MCP dependency.\n\nUntil the npm registry release is available, install the CLI directly from GitHub:\n\n```\nnpm install -g github:nanlogic/markdown-gatekeeper\n```\n\nAfter the package is published to npm, the equivalent command is `npm install -g markdown-gatekeeper`\n\n.\n\nInstall the matching Skill and bootstrap for the Agent host you use:\n\n```\nmdg setup codex\nmdg setup claude\nmdg setup status\n```\n\nRun only the setup command for hosts you have installed. `mdg setup codex`\n\nmanages the Skill, launcher, and bootstrap under `$CODEX_HOME`\n\nor `~/.codex`\n\n; `mdg setup claude`\n\ndoes the same under `$CLAUDE_CONFIG_DIR`\n\nor `~/.claude`\n\n. Each host keeps its own native instruction file and launcher. The launchers use absolute Node and package paths, so GUI sessions do not depend on npm's global executable directory being present in `PATH`\n\n.\n\nDuring local development, use `npm link`\n\nin this repository instead of installing globally from GitHub. New Codex tasks and Claude Code sessions then detect managed projects automatically, while unrelated global instructions and unmanaged projects are left alone.\n\nInitialize and organize an existing project with one command:\n\n```\nmdg init .\n```\n\n`mdg init .`\n\nis zero-touch: it completes discovery, review, safe high-confidence publication, archiving, Evidence, and integrity checks without another confirmation. It prefers an isolated Codex CLI, enforces a three-minute reviewer timeout, and can fall back to the current Codex or Claude Code Session when the command is started with `--host-session codex`\n\nor `--host-session claude`\n\n. Other configured reviewers are later fallbacks. `--preview`\n\nperforms classification and archive-risk reporting without review or publication, while `--setup-only`\n\ninstalls only the protocol.\n\nAfter installation, routine Agent sessions use Gatekeeper silently. If a managed project still has registry revision zero or pending legacy entrypoints, the host-specific bootstrap automatically resumes adoption. Successful housekeeping is not shown to the user; owner review appears only when the current task actually depends on unresolved product intent. Bootstrap calls the installed global `mdg`\n\ncommand directly and only uses a verified host launcher or repository-local fallback.\n\n```\nnode .\\bin\\mdg.mjs status .\nnode .\\bin\\mdg.mjs scan .\nnode .\\bin\\mdg.mjs context services\\api\nnode .\\bin\\mdg.mjs reconcile services\\api --json\nnode .\\bin\\mdg.mjs resolve architecture --path services\\api\n```\n\nCreate and publish a proposal:\n\n```\nnode .\\bin\\mdg.mjs propose docs\\proposals\\my-change.md --topic architecture\nnode .\\bin\\mdg.mjs publish docs\\proposals\\my-change.md --topic architecture --base-revision 1 --approve\nnode .\\bin\\mdg.mjs check .\n```\n\n`--approve`\n\nis an explicit workflow acknowledgement, not a security credential. Strong multi-user enforcement will require a separately privileged publisher identity.\n\n`PROJECT_AUTHORITY.md`\n\nis the generated human-readable entry point.`.authority/registry.json`\n\nis the deterministic current pointer map.`.authority/evidence/`\n\ncontains immutable, non-normative audit records. Revision one is a baseline; later records contain only changed rules.`.authority/reports/code-reconciliation/`\n\ncontains ignored, non-normative snapshots of implementation drift candidates.`docs/current/`\n\ncontains published canonical Markdown.`docs/proposals/`\n\ncontains competing work until review.- Local Git records history and enables rollback.\n- Claude and Codex project hooks block accidental direct edits to protected authority files.\n\nThe LLM acts as a semantic reviewer. The publisher, not the LLM, owns the state transition.\n\n| Command | Purpose |\n|---|---|\n`mdg init` |\nInitialize and automatically adopt safe legacy authority |\n`mdg status` |\nValidate the authority state |\n`mdg scan` |\nInventory Markdown and surface duplicates or unmanaged claims |\n`mdg resolve` |\nReturn the current source for a topic |\n`mdg context` |\nReturn the deepest applicable authority for every topic at a path |\n`mdg reconcile` |\nCompare the applicable Current context with bounded code-change candidates |\n`mdg explain` |\nTrace a rule through its on-demand Evidence chain |\n`mdg evidence amend` |\nAppend a non-destructive correction to Evidence |\n`mdg propose` |\nRegister a Markdown document as pending work |\n`mdg publish` |\nPublish an explicitly approved proposal |\n`mdg adopt` |\nDiscover, review, decide, apply, and restore legacy Agent documents |\n`mdg owner set` |\nAssign a per-scope topic owner with Git identity audit |\n`mdg doctor reviewers` |\nCheck Codex, Claude, and configured reviewer adapters |\n`mdg setup codex` |\nInstall or update the Codex Skill, launcher, and bootstrap |\n`mdg setup claude` |\nInstall or update the Claude Code Skill, launcher, and bootstrap |\n`mdg setup status` |\nReport installation versions and paths for both hosts |\n`mdg sync` |\nRegenerate adapters and authority index |\n`mdg check` |\nDetect direct edits and registry drift |\n\nThe default path is `mdg init .`\n\n. It discovers likely Agent-facing documents, follows their explicit Markdown authority references, excludes obvious archives and audit noise, and proceeds without another confirmation. High-confidence topics publish automatically; ambiguous topics remain unresolved and their files stay in place. After authority exists, initialization also writes a bounded implementation-observation baseline so later Sessions can detect code changes that outpace the documents.\n\nThe lower-level workflow remains available for debugging and expert control:\n\n```\nmdg adopt start .\nmdg adopt report adopt-RUN-ID\n```\n\nWhen `mdg init`\n\nfinds an existing unmanaged `AGENTS.md`\n\nor `CLAUDE.md`\n\n, it leaves the file byte-for-byte unchanged and marks it pending adoption. The managed adapter is installed only after the relevant legacy decisions are resolved and applied.\n\nThe report lists every candidate source. A manually driven review still requires explicit disclosure approval:\n\n```\nmdg adopt review adopt-RUN-ID --reviewer codex --approve-send\nmdg adopt report adopt-RUN-ID\nmdg adopt decide adopt-RUN-ID DECISION-ID --accept-draft\nmdg adopt apply adopt-RUN-ID --decision DECISION-ID\n```\n\nUse `--select S-001`\n\nto keep a single source or `--unresolved`\n\nto defer a topic. Applied legacy files move to `.authority/archive/legacy/`\n\n; `mdg adopt restore`\n\nverifies their hashes before restoring them. `AGENTS.md`\n\nand `CLAUDE.md`\n\nare replaced by short authority adapters only after all rules using that source are resolved.\n\nIsolated Codex and Claude adapters run without repository write tools or persistent reviewer sessions. The current-Session fallback receives an explicitly delimited untrusted-source bundle and can only submit schema-validated review data; the deterministic publisher retains canonical write control. A generic command can be configured locally in `.authority/local/reviewers.json`\n\n; repository content cannot define a command that Gatekeeper executes.\n\nEach adoption run pins its CLI, Skill protocol, adoption protocol, and reviewer schema versions and permits only one mutating operation at a time. External reviewers time out after three minutes by default. Unresolved topics are returned by `mdg adopt owner-review`\n\nin batches of up to three button questions; `mdg adopt owner-apply`\n\nvalidates and publishes the owner's selections without requiring typed IDs.\n\nEvery publish atomically creates current authority and an Evidence revision. Current rules use stable `R-001`\n\nidentifiers. Unchanged rules are not copied into later Evidence deltas:\n\n```\nmdg explain testing --path services\\api --item R-001\nmdg explain testing --path services\\api --item R-001 --history\nmdg evidence amend testing --path services\\api --item R-001 --reason \"Corrected source mapping\" --approve\n```\n\nRoutine `context`\n\nand `resolve`\n\noperations do not read Evidence. Evidence explains provenance and approval but does not confer authority; registry selection, current hashes, and deterministic publish events do.\n\n- Replacing Markdown or Git\n- Automatically deciding ambiguous product intent\n- Treating vector search as authority\n- Requiring GitHub or any remote service\n- Claiming hooks are an unbreakable security boundary\n\nApache-2.0.", "url": "https://wpnews.pro/news/show-hn-markdown-gatekeeper-one-current-source-per-topic-for-ai-agents", "canonical_source": "https://github.com/nanlogic/markdown-gatekeeper", "published_at": "2026-09-02 02:48:42+00:00", "updated_at": "2026-09-02 03:22:00.838052+00:00", "lang": "en", "topics": ["developer-tools", "ai-agents", "ai-tools"], "entities": ["Markdown Gatekeeper", "nanlogic", "Claude", "Codex", "npm"], "alternates": {"html": "https://wpnews.pro/news/show-hn-markdown-gatekeeper-one-current-source-per-topic-for-ai-agents", "markdown": "https://wpnews.pro/news/show-hn-markdown-gatekeeper-one-current-source-per-topic-for-ai-agents.md", "text": "https://wpnews.pro/news/show-hn-markdown-gatekeeper-one-current-source-per-topic-for-ai-agents.txt", "jsonld": "https://wpnews.pro/news/show-hn-markdown-gatekeeper-one-current-source-per-topic-for-ai-agents.jsonld"}}