periscope/.cursor/rules/00-coding-constitution.mdc

---
alwaysApply: true
---

## PURPOSE

This document defines the mandatory engineering rules for the Periscope project.

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.

---