103 lines
4.9 KiB
Markdown
103 lines
4.9 KiB
Markdown
<!--
|
|
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
|