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,20 +2,208 @@
 alwaysApply: true
 ---
-# Periscope Cursor Engineering Rules
+## PURPOSE
-Mandatory for every Cursor agent working on Periscope. This section is copied from `docs/development/CODING_CONSTITUTION.md` and must not contradict that master.
+This document defines the mandatory engineering rules for the Periscope project.
-## 0. Coding constitution
+These rules are not suggestions.
 They define:
 * repository structure;
 * coding standards;
 * architectural principles;
 * semantic modeling rules;
 * Python/Rust language policy;
 * testing requirements;
 * verification requirements;
 * Git workflow;
 * commit/push/deployment policy;
 * development-phase discipline.
 Cursor must treat these rules as **mandatory project constraints**.
 If an implementation conflicts with these rules, the implementation must be changed.
 Do not silently relax, bypass, reinterpret, or ignore these rules.
 ---
 # 1. CREATE THE PROJECT RULE STRUCTURE
 Create and maintain the following structure:
 ```text
 .cursor/
 └── rules/
    ├── 00-coding-constitution.mdc
    ├── 10-architecture.mdc
    ├── 20-python.mdc
    ├── 30-rust.mdc
    ├── 40-testing.mdc
    ├── 50-verification.mdc
    └── 60-git-workflow.mdc
 docs/
 └── development/
    └── CODING_CONSTITUTION.md
 ```
 The Markdown document is the human-readable master document.
 The `.mdc` files are the operational Cursor rules.
 The rules must be version-controlled with the project.
 Do not create contradictory rules in different files.
 If a conflict exists, resolve the conflict explicitly before continuing development.
 ---
 # 2. CORE PRINCIPLE
 ## CODE THAT FITS IN YOUR HEAD
 This is the fundamental Periscope engineering principle.
 > Code must be locally understandable by an engineer without requiring reconstruction of a large hidden abstraction system.
 Prefer:
 * small modules;
 * small functions;
 * one responsibility;
 * explicit dependencies;
 * explicit data flow;
 * simple data structures;
 * precise names;
 * deterministic behavior;
 * minimal public APIs;
 * composition over inheritance.
 Avoid:
 * huge functions;
 * god classes;
 * deep inheritance;
 * speculative abstractions;
 * hidden state;
 * magic behavior;
 * global mutable state;
 * unnecessary frameworks;
 * premature optimization;
 * unnecessary indirection.
 A function around 40–60 lines is a warning signal, not an absolute limit.
 The actual rule is local comprehensibility.
 A 20-line function can violate the rule if it contains too many responsibilities.
 A longer function may be acceptable if its structure remains obvious and justified.
 ---
 # 3. ONE RESPONSIBILITY
 Every function and module must have one primary responsibility.
 Prefer:
 ```text
 parse
    ↓
 normalize
    ↓
 build model
    ↓
 analyze
    ↓
 produce finding
    ↓
 report
 ```
 Avoid a single function that:
 * parses input;
 * modifies the model;
 * performs analysis;
 * accesses external services;
 * formats output;
 * writes files;
 * handles errors;
 * and generates reports.
 Separate responsibilities.
 ---
 # 4. EXPLICIT DATA FLOW
 Periscope must have explicit data flow.
 Prefer:
 ```text
 SOURCE
  ↓
 PARSER
  ↓
 NORMALIZED MODEL
  ↓
 ANALYZER
  ↓
 FINDING
  ↓
 REPORT
 ```
 Avoid hidden communication through:
 * global variables;
 * singleton state;
 * implicit registries;
 * hidden caches;
 * ambient configuration;
 * side effects;
 * undocumented environment state.
 If a function needs important information, that information must be visible in its inputs or clearly owned state.
 ---
 # 5. NO SPECULATIVE ABSTRACTION
 Do not introduce an abstraction merely because it might become useful later.
 Do not create unnecessary:
 * factories;
 * generic managers;
 * service layers;
 * repository layers;
 * plugin systems;
 * inheritance hierarchies;
 * generic object wrappers;
 * framework-like internal infrastructure.
 Implement the actual requirement first.
 Abstract only when there is a concrete and demonstrated reason.
 ---
 # 6. COMPOSITION OVER INHERITANCE
 Prefer composition.
 Avoid deep class hierarchies.
 Inheritance must have a clear semantic reason.
 Do not use inheritance merely to share a few methods.
 ---
 - You are implementing Periscope (schematic/PCB validation), not a generic scaffold and not Faradworks/PinScope under a new name.
 - Prefer original Periscope source in `periscope/src` over copying PinScope. Overlay stamps, `cp` of `periscope/dependency/**`, and near-identical pastes do **not** create architectural or AGPL independence.
 - Keep `periscope/dependency/` until a rewritten slice is proven. Never empty-delete inherited files to “look native.”
 - Auto-place / pcbnew write-back is out of scope unless Michele explicitly asks.
 - Never touch live auth users, password hashes, or `AUTH_JWT_SECRET` unless Michele explicitly orders a credential change in that turn.
 - Never swallow exceptions with bare `except: continue`. Log or re-raise.
 - Match existing public contracts (Pydantic models, REST shapes, finding engine). Frontend types stay in sync with backend models.
 - AGPL-3.0 of the fork stays visible. Do not relicense. Do not detach the GitHub fork unless Michele and counsel say so.
 - Gateway-owned seams stay stub-shaped (`billing_hook.get_billing()`, frontend auth/billing pass-throughs). Do not import Clerk/Stripe SDKs outside those seams.
 - Skills stay local (`skills/*/SKILL.md` + `validate.py` on DeepSeek). Do not run `scripts/upload_skills.py`.
 - Default LLM path is DeepSeek. Do not route live stages to Anthropic Console.
