periscope/docs/development/CODING_CONSTITUTION.md

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

## 0. Coding constitution

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

## 1. Architecture

Three layers:

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

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.

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.

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.

Do not add auth, billing, or extra services unless the task needs them. Do not add a second frontend component library.

## 2. Python

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

## 3. Rust

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

## 4. Testing

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

## 5. Verification

- 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

Worktree for this product line: `~/Development/pinscope-tree-split` unless Michele names another. Do not start a second clone to dodge the worktree.

### Phase vs macro-phase

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

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