36 lines
1.8 KiB
Markdown
36 lines
1.8 KiB
Markdown
Please review `docs/development.md` for initial orientation in this repository
|
|
and follow its task-specific reading guide.
|
|
|
|
## Implementation Discipline
|
|
|
|
Simplify the mechanism, not the user's choices.
|
|
|
|
**Keep implementation machinery proportionate.** Use straightforward,
|
|
idiomatic code and introduce only the machinery needed to support the requested
|
|
behavior and flexibility. Optimize for conceptual simplicity and
|
|
maintainability, not for the fewest lines, fewest options, or narrowest product
|
|
surface.
|
|
|
|
**Do not invent restrictions.** Do not reject, prohibit, constrain, cap,
|
|
harden, or otherwise narrow behavior unless required by the user, an explicit
|
|
repository contract, or an unavoidable correctness constraint. Preserve
|
|
operator and caller choice where policy has not been established. If an
|
|
additional restriction appears advisable, present it as a decision rather than
|
|
silently implementing it.
|
|
|
|
A correctness constraint must follow from the requested behavior or an
|
|
established invariant, not from the convenience of the chosen implementation.
|
|
Explain the specific failure it prevents and why a less restrictive
|
|
implementation cannot satisfy the contract.
|
|
|
|
**An implementation detail is not repository policy.** Tests and documentation
|
|
must not elevate incidental behavior into a durable guarantee or restriction
|
|
unless that behavior was expressly selected as part of the contract. Existing
|
|
explicit contracts remain authoritative; changing or weakening one requires a
|
|
deliberate decision rather than being inferred from this principle.
|
|
|
|
Agent-authored plans, tests, documentation, and prior implementations are not
|
|
evidence that an additional restriction was deliberately approved. Identify the
|
|
authorizing requirement or decision; when that authority is unclear, surface
|
|
the ambiguity rather than treating repetition as approval.
|