@@ -2,26 +2,405 @@
 alwaysApply: true
 ---
-# Periscope Cursor Engineering Rules
+# 7. DETERMINISTIC CORE
-Mandatory for every Cursor agent working on Periscope. This section is copied from `docs/development/CODING_CONSTITUTION.md` and must not contradict that master.
+The verification core must be deterministic.
-## 1. Architecture
+For the same:
-Three layers:
+```text
 input
 +
 configuration
 +
 source data
 ```
-| Layer | Location | Purpose |
+Periscope must produce the same:
 | --- | --- | --- |
 | Core | `backend/periscopex/` (native under `periscope/src` when split) | Models, parsers, graph, validator, passives, taxonomy, derating |
 | Backend | `backend/` | FastAPI, pipeline, SSE, storage |
 | Frontend | `frontend/` | Next.js app: dashboard, progress, report, derating, admin |
-Physical split (when present): `periscope/src` = Periscope; `periscope/dependency` = inherited PinScope in-tree. Docker copies dependency then src so native files win **only when they are real replacements**, not stamped copies.
+```text
 model
 calculations
 findings
 ```
-Import switch rule: keep calling `dependency/` until pytest + deploy smoke pass for that slice, then switch imports. Fail-soft: if verification fails, leave the inherited path.
+Do not make deterministic verification dependent on:
-Netlist is a queryable bipartite graph (components + nets). Deterministic checks beat heuristics. Finding normalization is downgrade-only. Cross-IC excerpt budget is global plus per-neighbor.
+* LLM output;
 * prompts;
 * randomness;
 * execution order;
 * hidden state;
 * uncontrolled external state.
