Audit: Pre-push audit file¶

What we check¶

Repositories that carry a pre-push audit runbook must:

name it PUSH-AUDIT.md -- the historical PUSH-TEMPLATE.md is flagged as legacy, because the file is a runbook the operator follows before pushing rather than a template that gets copied, and -TEMPLATE is reserved for true templates like PLAN-TEMPLATE.md;
embed the current readme-discipline, llm-doc-discipline, diagram-discipline and plan-phase-references shared blocks in its documentation-review section (see the readme-structure, llm-doc-structure, diagram-format and plan-phase-references audits for the policies they enforce);
embed the current comment-proportion shared block in its code-quality review section;
embed the current source-file-size shared block alongside it -- the advisory guidance on how long a source file gets before its size is itself worth raising in review, framed as the cost of re-reading a whole file rather than as taste, because where review is tracked per file every change discards the review of all of it;
embed the current plan-references-in-code shared block alongside those -- code, comments and configuration describe the software as it is, so they cite no plan phase, step or decision number, and carry the reasoning a plan pointer would otherwise stand in for; a plan link survives only for work not yet built (see the plan-source-references audit, which checks that such links resolve);
embed the current path-traversal-review, python-version-discipline and functional-test-coverage shared blocks, which carry the three criteria delegated to the reviewer because no grep can judge them (see the security-sanitization, python-version and test-coverage audits for the policies they enforce);
keep every embedded block verbatim and at the current version; and
be referenced from AGENTS.md, so a session can discover it.

Repositories with no pre-push audit file are N/A: whether every project should have one is a separate decision, not smuggled in here.

Why the reference is checked¶

Checking only the file's contents is how the runbook went untriggered. In August 2026 the audit was current and correct in eight repositories while three AGENTS.md files mentioned it at all, and exactly one of those said when to run it. No CLAUDE.md, PLAN-TEMPLATE.md, git hook or CI job pointed at it either, so it ran when the operator remembered it and not otherwise.

AGENTS.md is the surface checked because it is loaded into every session. The check is deliberately shallow -- it looks for the filename, not for particular wording -- because the reference that matters is the one a repository writes for itself. A repository still on the legacy name is checked against that name, so it is told to rename the file once rather than told twice about a file it does not have.

The reference is necessary but not sufficient: discoverable is not run. What makes it run is the plan-push-audit-phase shared block, which puts a push-audit phase at the end of every master plan. That block lives in PLAN-TEMPLATE.md and is enforced by the plan-template audit, not this one.

Why comment proportion is a judgment check¶

Comment volume has no honest mechanical threshold: the same twenty-line docstring is right on a lock-ordering contract and wrong on a three-line accessor. What can be mechanised is finding the candidates -- runs of added comment lines, and comment blocks larger than the body they precede -- which a repository may add to its wave-1 sweep as a report-only grep. The proportionality call belongs to the code-quality judgment agent, which is why comment-proportion is shared wording for a sub-agent brief rather than a check in audit-check.py.

Shared blocks¶

Shared blocks are canonical wording embedded verbatim across repositories between  and  markers; the canonical copies live in templates/shared-blocks/, whose README.md describes the mechanism. The check fails when a required block is missing, stale, drifted from the canonical wording, unknown, or missing its end marker.

This audit exists because the pre-push audit files drifted independently in each repository -- several still told the documentation reviewer that "README.md reflects any new features", which is the exact feedback loop that bloats READMEs.

Recently enforced¶

plan-references-in-code became a required block on 2026-09-24. It extends to code the rule plan-phase-references already applies to documentation: a reader of the code has not read the plan, so added in phase 5 or per decision 3 tells them nothing, and a comment that points at a plan for its reasoning should carry the reasoning instead. It is a judgement check in the reviewer's brief rather than a grep, for now: a raw scan of the fleet's code on the day it was written found roughly 3,400 phase, step, decision and plan references across thirteen repositories, and "phase" has enough ordinary meanings that a mechanical check wants the first repository sweep to show what its false positives look like before it files issues. The fix for a non-compliant repository is a verbatim copy of templates/shared-blocks/plan-references-in-code.md; the backlog the block describes is swept separately.

source-file-size became a required block on 2026-09-20, and the repositories that do not yet embed it are non-compliant on the generated compliance page from that date rather than from any change of their own. The fix is a verbatim copy of templates/shared-blocks/source-file-size.md from shakenfist/development, markers included; templates/shared-blocks/README.md describes the copy discipline, and the reasoning for enforcing it with a backlog open rather than after the sweep is D1 and D2 of PLAN-review-unit-size.md.

Template¶

Template: templates/shared-blocks/ See: templates/shared-blocks/README.md

To fix a non-compliant repository, copy each named block verbatim from templates/shared-blocks/ into PUSH-AUDIT.md and reference the file from AGENTS.md; templates/shared-blocks/README.md describes the markers and the version bump procedure.

Projects¶

Per-project compliance for this criterion is regenerated every morning by the consistency audit: see the compliance page.

📝 Report an issue with this page