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.