From 2f2e35e802b4ab2c4433e231a7aac926451cc626 Mon Sep 17 00:00:00 2001 From: Michele Bigi Date: Sun, 20 Sep 2026 18:24:29 +0200 Subject: [PATCH] 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. --- .cursor/rules/00-coding-constitution.mdc | 216 +++- .cursor/rules/10-architecture.mdc | 407 ++++++- .cursor/rules/20-python.mdc | 32 +- .cursor/rules/30-rust.mdc | 94 +- .cursor/rules/40-testing.mdc | 149 ++- .cursor/rules/50-verification.mdc | 245 ++++- .cursor/rules/60-git-workflow.mdc | 125 ++- docs/development/CODING_CONSTITUTION.md | 1264 ++++++++++++++++++++-- 8 files changed, 2390 insertions(+), 142 deletions(-) diff --git a/.cursor/rules/00-coding-constitution.mdc b/.cursor/rules/00-coding-constitution.mdc index 5c47e85..3ee00f8 100644 --- a/.cursor/rules/00-coding-constitution.mdc +++ b/.cursor/rules/00-coding-constitution.mdc @@ -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. diff --git a/.cursor/rules/10-architecture.mdc b/.cursor/rules/10-architecture.mdc index 39e7358..7db907f 100644 --- a/.cursor/rules/10-architecture.mdc +++ b/.cursor/rules/10-architecture.mdc @@ -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. diff --git a/.cursor/rules/20-python.mdc b/.cursor/rules/20-python.mdc index 6992777..bc7d112 100644 --- a/.cursor/rules/20-python.mdc +++ b/.cursor/rules/20-python.mdc @@ -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. diff --git a/.cursor/rules/30-rust.mdc b/.cursor/rules/30-rust.mdc index d8eee7e..d8b1b07 100644 --- a/.cursor/rules/30-rust.mdc +++ b/.cursor/rules/30-rust.mdc @@ -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/`. diff --git a/.cursor/rules/40-testing.mdc b/.cursor/rules/40-testing.mdc index b371790..0417e74 100644 --- a/.cursor/rules/40-testing.mdc +++ b/.cursor/rules/40-testing.mdc @@ -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. diff --git a/.cursor/rules/50-verification.mdc b/.cursor/rules/50-verification.mdc index 23f46dd..c0c084a 100644 --- a/.cursor/rules/50-verification.mdc +++ b/.cursor/rules/50-verification.mdc @@ -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.** diff --git a/.cursor/rules/60-git-workflow.mdc b/.cursor/rules/60-git-workflow.mdc index cc0ec86..4c60564 100644 --- a/.cursor/rules/60-git-workflow.mdc +++ b/.cursor/rules/60-git-workflow.mdc @@ -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/-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. diff --git a/docs/development/CODING_CONSTITUTION.md b/docs/development/CODING_CONSTITUTION.md index 108fc68..109428e 100644 --- a/docs/development/CODING_CONSTITUTION.md +++ b/docs/development/CODING_CONSTITUTION.md @@ -1,90 +1,1224 @@ -# Periscope Cursor Engineering Rules +# PERISCOPE — CURSOR ENGINEERING RULES -Mandatory for every Cursor agent working on Periscope. Do not invent a weaker local policy. This file is the master; `.cursor/rules/*.mdc` split the same text by section and must not contradict it. +## PURPOSE -## 0. Coding constitution +This document defines the mandatory engineering rules for the Periscope project. -- 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. +These rules are not suggestions. -## 1. Architecture +They define: -Three layers: +* 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. -| 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 | +Cursor must treat these rules as **mandatory project constraints**. -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. +If an implementation conflicts with these rules, the implementation must be changed. -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 silently relax, bypass, reinterpret, or ignore these rules. -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. +--- -Content-addressed datasheets live under `library/datasheets/`. DigiKey matches exact MPN only. Value-string passives stay per-project, never the shared library. +# 1. CREATE THE PROJECT RULE STRUCTURE -Do not add auth, billing, or extra services unless the task needs them. Do not add a second frontend component library. +Create and maintain the following structure: -## 2. Python +```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 -- 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. +docs/ +└── development/ + └── CODING_CONSTITUTION.md +``` -## 3. Rust +The Markdown document is the human-readable master document. -- 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/`. +The `.mdc` files are the operational Cursor rules. -## 4. Testing +The rules must be version-controlled with the project. -- 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. +Do not create contradictory rules in different files. -## 5. Verification +If a conflict exists, resolve the conflict explicitly before continuing development. -- 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. +--- -## 6. Git workflow +# 2. CORE PRINCIPLE -Worktree for this product line: `~/Development/pinscope-tree-split` unless Michele names another. Do not start a second clone to dodge the worktree. +## CODE THAT FITS IN YOUR HEAD -### Phase vs macro-phase +This is the fundamental Periscope engineering principle. -- **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. +> Code must be locally understandable by an engineer without requiring reconstruction of a large hidden abstraction system. -### Other git rules +Prefer: -- Feature branches `cursor/-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. +* 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. + +--- + +# 7. DETERMINISTIC CORE + +The verification core must be deterministic. + +For the same: + +```text +input ++ +configuration ++ +source data +``` + +Periscope must produce the same: + +```text +model +calculations +findings +``` + +Do not make deterministic verification dependent on: + +* LLM output; +* prompts; +* randomness; +* execution order; +* hidden state; +* uncontrolled external state. + +--- + +# 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. + +--- + +# 21. TESTING IS MANDATORY + +Every meaningful implementation change requires tests. + +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. + +--- + +# 25. PHASE GATES + +Development is divided into macro-phases. + +A macro-phase is not complete until: + +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. + +Only then is the macro-phase considered complete. + +--- + +# 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. + +--- + +# 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. + +--- + +# 32. PYTHON IS THE DEFAULT LANGUAGE + +Python is the default implementation language for Periscope. + +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. + +--- + +# 33. RUST IS NOT A DEFAULT + +Rust must not be introduced simply because code is new. + +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. + +--- + +# 37. CORRECTNESS BEFORE PERFORMANCE + +Priority order: + +```text +1. Correctness +2. Semantic integrity +3. Determinism +4. Testability +5. Readability +6. Maintainability +7. Performance +8. Optimization +``` + +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.**