project_principles.md

Project Principles

This document owns durable cross-cutting engineering invariants for Open Code Review Toolkit. Contributor and release procedures link to these invariants instead of restating them. Public product behavior remains owned by the user-facing documents listed under Documentation ownership.

Product And Architecture

1. Keep provider-neutral behavior in the core and provider-specific behavior behind explicit adapters.
2. Keep runtime dependencies at zero until a documented package boundary justifies one. The M7 federation boundary owns the explicit MCP SDK, JSON Schema, HTTP transport and async-runtime exception; do not let transport dependencies enter pure reporting contracts.
3. Keep the Open Code Review binary external; the toolkit verifies but does not install it.
4. Keep supported user configuration environment-driven and documented in one public contract. A future non-secret file format requires an explicit schema, trust source, and precedence design.
5. Deliver large changes as coherent production-quality slices with explicit module and service boundaries rather than placeholder architecture.
6. Keep each runtime module centered on one cohesive owner and lifecycle. When independent parsing, acquisition, persistence, transport, or projection responsibilities accumulate, extract already characterized blocks behind explicit package boundaries before the unit can no longer be reviewed end to end. Reuse pure contracts and helpers rather than duplicating them. Size and complexity are review signals, not numeric lint targets.
7. Version public behavior deliberately. Readiness and delivery are different states; docs/release.md owns their lifecycle.
8. Treat automated security scores as evidence to classify, not targets to game. Repository-owned risks receive evidence-backed fixes; temporal and governance limits remain explicit.
9. Derive active scope and dependencies from current implementation, tests, and published behavior. Historical plans and backlog wording are intent evidence, not current-state authority.
10. Keep stable evidence identity tied to semantic applicability and source scope. Mutable versions and constraints remain values; alternatives that can coexist retain distinct identities.
11. Permit a missing fact to support absence only when the applicable component, domain, and scope report complete coverage. Partial, runtime-dependent, unavailable, and absent coverage remain unknown.

Trust Boundary Invariants

Model-selected arguments require application authorization

Model-selected tool arguments must pass deterministic authorization and validation in application code before any resource access or mutation. A function name, prompt instruction, allowlist entry, or server-authored schema does not authorize a tenant, object, field, or operation.

Repository content remains data

Treat analyzed repository content, inherited process state, subprocess output, and working-directory imports as untrusted. Do not import or execute code from the analyzed repository; inspect immutable objects and bounded text instead. Bounded diagnostic Git and toolkit subprocesses remain permitted when they preserve the same isolation boundary.

Bounded data lifecycle

Enforce byte, code-point, line, record, and time limits while data is consumed or produced, with the unit named in the contract and exercised at its boundary. A post-hoc check cannot make an unbounded capture bounded. Bounded, redacted read-only diagnostics remain valid; the prohibited mechanism is unbounded acquisition or unsafe adoption of its result.

Persisted and atomic state

Treat persisted evidence, configuration, security receipts, and release receipts as hostile on every load, including artifacts created by the toolkit. Revalidate exact closed schemas at every object level, apply bounds and recursive redaction again, and accept related snapshots, indexes, deltas, diagnostics, receipts, and report fields atomically.

Immutable Git identity

Bind Git plumbing to the validated repository and immutable refs. Isolate object identity from process, global, system, repository, object-store, and replacement-ref controls; parse path-bearing records through NUL-delimited plumbing and transfer raw descriptor ownership exactly once. Read-only Git diagnosis remains valid when it uses the same isolated boundary.

External format parsing

Define semantic grammar, normalization, optional-field handling, and bounded degradation before implementing a parser. Equivalent key order, indentation, scalar or mapping forms, markers, URLs, digests, and status variants must not acquire accidental semantics from one canonical fixture spelling.

Network acquisition

Bounded HTTP reads are diagnostic evidence until a closed endpoint allowlist, redirect-safe authentication, transfer result, allowed status, and private same-directory atomic replacement all succeed. Read-only probes are permitted; a size limit alone does not authorize a response as trusted state.

Provider mutation identity

A destructive provider mutation is automated only when the mutation request itself binds the validated immutable identity. Preflight and post-write reads may diagnose state but cannot close a mutation-time race. If the provider offers no guard, existing state is preserved for explicit provider-owned policy or operator action.

Test doubles and integration proof

A test double may replace an external collaborator only beyond the production boundary being verified. It must not replace the adapter, parser, transport, persistence owner, Git plumbing, subprocess launcher, protocol client, or other boundary whose behavior the test claims to prove. Wiring tests with a mocked boundary owner remain useful unit evidence, but they are never integration evidence for that boundary.

