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,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 |
-| --- | --- | --- |
-| 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 |
+Periscope must produce the same:

-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.