A README Documentation Gate: Compile Packaging Facts, Sign User Promises

Description and use

The article presents an automated workflow that separates machine‑verifiable facts from human‑signed promises in a README, preventing stale or misleading documentation.

Problem

Public READMEs often mix machine‑verifiable facts with human‑signed promises, leading to stale or misleading documentation.

Outcome

The README now accurately reflects the repository’s current state, separating machine‑verifiable facts from human‑signed promises, reducing onboarding friction and preventing accidental contractual claims.

Workflow

• 1. Run the local deterministic script to extract facts from pyproject.toml, source files, and pytest collection.
• 2. Generate readme_facts.json containing package name, version, console‑script names, test node IDs, and public module paths.
• 3. Maintain promise_register.yaml with human‑signed statements such as install commands, supported Python/OS windows, and copy‑paste examples.
• 4. Use a documentation gate that compares compiled facts against the register; fail if any signed field contains a placeholder or mismatches.
• 5. Render the final README from the verified facts and signed promises.
• 6. Publish the README once the gate passes.

Evidence

The compiler writes readme_facts.json from packaging metadata and test collection.

Source

The gate refuses to render when any signed field still contains a placeholder or when compiled names no longer match the register.

Source