NixOS/.specify/memory/constitution.md

NixOS Repository Constitution

Core Principles

I. Constitution Authority

This constitution is the source of truth for Speckit-driven planning and implementation work in this repository. Plans, specs, tasks, and runtime guidance MUST align with it. When another document conflicts with this constitution, the conflicting document MUST be updated in the same change set or the conflict MUST be recorded in specs/001-ai-docs/research.md.

II. Module and Host Boundaries

Code MUST live in the directory that owns the behavior. Shared feature logic belongs under modules/; host-specific assembly belongs under hosts/<name>/; factory helpers belong under modules/factories/; repo-wide shared options belong under modules/modules.nix or the relevant shared module. New behavior MUST NOT be placed in an unrelated host or module file for convenience.

III. Host-Local Firewall Ownership

Any host that contains firewall rules MUST keep firewall-related logic in hosts/<name>/firewall.nix. Host configuration.nix files MAY import that file, but MUST NOT become the long-term home for firewall rule definitions, NAT rules, nftables tables, forward-port rules, or other firewall-specific logic. Firewall changes in specs, plans, and task lists MUST reference the host-local firewall.nix path explicitly.

IV. Nix Structure and Ordering

Nix code MUST preserve grouped parents when they have multiple children and MUST flatten only single-child chains. Siblings that share a parent MUST live under one parent block instead of being split across disconnected assignments. Within module bodies, options MUST appear before config. Within attribute sets, inherit statements MUST come first, then boolean leaves, then other leaf assignments, then nested attribute sets.

V. Secure Host and Secrets Discipline

Secret-dependent behavior MUST stay behind config.my.secureHost. Secrets MUST live in the appropriate secrets/*.yaml file by purpose, and hosts marked non-secure MUST avoid secret-dependent services and secret loading. Proxy-only or network-only changes MUST still respect secret ownership, secure-host gating, and host-local boundaries.

Repository Constraints

• Host definitions live in hosts/<name>/configuration.nix with optional imports such as hosts/<name>/firewall.nix and hosts/<name>/toggles.nix.
• Module categories remain apps, dev, scripts, servers, services, shell, websites, network, users, and nix, with feature directories preferred over new flat modules.
• Service ports intrinsic to a server module SHOULD live with that module; miscellaneous shared ports SHOULD live in my.ports.
• Firewall rules, NAT, nftables tables, and forward-port declarations for a host MUST be reviewed as one unit inside that host's firewall.nix.

Delivery Workflow

• Every plan MUST include a constitution check that validates module ownership, host ownership, secure-host impact, and whether firewall work belongs in hosts/<name>/firewall.nix.
• Every spec that changes networking or exposure MUST state which host owns the change and which firewall file is affected.
• Every task list that includes firewall work MUST name the concrete hosts/<name>/firewall.nix path.
• Runtime guidance docs that describe repository structure MUST be updated when host boundary rules change.

Governance

This constitution supersedes conflicting Speckit planning assumptions for this repository. Amendments MUST be made in the same change set as any dependent template or runtime guidance updates. Versioning follows semantic versioning: MAJOR for incompatible governance changes or principle removals, MINOR for new principles or materially expanded rules, PATCH for clarifications that do not change required behavior. Compliance review is mandatory for every plan, spec, and tasks artifact that claims alignment with this constitution.

Version: 1.0.0 | Ratified: 2026-04-01 | Last Amended: 2026-04-01