<!--
Sync Impact Report
- Version change: 1.0.0 -> 1.1.0
- Modified principles:
  - Template Principle 1 -> I. Constitution Authority
  - Template Principle 2 -> II. Module and Host Boundaries
  - III. Host-Local Firewall Ownership -> III. Host-Local Network Ownership
  - Template Principle 4 -> IV. Nix Structure and Ordering
  - Template Principle 5 -> V. Secure Host and Secrets Discipline
- Added sections:
  - None
- Removed sections:
  - None
- Templates requiring updates:
  - ✅ updated `.specify/templates/plan-template.md`
  - ✅ updated `.specify/templates/spec-template.md`
  - ✅ updated `.specify/templates/tasks-template.md`
  - ✅ updated `docs/constitution.md`
  - ✅ updated `docs/reference/index.md`
  - ✅ updated `specs/001-ai-docs/research.md`
  - ✅ no `.specify/templates/commands/*.md` files present
- Follow-up TODOs:
  - None
-->
# 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 Network Ownership
Any host that owns host-local networking behavior MUST keep that logic in
`hosts/<name>/network.nix`. Host `configuration.nix` files MAY import that
file, but MUST NOT become the long-term home for host-specific firewall rules,
NAT rules, nftables tables, forward-port rules, WireGuard interface
configuration, policy-routing services, or other host-local networking logic.
Networking changes in specs, plans, and task lists MUST reference the
host-local `network.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>/network.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`.
- Host-local firewall rules, NAT, nftables tables, WireGuard interfaces, and
  policy-routing services MUST be reviewed as one unit inside that host's
  `network.nix`.

## Delivery Workflow

- Every plan MUST include a constitution check that validates module ownership,
  host ownership, secure-host impact, and whether networking work belongs in
  `hosts/<name>/network.nix`.
- Every spec that changes networking or exposure MUST state which host owns the
  change and which host-local network file is affected.
- Every task list that includes networking work MUST name the concrete
  `hosts/<name>/network.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.1.0 | **Ratified**: 2026-04-01 | **Last Amended**: 2026-04-02