Content policy
On by default. A review dimension is an additional lens the reviewer applies to a diff, on top of the core correctness/security review. The content policy dimension applies the built-in baseline below to the human-readable prose in a diff (Markdown, code comments, docstrings, user-facing or log strings, and the PR title/description), never code logic, identifiers, or structured data. Violations are reported as contentPolicy findings alongside the core reviewer's findings, in the same envelope.
Configuration and opt-out
Content policy needs no repo configuration. The built-in baseline runs unless the repo explicitly disables it. A repo can customize that behavior in two ways:
- Add
.postil/content-policy.mdto append repo-specific rules to the built-in baseline. - Set
contentPolicy.enabled: falsein.postil.yamlto opt out of content-policy review entirely.
An explicit contentPolicy.enabled: false also disables any rules in .postil/content-policy.md. The file can remain in the repo without overriding the opt-out.
Custom policy
.postil/content-policy.md is plain Markdown, one rule per bullet or heading, in the same register as .postil/guardrails.md. Its rules are appended to the built-in baseline below, not a replacement for it. Repo-specific additions layer on top of the defaults rather than overriding them.
# .postil/content-policy.md
- Do not reference internal codenames in public-facing docs or comments.
- Changelog entries must not use marketing superlatives ("blazing fast").The built-in baseline
Six checks, each with a fixed default severity that reflects how confident the model must be before it flags anything:
| Check | Severity | What it catches |
|---|---|---|
| Fabricated or contradicted claims | error | A changed comment, docstring, or doc line that contradicts the code/config/files in the diff or repo, or describes a command, flag, path, env var, or behavior that does not exist. A plausible description is not flagged merely for being unproven: only claims the model can show are false. |
| Self-contradiction within the change | warn | A changed doc or comment asserts something that another file changed in the same diff plainly refutes. Both sides of the contradiction must be in the diff. |
| Authoring-process narration and AI-authorship residue | warn | Prose that narrates writing the code instead of stating what it does, or that reads as assistant/model output leaking into committed text. A plain mention of an AI/LLM as a product feature is not flagged. |
| Conversation and transcript leakage | error | Pasted chat logs, turn markers, narration of what "the user" asked, tool-call/tool-result dumps, or reasoning text leaking into committed content. |
| Stale temporal and TODO residue | info | Reference documentation that reads as genuinely stale: dangling TODO/FIXME with no owner, "currently"/"for now" phrasing describing an already-completed transition. Dated changelog entries and explicit roadmap sections are exempt. |
| House writing style | info | Em-dashes, flowery/themed language, or hype filler ("delve", "seamless", "leverage" as a verb), flagged only when the same pattern repeats three or more times in one file. |
Kept conservative and low-noise on purpose: content policy augments the core reviewer, it does not turn Postil into a style linter. Borderline lines are not flagged.
In the envelope and check-runs
Content-policy findings carry kind: "contentPolicy" in the envelope and are otherwise indistinguishable from other findings: same severity levels, same confidence and suppression rules, same inline comments on postil/review. An error-severity contentPolicy finding gates the PR exactly like any other error finding; see the gate.
Hosted reviews
The hosted GitHub App honors .postil.yaml, .postil/guardrails.md, and .postil/content-policy.md from the repository's default branch, the same as local and CI reviews resolve them by default.