Assemble a README Ledger From Entry Points and Tests; Sign Guarantees by Hand

Description and use

Create a JSON ledger that separates project facts (commands, tests, extras) from contract and support statements, so reviewers focus on contracts rather than formatting.

Problem

Generated README prose can overwrite or hide contract details, leading to silent compatibility changes, missing secrets, or invented support windows.

Outcome

A structured ledger that clearly distinguishes inventory from contract and support claims, reducing review friction and preventing accidental contract violations in README updates.

Workflow

• Collect repository facts: parse pyproject.toml for project name, scripts, optional-dependencies; run pytest --collect-only to gather test node identifiers.
• Store any collection failures as ledger defects; do not guess missing data.
• Generate a proposal JSON ledger (readme_ledger.json) with inventory arrays populated and contract/support cells set to null.
• Review the ledger output locally, inspect unsigned cells, and add signatures (dates) where appropriate.
• Update the README using the ledger as source of truth, keeping human-signed contract and support statements separate from autogenerated inventory tables.

Evidence

Inventory facts can be compiled from entry points, pytest node identifiers, and package metadata with deterministic scripts.

Source

If a sentence cannot be regenerated from repository facts, it belongs in a contract or support lane and stays unsigned by default.

Source