Have an AI Coding Agent Ship Zero-Warning Code and Honest Reports in a Strict-Build Repo

## Build Only the Changed Module While Iterating, but Validate Fully Before Pushing Use the repository's committed build wrapper rather than a globally installed toolchain, so every contributor and agent builds identically. For fast iteration, build and test only the module you changed instead of the whole multi-module build; there is usually a "fast" profile that skips static-analysis checks and a flag that skips tests. Those shortcuts are for local loops only. Before committing you must run a full compile of the affected module with checks enabled and confirm zero warnings — never commit on the strength of a checks-skipped build. Before pushing, run the project's validation step, which is diff-aware: it classifies the change (docs-only, single-module, or root/config change) and builds only the affected modules plus their dependency closure, while a change to root build config forces a full build. Validation leaves a short-lived marker that the push hook checks. Cancel superseded pipeline runs on your branch before pushing so shared runners are not wasted. ## Never Skip Git Hooks, and Write Short Commit Messages Without AI Signatures Enable the repository's hook path at the start of every working session; sessions may be archived and revived, so this is not a one-time setup. Never bypass the hooks — no verification-skip flag, no signing bypass. The hooks enforce license headers, the absence of unused or duplicate imports, and commit-message format. Write conventional commit subjects in the form type(scope): description, using types such as feat, fix, docs, refactor, test, and chore. Keep each message to at most two non-empty lines, with the first line under about 100 characters. Do not add any trailer lines — no co-author trailer, no sign-off trailer, and above all no AI-authorship or AI-generated signature of any kind; the commit-message hook rejects them. Bug fixes go straight to the main development branch; new features use feature branches. ## Match the Surrounding Style and Treat Every Warning as an Error Match the style of the surrounding code and make the smallest reasonable change to reach the outcome. Every source file must carry the required license header. Prefer composition over inheritance; use a try-with-resources construct for every closeable resource; return an optional wrapper instead of null from public APIs; use local type inference only when the type is obvious from context; prefer switch expressions and pattern matching over long if/else chains; use sealed types and immutable record carriers where they fit; always parameterize generics; annotate overriding methods; build strings with a builder inside loops; and construct unmodifiable collections with the standard factory helpers. Treat every compiler, deprecation, and static-analysis warning as an error. The build runs with all lint checks on and fails on unused or duplicate imports, so zero warnings are required to ship. Do not introduce new warning-suppression annotations without a comment justifying why one is unavoidable, and never delete a code comment unless you can prove it is actively false. ## Let Only the Creator Close a Resource, and Never Ignore Capacity Limits The following invariants are release-blocking regardless of feature scope; violating one blocks the release no matter how small the change. **Ownership** — Only the creator of a resource may release, close, or shut it down. Track ownership explicitly, and when you accept an externally supplied executor, pool, or connection, wrap it so lifecycle calls cannot destroy something you did not create. Every start routine needs a symmetric stop routine that undoes every registration — listeners, handlers, hooks — and every buffer must be released on all terminal and error paths. **Terminal-path completeness** — Every exit path (success, failure, cancel, timeout, reject) must leave the system in a completed state: resolve futures, reset flags, release buffers. Make close idempotent with a compare-and-set or close-once pattern. If a guard checks a counter, some path must actually increment that counter. **Backpressure** — Never ignore rejection or capacity signals. Check the return value of a bounded offer, handle rejected execution, and handle partial writes. Every cache and buffer needs a size bound or an eviction policy; an unbounded structure fed by external input is a denial-of-service vector. ## Validate Input at Every Boundary and Report Only What Is Actually Running These invariants are also release-blocking regardless of feature scope. **Boundary safety** — At every boundary (wire, filesystem, shell, URL, HTTP) validate and encode before interpreting. Decode text only from complete framed messages, never from raw transport chunks. Normalize and validate filesystem paths — resolve, normalize, then confirm the result stays under the intended root, rejecting parent-directory segments, separators, and empty segments. Use argument arrays for shell calls, URL-encode dynamic path and query parts, match content types case-insensitively, and return a client error rather than a server error for malformed input by catching parse failures at the boundary. **Runtime truth** — Advertise and report only confirmed runtime state, never configuration intent or mere classpath presence. Capability flags and discovery endpoints must reflect what is actually running, and feature advertisement must be suppressed when startup fails. **Security** — Every mutating or admin surface requires explicit authentication and authorization, default deny. Integrity verification must fail closed; any fail-open mode must be explicit and non-default. Never ship insecure defaults in production paths — gate them behind explicit opt-in with a startup warning — and examples must not regress this posture. **Mode parity** — If a feature exists in multiple invocation modes (sync, async, stream), the semantics must match: error handling, lifecycle events, observability, and completion behavior. Document and test any intentional difference, and when you add a feature to one path, verify it in all paths. ## Add a Regression Test for Serious Bugs and Ban Empty Tests Every high-severity bug fix must ship with a regression test that reproduces the failing scenario. No placeholder or no-op tests are allowed in required CI lanes — a test that merely asserts a trivial truth is forbidden, and each test must assert the specific behavior it claims to verify. End-to-end tests must assert the feature under test, not merely that a server started. If you must quarantine a flaky test, it needs an owner, an expiry, and a tracking issue, and it must still run in a scheduled lane. Workflow path filters must include every behavior-affecting script and config location for the area under change, or CI will silently skip the very code that was modified. ## Make Examples Call the Real API Instead of Faking It Sample and example apps are the first thing users see, so they must be production-quality, not stubs. Actually use the integration you claim to demonstrate: if an example is named for a real capability it must call that real API, not fake it with an in-memory stand-in. If you cannot make the real integration work, say so and ask for help rather than shipping a disguised mock — comments like "in a real app you would call this" are a red flag that the example is not the real app. Before writing integration code against a third-party library, read its actual API — inspect the dependency artifacts and read the public signatures — and never invent method calls. Prefer the library's provided auto-configuration over manual wiring. Every example must compile and ship with a short README explaining what it does, how to run it, and what the key code shows. Do not create one example per backend variant when a single swappable dependency is the whole point of the abstraction. ## Check Every Claim Against the Code or Git History Before Writing It Every factual claim in docs, changelog entries, commit messages, and user-facing text must correspond to something that exists in the code or the git history. Do not invent features, method names, capability sets, metric numbers, or fix commits; each fabrication costs credibility and has to be chased down and rolled back. Numerical claims require a source — verify a count against the actual code before writing it. Changelog "fixed" and "added" bullets must match real commits: search the log for the change and keep the commit hash in your draft before promoting it; if you cannot find the commit, the fix did not happen. API-surface claims require reading the actual source (field lists, method names) first. A claim that something is shipped, wired, or integrated requires a real production consumer on a path reached from a user action, not merely a service-provider interface or a reference implementation. When a fact cannot be verified, either remove it or mark it explicitly as unverified and ask before publishing. If you catch yourself inventing, stop, do not commit, report the false claim against the ground truth, and fix every copy of it. ## Don't Use Rule Conflicts as an Excuse, and Don't Declare Done Too Early Beyond factual honesty, avoid behavioral dishonesty — framings where each statement is defensible but the whole misleads. Do not fabricate a conflict between two rules to justify the easier path; when rules seem to conflict, the one demanding the harder, safer work almost always governs. Do not cherry-pick which guideline to cite while a contradicting one exists; reconcile them in the open. Do not report a status the rules say to fix silently — if a shared pipeline is broken, fix it and report success rather than narrating the breakage. "It was already broken" or "not my regression" is a description, not an excuse: accountability for shared branches transfers on every change. Do not ask permission for an action the rules already mandate — doing beats asking, so just do the mandated work and keep going on the open items until you are redirected. Do not declare victory mid-task; the honest signal lists what is not yet done alongside what is. When brevity conflicts with a correctness or safety rule, the safety rule wins: verbose-but-correct beats concise-but-unsafe. When you catch one of these patterns, name it, do the work the rule actually mandated, and remember that the apology is not the work. ## Save Decisions and Plans in the Shared Knowledge Base, Not Just in Chat Treat a shared knowledge base as the durable home for structured outputs, because chat is not durable. Read it first for prior decisions, designs, and context before starting structured work, and write durable results back to it rather than leaving them only in a conversation. Route by document type: architecture decisions and design records, phased plans, runbooks and on-call procedures, and audits, analyses, and handoffs each have a designated destination; reference docs that ship live with the code, and directory-scoped specs live in that directory's README. Keep private or local-only identifiers — personal handles, role-play names, machine-specific paths — out of every committed artifact. Use neutral placeholder names in tests and samples, and a real identifier only where it genuinely refers to a public account. When the durable store is unavailable, fall back to a shareable link and record it so a later session can file it in the right place.