-Content-addressed datasheets live under `library/datasheets/`. DigiKey matches exact MPN only. Value-string passives stay per-project, never the shared library.
+---
 # 8. LLM ROLE
 LLMs may be used for:
 * extraction;
 * classification;
 * datasheet interpretation;
 * explanation;
 * hypothesis generation;
 * assistance.
 LLMs must not be the authoritative deterministic verification engine.
 The intended architecture is:
 ```text
 SOURCE
  ↓
 STRUCTURED REQUIREMENT
  ↓
 DETERMINISTIC ANALYZER
  ↓
 FINDING
  ↓
 OPTIONAL LLM EXPLANATION
 ```
 Not:
 ```text
 SOURCE
  ↓
 LLM
  ↓
 probably wrong
 ```
 ---
 # 9. EVIDENCE BEFORE CONCLUSION
 Every engineering conclusion must be traceable to evidence.
 Where applicable, preserve:
 ```text
 observed fact
 requirement
 source
 calculation
 assumption
 conclusion
 confidence
 severity
 ```
 Do not silently transform assumptions into facts.
 ---
 # 10. REQUIREMENT STRENGTH
 Requirements must preserve their strength.
 Use:
 ```text
 MANDATORY
 RECOMMENDED
 TYPICAL
 EXAMPLE
 ENGINEERING_INFERENCE
 ```
 Do not convert:
 ```text
 RECOMMENDED
 ```
 into:
 ```text
 MANDATORY
 ```
 Do not convert an example into an absolute rule.
 Do not convert an engineering inference into documented manufacturer information.
 ---
 # 11. SEVERITY AND CONFIDENCE ARE INDEPENDENT
 A finding must be able to represent independent:
 ```text
 severity
 confidence
 ```
 Examples that are valid:
 ```text
 ERROR + LOW confidence
 RISK + HIGH confidence
 ```
 Do not use confidence as a substitute for severity.
 ---
 # 12. INSUFFICIENT EVIDENCE
 If the available information is insufficient to establish a conclusion:
 ```text
 INSUFFICIENT_EVIDENCE
 ```
 must be used.
 Never invent missing engineering information.
 Never invent:
 * electrical limits;
 * timing values;
 * pin functions;
 * voltages;
 * currents;
 * tolerances;
 * PCB rules;
 * thermal limits;
 * datasheet requirements.
 Missing evidence is not permission to guess.
 ---
 # 13. SEMANTIC MODEL FIRST
 Periscope must preserve domain semantics.
 At minimum, distinguish concepts such as:
 ```text
 Project
 Component
 Pin
 Footprint
 Pad
 Net
 Via
 Track
 Zone
 PowerRail
 SignalGroup
 TimingEvent
 Requirement
 Constraint
 DesignIntent
 Evidence
 Finding
 ```
 Do not collapse semantically different physical objects into one generic object merely because they share coordinates, nets, or attributes.
 ---
 # 14. SEMANTIC IDENTITY MUST SURVIVE TRANSFORMATIONS
 A transformation must preserve the semantic identity of objects.
 For example:
 ```text
 PCB Via
 ```
 must never become:
 ```text
 Component Pad
 ```
 merely because:
 * it is close to a footprint;
 * it is inside a footprint area;
 * it is connected to GND;
 * it shares a net;
 * it has coordinates similar to a pad.
 Similarly:
 ```text
 Pad ≠ Via
 Track ≠ Via
 Zone ≠ Pad
 Component Pin ≠ PCB Via
 ```
 This is a fundamental Periscope rule.
 ---
 # 15. ROOT CAUSE OVER SYMPTOM
 When a false positive or incorrect result is discovered:
 Do not simply suppress the finding.
 Determine where the representation first becomes incorrect.
 Example:
 ```text
 PCB
 ↓
 parser
 ↓
 incorrect model
 ↓
 correct analyzer operating on incorrect model
 ↓
 incorrect finding
 ```
 The fix belongs in the model/parser boundary, not necessarily in the analyzer.
 Always investigate the complete chain:
 ```text
 source
 → parser
 → normalized representation
 → semantic model
 → analyzer
 → finding
 → report
 ```
 ---
 # 16. NO COMPONENT-SPECIFIC HACKS
 Do not fix architecture problems with:
 ```text
 if component == U1
 ```
 or:
 ```text
 if footprint == X
 ```
 or:
 ```text
 if net == GND
 ```
 or hard-coded corrections such as:
 ```text
 subtract N
 ignore N
 force expected count
 ```
 unless the condition represents a genuine documented engineering rule.
 A bug in generic PCB semantics must receive a generic semantic fix.
 ---
 # 17. PHYSICAL SEMANTICS
 Periscope is an electronic design verification system.
 Its internal model must reflect physical reality.
 Geometric proximity does not establish semantic identity.
 For example:
 ```text
 Via located inside footprint
 ```
 does not imply:
 ```text
 Via belongs to component as a pad
 ```
 unless the PCB data model explicitly establishes that relationship.
 Do not infer component relationships solely from proximity when stronger source information exists.
 ---
 # 18. UNITS MUST BE EXPLICIT
 Use explicit units.
 Prefer:
 ```text
 width_mm
 delay_ns
 frequency_hz
 voltage_v
 current_a
 temperature_c
 ```
 over ambiguous variables such as:
 ```text
 width
 delay
 value
 limit
 ```
 when unit ambiguity is possible.
 Never rely on undocumented implicit units.
 ---
 # 19. NAMED CONSTANTS
 Avoid magic numbers.
 Prefer:
 ```text
 MIN_SUPPLY_V
 MAX_TRACE_LENGTH_MM
 DEFAULT_SPI_CLOCK_HZ
 ```
 over unexplained numeric literals.
 Engineering constants must have traceable sources where appropriate.
 ---
 # 20. ERROR CATEGORIES
 Distinguish:
 ```text
 tool failure
 data failure
 analysis result
 insufficient evidence
 engineering violation
 ```
 Do not collapse fundamentally different failure modes into one generic error.
 ---
 Do not add auth, billing, or extra services unless the task needs them. Do not add a second frontend component library.
