Code Quality
A handful of things here get confused for each other constantly. Syntaxis keeps them apart on purpose — each is answering a genuinely different question, and none of them can stand in for another.
| Proof | The question it actually answers |
|---|---|
| Verify | Do the project’s own checks pass? |
| Check | Does this work satisfy its spec, in the app as it’s actually running? |
| Audit | Is the code sound, secure, and consistent with our standards? |
| Independent audit | Does someone with zero history on this build agree? |
| Check guide | Can a human follow the steps and judge it themselves? |
| Test run | Do the designed cases still hold across areas and platforms? |
None of these substitute for the others. A green pipeline says nothing about behavior. A clean review doesn’t mean the app runs. A passing suite is silent about everything it never touched.
Verify
Section titled “Verify”The project’s own repeatable checks — typecheck, tests, build — defined once
through /ci and written down in AGENTS.md. Local
work and GitHub both run that exact same recipe.
A review across quality, security, performance, and test coverage, either scoped to a branch or run against the whole project, narrowable to a specific lens when that’s all you need.
The rule that matters more than any other here: the ledger never decides what gets reviewed. The code gets looked at fresh every time, and only afterward do findings get recorded. Treating open findings as a checklist — verifying only those — is exactly the failure this exists to prevent, because a repair can introduce a brand-new defect that no existing entry was ever pointing at.
Independent audit
Section titled “Independent audit”Either a genuinely fresh reviewer session, or a configured isolated reviewer child, examines one exact approved checkpoint and leaves behind a receipt: target and base SHAs, the spec’s hash, who was asked to review it versus who actually did, the check result, commands run, evidence, findings, and whatever risk remains.
A later change that actually matters makes that receipt go stale, and
/complete won’t proceed on a stale, pending, or
changes-requested review.
The declared adapter, model, and fresh-context identity are recorded metadata — not cryptographic proof of anything. Syntaxis writes down what ran; it doesn’t claim more certainty than that.
Proportional engineering
Section titled “Proportional engineering”Reviews are held to the same bar builds are:
- New abstractions, dependencies, services, configuration surfaces, or security machinery all need a current requirement behind them.
- When scale is unknown, the smaller and more reversible design wins by default.
- Simplicity is never an excuse to skip real trust-boundary validation, data-loss prevention, accessibility, an explicit security requirement, a configured test, or a project rule.
A pure proportionality complaint sits at P2 or P3. It only climbs to P0 or P1 once an actual code path, a broken contract, or a real security boundary is demonstrated — not just suspected.
Being disciplined about severity
Section titled “Being disciplined about severity”P0 and P1 block completion, so they’re reserved for failures that have
actually been shown to be real. A hunch gets recorded as unverified —
tracked as a lead, without holding up a merge.
See The Findings Ledger for the full mechanics.