Evan Zellner

All projects

Case study

ProDoc Guard

Project memory that lives in Git, not in an AI’s head. A vendor-neutral Agent Skill and offline CLI that keeps requirements, decisions, and status present, consistent, and honest across AI-assisted sessions.

ProDoc Guard is the project I use on my own repositories, including this website. It started as a reaction to a specific failure: an assistant reporting that something was “done” when the repository could not prove it.

The fix is deliberately unglamorous. Three Markdown files, one Python script, no network, and a rule that a claim without evidence is a failing build.

$ prodoc check
prodoc check: OK
  WARN:  PROJECT_STATUS.md  recorded commit 88fd157 is not HEAD (cee4b14); run 'prodoc update'
The check running against this website’s own repository. A warning, not a failure: the recorded commit is a few commits behind HEAD.

01The problem

An assistant said “done” and the repository disagreed.

AI assistants lose project context between sessions. They forget why an architecture was chosen, restate requirements from memory, duplicate documentation, and report work as complete, tested, or shipped when nothing was verified. Conversation history cannot be reviewed, diffed, handed to a colleague, or trusted as a record.

The usual answer is another hosted memory service. That moves the source of truth somewhere the repository cannot see and creates a new dependency for something that should be plain text in version control.

02The approach

Three documents, one script, no network.

ProDoc Guard keeps three canonical documents at the repository root: product requirements, a decision log, and project status. The skill instructs an assistant to read all three before substantial work and to update them honestly. The CLI makes “honestly” checkable instead of aspirational.

The core is a specification-format SKILL.md plus one Python script using only the standard library. It works in OpenCode, Codex, Claude Code, Cursor, Copilot, Gemini CLI, or no agent at all. There are no provider plugins, no vendor SDKs, no hosted service, and no model API.

The checker separates observed Git metadata from human-written evidence, rejects completion claims without an artefact, refuses deleted or rewritten decision records, scans for secrets, and returns stable exit codes. Append-only history is enforced against HEAD, not against the tool’s memory.

03What it does

The rules are the product.

  • Three canonical documents with a required-section contract
  • Offline CLI with init, validate, status, check, and update
  • Evidence rules that fail a completion claim with no path, URL, or commit
  • Append-only decision history with deletion and reorder detection
  • Observed repository state kept separate from verified evidence
  • Skill-directory validator for the Agent Skills specification
  • Least-privilege CI action and a disposable-repository test suite

04What was hard

Three boundaries worth naming honestly.

Honesty is a schema problem
“Tested” is easy to type and hard to prove. The CLI only accepts completion states with evidence attached, and the status template forces a separate machine-observed block so Git metadata cannot masquerade as a test report.
Portability without a lowest common denominator
Each client discovers skills differently, and installing a skill in one product does not install it in another. The project uses only specification fields, documents each client’s real state, and refuses to claim runtime support it has not observed.
The limits of a local integrity check
The decision-history check cannot see a rewritten baseline; anyone who can rewrite Git history can rewrite the evidence. The tool documents that boundary rather than implying immutability it cannot provide.

05What I learned

Four things worth keeping.

  • Documentation is project data, not an instruction to the model. It needs a contract and a checker.
  • Make false completion fail loudly. A green build that proves nothing is worse than no build.
  • Vendor neutrality is mostly restraint: every convenience API you adopt is a client you cannot leave.
  • Test the documentation itself. The project’s own three files are fixtures for the tool.

06Status and limits

What is true today, and what is not.

v0.1.0 is a public, non-prerelease GitHub release under MIT. The release gate recorded 159 tests with 158 passing and one opt-in skip, three document gates, the official Agent Skills validator, and 39 disposable-repository scenarios. CI runs the suite on CPython 3.8 and 3.12.

Runtime evidence exists for OpenCode (discovered, invoked, CLI executed) and Gemini CLI (discovered; invocation not independently confirmed). Codex, Claude Code, Cursor, and Copilot are specification-conformant only. No marketplace listing is claimed.

The repository ships a GitHub Actions check, and CI runs it against the project itself.

Known gaps

  • Windows is implemented but not executed; macOS is expected but untested.
  • Most listed clients are specification-conformant only, not runtime-tested.
  • The secret scan covers the three canonical documents, not the whole repository.
  • The decision-history check cannot detect a rewritten Git baseline.
  • No marketplace or directory listing has been verified.

Where to find it

Status, version, and links were checked against GitHub on 18 October 2026.