@@ -2,17 +2,27 @@
 alwaysApply: true
 ---
-# Periscope Cursor Engineering Rules
+# 32. PYTHON IS THE DEFAULT LANGUAGE
-Mandatory for every Cursor agent working on Periscope. This section is copied from `docs/development/CODING_CONSTITUTION.md` and must not contradict that master.
+Python is the default implementation language for Periscope.
-## 2. Python
+Use Python for:
 * orchestration;
 * datasheet processing;
 * document parsing;
 * LLM integration;
 * requirement extraction;
 * evidence management;
 * project management;
 * CLI;
 * API integration;
 * reporting;
 * test orchestration;
 * external tool integration;
 * high-level analysis.
 Do not rewrite Python into Rust merely because Rust exists in the project.
 ---
 - Python 3.12+, Pydantic 2.x, FastAPI on the backend.
 - Parsers and graph builders are pure functions without hidden I/O, except documented loaders (`build_graph` from paths).
 - All shared data structures are Pydantic models in `backend/periscopex/models.py` (or the native successor once rewritten).
 - Tests live under `tests/` against `simple_project/` as ground truth. Emmaforo behavior is a live spec, not a license to skip unit tests.
 - Extraction prompts live in `skills/` and run in-process. Bump `default_model_version` in `skills_manifest.json` when skill prompts change; never call Anthropic Console.
 - Use stdlib hashing (`hashlib.scrypt` in `local_users.hash_password`) for local passwords. Do not invent a homemade hash.
 - `repo_paths.py` locates taxonomy, skills, vendor, changelog. Do not hard-code `/app` without the Docker heuristic that also requires `vendor/`.
 - Format and lint with the repo’s existing tools. Do not drive-by reformat unrelated files.
@@ -2,13 +2,93 @@
 alwaysApply: true
 ---
-# Periscope Cursor Engineering Rules
+# 33. RUST IS NOT A DEFAULT
-Mandatory for every Cursor agent working on Periscope. This section is copied from `docs/development/CODING_CONSTITUTION.md` and must not contradict that master.
+Rust must not be introduced simply because code is new.
-## 3. Rust
+Rust is justified only when there is a demonstrated engineering requirement.
 Valid reasons include:
 * measured performance bottleneck;
 * computationally intensive geometry;
 * large-scale spatial processing;
 * numerical computation;
 * graph processing;
 * memory pressure;
 * deterministic high-performance computation.
 Do not use Rust speculatively.
 ---
 # 34. MEASURE BEFORE MOVING TO RUST
 Required sequence:
 ```text
 correct implementation
 ↓
 measurement
 ↓
 profiling
 ↓
 identified bottleneck
 ↓
 Rust implementation
 ↓
 benchmark
 ↓
 accept/reject based on evidence
 ```
 Do not introduce Rust based on assumptions about performance.
 ---
 # 35. RUST BOUNDARIES MUST BE COARSE-GRAINED
 Prefer:
 ```text
 Python
   ↓
 structured input
   ↓
 Rust engine
   ↓
 structured result
   ↓
 Python
 ```
 Avoid excessive Python ↔ Rust calls for individual operations.
 Rust should encapsulate meaningful computational workloads.
 ---
 # 36. DO NOT PREMATURELY FREEZE THE CORE IN RUST
 The semantic model should first become correct and well understood.
 Prefer:
 ```text
 semantic model
 ↓
 correctness
 ↓
 tests
 ↓
 architecture stabilization
 ↓
 profiling
 ↓
 Rust where justified
 ```
 Do not rewrite the entire Periscope core in Rust simply to establish a Rust architecture.
 ---
 - Periscope’s product code is Python/TypeScript today. If a Rust crate is added, it is original Periscope code, not a paste of an AGPL PinScope module.
 - Rust slices follow the same verify-then-switch rule: tests first, then wire into the Python/TS surface.
 - Use `rustfmt` + `clippy` on that crate. No `unsafe` without a comment that names the invariant.
 - Do not introduce Rust to dodge AGPL or to empty-delete Python in `dependency/`.
