Replace paraphrased constitution with the 1224-line master.

Copy CODING_CONSTITUTION.md from the AgentStore docs/development path and split the seven always-on .mdc files from that exact text.
2026-09-20 18:24:29 +02:00
parent 0533d4ebd2
commit 2f2e35e802
8 changed files with 2390 additions and 142 deletions
@@ -2,13 +2,244 @@
 alwaysApply: true
 ---

-# Periscope Cursor Engineering Rules
+# 37. CORRECTNESS BEFORE PERFORMANCE

-Mandatory for every Cursor agent working on Periscope. This section is copied from `docs/development/CODING_CONSTITUTION.md` and must not contradict that master.
+Priority order:

-## 5. Verification
+```text
+1. Correctness
+2. Semantic integrity
+3. Determinism
+4. Testability
+5. Readability
+6. Maintainability
+7. Performance
+8. Optimization
+```

- Verify-then-switch: pytest (or the docs check above) **then** import/path switch, **then** commit+push at phase end.
- Live smoke after a **macro-phase** deploy: version from changelog, health of `/api/auth/mode`, overlay/rewrite modules that should load, users **untouched**.
- Deploy script: `/root/periscope` `./scripts/update-periscope.sh`. Prefer `--no-pull` after the host checkout is already on the intended SHA. Do not let the script generate a new `AUTH_JWT_SECRET` if one exists.
- Do not treat Docker COPY of `src` over `dependency` as proof of a rewrite.
+Performance optimization must not compromise the first six without explicit justification.
+
+---
+
+# 38. MINIMAL PUBLIC APIs
+
+Public APIs must be as small as practical.
+
+Do not expose internal implementation details unnecessarily.
+
+Prefer explicit interfaces.
+
+Avoid API surface growth without a real requirement.
+
+---
+
+# 39. NO DEAD CODE
+
+Remove or explicitly document:
+
+* obsolete code;
+* commented-out implementations;
+* unused imports;
+* unused abstractions;
+* obsolete APIs;
+* temporary workarounds.
+
+Temporary adapters must be clearly identified and have a removal path.
+
+---
+
+# 40. COMMENTS
+
+Comments should explain:
+
+```text
+WHY
+```
+
+rather than simply:
+
+```text
+WHAT
+```
+
+Do not comment obvious code.
+
+Do document:
+
+* non-obvious engineering decisions;
+* semantic constraints;
+* source-specific behavior;
+* intentional limitations;
+* reasons for unusual algorithms;
+* compatibility constraints.
+
+---
+
+# 41. CHANGE MINIMIZATION
+
+For bug fixes:
+
+1. reproduce the problem;
+2. locate root cause;
+3. change the smallest appropriate architectural layer;
+4. add regression test;
+5. run relevant tests;
+6. run full regression;
+7. review the resulting design.
+
+Do not combine unrelated refactoring with a bug fix unless necessary.
+
+---
+
+# 42. NO SPECULATIVE ENGINEERING
+
+Do not invent engineering rules.
+
+Every rule should be based on one of:
+
+```text
+documented requirement
+datasheet/source evidence
+standard
+explicit design intent
+validated engineering inference
+```
+
+If evidence is insufficient:
+
+```text
+INSUFFICIENT_EVIDENCE
+```
+
+---
+
+# 43. DESIGN INTENT IS FIRST-CLASS
+
+Do not assume that every unusual design decision is an error.
+
+Periscope must be able to represent:
+
+```text
+INTENTIONAL_DESIGN
+```
+
+when the evidence supports that interpretation.
+
+The system must distinguish:
+
+```text
+actual violation
+intentional design
+engineering observation
+insufficient evidence
+```
+
+---
+
+# 44. FINDING CATEGORIES
+
+Findings may include:
+
+```text
+ERROR
+RISK
+REFERENCE_DEVIATION
+ENGINEERING_OBSERVATION
+INTENTIONAL_DESIGN
+INSUFFICIENT_EVIDENCE
+```
+
+Do not collapse all deviations into ERROR.
+
+Severity and confidence remain independent.
+
+---
+
+# 45. REVIEW QUESTIONS BEFORE COMPLETING ANY CHANGE
+
+Before declaring a change complete, Cursor must verify:
+
+```text
+Is the implementation correct?
+
+Is the root cause fixed?
+
+Is the semantic model correct?
+
+Is the data flow explicit?
+
+Can the code fit in my head?
+
+Is any abstraction unnecessary?
+
+Is there hidden state?
+
+Are units explicit?
+
+Are engineering constants named?
+
+Are assumptions distinguished from facts?
+
+Are tests strict?
+
+Are negative cases tested?
+
+Are boundary cases tested?
+
+Is insufficient evidence tested?
+
+Could this change create a false positive?
+
+Could this change suppress a true positive?
+
+Is the full regression passing?
+
+Is documentation updated?
+
+Is the macro-phase actually complete?
+```
+
+---
+
+# 46. FINAL ENGINEERING PRINCIPLE
+
+Periscope must not become a clever software system.
+
+It must become a:
+
+```text
+CORRECT
+DETERMINISTIC
+SEMANTICALLY ACCURATE
+TESTABLE
+TRACEABLE
+READABLE
+MAINTAINABLE
+ENGINEERING SYSTEM
+```
+
+The preferred implementation is the simplest one that satisfies those properties.
+
+When two implementations are technically correct, prefer the one with:
+
+* fewer abstractions;
+* fewer dependencies;
+* less hidden state;
+* clearer data flow;
+* smaller modules;
+* smaller APIs;
+* easier testing;
+* easier debugging;
+* clearer semantics.
+
+The governing principle is:
+
+> **CODE THAT FITS IN YOUR HEAD.**
+
+And the governing development discipline is:
+
+> **NO PHASE IS COMPLETE UNTIL ITS TESTS PROVE IT.**
+
+And the governing repository discipline is:
+
+> **COMMIT AND PUSH AT THE PHASE BOUNDARY AFTER TESTS; DEPLOY ONLY AFTER A MACRO-PHASE.**