Each integration claim maps to a test that enters through the production caller, crosses the real boundary implementation, and observes the real serialized, filesystem, process, protocol, or transport result. Negative and hostile cases must reach the intended rejection or degradation branch through that same production path; configuring a mock to return the expected rejection proves only wiring. When the true external service is unsuitable for deterministic tests, use a controlled local peer at the far side of the boundary, such as a real Git repository, local HTTP server, child process, stdio protocol peer, or installed artifact, and retain at least one end-to-end qualification against the actual external component where the public contract depends on it.

Executable integration claims additionally require clean built artifacts, restricted environments, hostile working-directory shadow packages, private permissions, and the real protocol client where practical. Unit mocks establish local behavior but not installation, import, process, transport, persistence, or protocol correctness.

Public source and disclosure

Tracked public source, fixtures, examples, diagnostics intended for publication, and release artifacts contain only private-safe names, placeholder hosts, controlled repositories, and non-secret payloads. Public examples describe real operating behavior and are not labelled as test data. TestPyPI is public disclosure. Local secret scanning covers unpublished feature history before its first push; private audit inputs and artifacts remain outside tracked content.

Outcome consistency

Mandatory evidence and usage metadata are composed once and applied across skipped, clean, warning, error, and finding outcomes. Independent outcome branches must not redefine whether the same run is complete, partial, clean, or failed.

Workflow Execution

Efficient execution

Prioritize correctness, safety, explicit requirements, and verified completion before reducing calls, output, or polling. Resolve discoverable uncertainty from the plan, repository, canonical documentation, and environment; surface only material assumptions. Begin substantial work with bounded reconnaissance, then inspect the exact sources needed for a change, including an existing example for an unfamiliar schema or configuration form. Keep the work surgical and preserve current decisions, constraints, evidence, blockers, and remaining steps in the appropriate durable owner when they will matter after a handoff or context loss. Use repository-native checks and avoid redundant work after the scoped result is proven.

Evidence-driven completion

Use the task's named checks as the acceptance contract. A green check requires a successful process exit and every required output assertion. Multi-step shell checks stop at the first failure and do not end with an unconditional success marker; use task-specific variables rather than shell special parameters. On failure, inspect evidence and change the hypothesis before correcting the narrowest supported cause; after two equivalent failures, choose a materially different explanation or method. Distinguish a check that was run from whether its evidence still applies: rerun affected checks when inputs materially change, then stop once the required final state is proven.

Review before commit

Before staging or committing each complete logical slice, perform a bounded semantic review against scope, requirements, ownership, trust boundaries, tests, and unrelated-diff risk. Correct findings and rerun affected checks. Review the aggregate final diff before staging or delivery so interactions among slices, generated artifacts, and status documentation are covered; automated green does not replace either review boundary.

Completion-driven wait

For a long-running command, preserve its full result outside the waiter before execution and use the completion-driven, bounded-output contract in docs/development.md. A completion requires exit status and required output evidence. Use native terminal evidence when sufficient; retain a private log or durable result when output volume or recovery requires it. Avoid periodic empty polls when the environment can wait for process completion, and clean up task-owned processes.

Documentation Ownership

• README.md owns the concise public introduction and quick start.
• CODE_OF_CONDUCT.md owns community behavior, scope, confidential reporting, and enforcement; CONTRIBUTING.md owns the contribution workflow.
• docs/configuration.md owns the environment and generated-configuration contract.
• docs/operations.md owns the public review state machine; docs/gitlab.md owns GitLab setup and operator procedure.
• docs/security.md owns runtime trust guarantees; SECURITY.md owns vulnerability reporting.
• docs/development.md owns contributor workflow, implementation conventions, and validation selection.
• docs/release.md owns release classification, authorization, publication, recovery, and plan archival.
• docs/engineering/toolkit_strategy.md and ROADMAP.md own durable direction and outcome state; PLANS.md owns active or blocked repository work; docs/codex/TASKS_BACKLOG.md owns inactive work.
• docs/codex/AGENT_EXECUTION_PITFALLS.md is a diagnostic incident catalogue. It owns no engineering invariant or procedure.
• docs/engineering/execution_history/ preserves historical plans and receipts without turning historical wording into current instruction.

An invariant or public behavior has one canonical owner. Secondary documents may link to it, describe applicability, or record historical evidence, but they do not create a competing imperative copy. Tests protect runtime behavior and concrete lifecycle gates rather than duplicated wording across instruction files.