@@ -2,15 +2,146 @@
 alwaysApply: true
 ---
-# Periscope Cursor Engineering Rules
+# 21. TESTING IS MANDATORY
-Mandatory for every Cursor agent working on Periscope. This section is copied from `docs/development/CODING_CONSTITUTION.md` and must not contradict that master.
+Every meaningful implementation change requires tests.
-## 4. Testing
+At minimum test:
 ```text
 normal case
 failure case
 boundary case
 insufficient evidence
 ```
 For semantic models, also test the boundaries between object types.
 For PCB analysis, explicitly test:
 ```text
 Pad
 Via
 Track
 Zone
 ```
 as distinct semantic entities.
 ---
 # 22. TESTS MUST BE STRICT AND ABSOLUTE
 Periscope tests are not advisory.
 A test must define the exact expected behavior.
 Do not use vague assertions such as:
 ```text
 result is reasonable
 result is not empty
 analysis completed
 ```
 when an exact result can be established.
 Prefer assertions such as:
 ```text
 expected object type == Via
 expected pad count == 24
 expected finding count == 0
 expected finding code == X
 expected severity == ERROR
 expected confidence == HIGH
 ```
 Where deterministic exact values are available, test them exactly.
 Do not weaken tests merely to make an implementation pass.
 Do not modify expected results to accommodate incorrect implementation behavior.
 ---
 # 23. REGRESSION TEST FOR EVERY BUG
 Every fixed bug must become a regression test.
 Required sequence:
 ```text
 BUG
 ↓
 REPRODUCE
 ↓
 TEST FAILS
 ↓
 FIX
 ↓
 TEST PASSES
 ↓
 FULL REGRESSION
 ```
 A bug fix is not complete until the original failure is permanently represented by a test.
 ---
 # 24. TEST THE NEGATIVE CASE
 Do not test only:
 ```text
 valid → pass
 ```
 Also test:
 ```text
 invalid → fail
 ```
 and ensure that genuine errors remain detectable.
 For example, if fixing:
 ```text
 24 datasheet pins
 24 footprint pads
 N vias
 ```
 verify that:
 ```text
 24 datasheet pins
 23 footprint pads
 ```
 still produces a real mismatch.
 The fix must remove false positives without suppressing true positives.
 ---
 # 26. NO WEAKENING TESTS TO CLOSE A PHASE
 Do not:
 * delete failing tests;
 * weaken assertions;
 * skip tests;
 * mark tests expected-to-fail;
 * suppress failures;
 * change expected values without engineering justification;
 simply to make a macro-phase pass.
 If a test exposes a real implementation problem, fix the implementation.
 If the requirement itself is wrong, change the requirement explicitly and document why.
 ---
 - Write tests before considering a slice done. Prefer tests that lock behavior (graph topology, finding codes, via≠pad, review isolation) over tests that assert overlay stamps or file provenance comments.
 - `pytest` from the worktree with the project venv. Do not claim green from a system Python missing deps.
 - One malformed IC must not kill the whole review; keep per-IC isolation tests.
 - Do not add tests whose only job is to require `Native Periscope overlay` in a copied file.
 - UI changes: exercise the flow (not a single screenshot). If no browser tools, say what was not verified.
 - Installing docs/rules is a docs phase: existence and internal consistency of the seven `.mdc` files plus this master is the check. There is no product pytest gate for markdown-only.
@@ -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.
+Performance optimization must not compromise the first six without explicit justification.
- 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.
+
 # 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.**
@@ -2,25 +2,120 @@
 alwaysApply: true
 ---
-# Periscope Cursor Engineering Rules
+# 25. PHASE GATES
-Mandatory for every Cursor agent working on Periscope. This section is copied from `docs/development/CODING_CONSTITUTION.md` and must not contradict that master.
+Development is divided into macro-phases.
-## 6. Git workflow
+A macro-phase is not complete until:
-Worktree for this product line: `~/Development/pinscope-tree-split` unless Michele names another. Do not start a second clone to dodge the worktree.
+1. implementation is complete;
 2. all required tests exist;
 3. all required tests pass;
 4. full regression passes;
 5. relevant integration tests pass;
 6. static/type/lint checks pass where applicable;
 7. no known blocker remains;
 8. documentation is updated;
 9. results have been reviewed;
 10. the phase acceptance criteria are satisfied.
-### Phase vs macro-phase
+Only then is the macro-phase considered complete.
- **Phase** (one verified slice: e.g. rules install, one rewritten module with tests): when tests (or the docs check) pass → **commit and push**. That is the end of the phase.
+---
 - **Macro-phase** (a named batch of phases Michele treats as one shippable increment): **deploy only after a macro-phase**, not after every phase, and not at a mere phase boundary.
 - **No commit, push, or deploy on every small edit.** Edit, keep working, commit when the phase is actually done.
 - **No deploy at a mere phase boundary.** Passing tests + push is not a deploy order.
-### Other git rules
+# 27. PHASE COMMIT AND PUSH POLICY
 Do not commit after every small implementation step merely for convenience.
 During a **phase**:
 ```text
 implement
 → test
 → fix
 → test
 ```
 The repository may contain intermediate working-tree changes.
 At the **end of each phase**, after tests pass:
 ```text
 PHASE TESTS
        ↓
 COMMIT
        ↓
 PUSH
 ```
 Commit and push belong to the **phase** boundary, not to every edit.
 Do not push broken or half-completed phase work merely to synchronize the repository.
 ---
 # 28. MACRO-PHASE DEPLOY POLICY
 **Deploy** happens only after a **macro-phase**, not after every phase.
 A macro-phase may contain several phases (each already committed and pushed after its tests).
 Never deploy an incomplete macro-phase.
 Required sequence for a macro-phase:
 ```text
 PHASES (each: implement → test → commit → push)
 ↓
 FULL REGRESSION
 ↓
 MACRO-PHASE ACCEPTANCE
 ↓
 DEPLOY
 ↓
 POST-DEPLOY VERIFICATION
 ```
 If deployment verification fails, stop and investigate.
 ---
 # 29. NO DEPLOY AT PHASE BOUNDARY
 Commit + push after phase tests: **yes**.
 Deploy after a phase that is not a completed macro-phase: **no**.
 ---
 # 30. NO AUTOMATIC COMMIT/PUSH/DEPLOY DURING DEVELOPMENT
 Cursor must not create commits, push, or deploy merely because a small task has finished.
 Commit and push are **phase-boundary** operations (after tests).
 Deploy is a **macro-phase-boundary** operation.
 If explicitly instructed to deploy before a macro-phase is complete, Cursor must identify the conflict with this policy rather than silently proceeding.
 ---
 # 31. GIT HISTORY IS ENGINEERING EVIDENCE
 Do not rewrite Git history casually.
 Do not:
 * force-push;
 * squash history;
 * rewrite commits;
 * detach repository history;
 unless explicitly required by the project phase and explicitly authorized.
 Git history may be relevant to provenance and licensing analysis.
 Preserve it.
 ---
 - Feature branches `cursor/<descriptive-name>-0d9d` (lowercase). Do not force-push unless Michele explicitly orders it.
 - Do not create pull requests unless Michele asks.
 - Push `origin` and `github` when this worktree has both remotes.
 - Do not commit secrets, `data/auth/users`, or `.env` password material.
 - Changelog version is the latest `## x.y.z` in `frontend/content/changelog.md` (dependency copy is the Docker source of truth today). Bump only when the phase is a product change, not for docs-only rules unless Michele wants a version bump.