nimmo/nixos-config
nimmo/nixos-config
Watch
1
0
Fork
You've already forked nixos-config
 0
Code Issues 15 Pull requests Wiki Activity Actions

[Wiki 3/5] Establish governance, security policy, and architecture decisions #221

New issue
Closed
opened 2026-09-12 09:42:42 +01:00 by nimmo · 3 comments
nimmo commented 2026-09-12 09:42:42 +01:00
Owner
Copy link

Objective

Establish first-class governance, security policy, and Architecture Decision Records without turning decision pages into duplicated reference manuals or runbooks.

Prerequisites and durable context

  • Milestone: Wiki Knowledge Architecture Rebuild
  • Complete the foundation issue first. The System Atlas may proceed in parallel only where its terminology and links are already stable.
  • Project label: project:wiki-rebuild
  • The live repository and completed Forgejo issue evidence are authoritative. Engram memories are discovery aids and must be verified before use.

Documentation rule

Each subject may have several page types, but each page owns one question:

  • Reference: what exists now?
  • ADR: why was this choice made and what follows from it?
  • Runbook: how is it operated or recovered?
  • Policy: what is required or prohibited?
  • Tutorial: how does a learner understand it?

Cross-link those pages. Do not repeat the same explanation in each.

Scope and checklist

  • Rewrite Project and Change Governance around the current Forgejo issue/milestone lifecycle, risk-based change workflow, validation, canaries, deployment evidence, and wiki promotion boundary.
  • Rewrite Security Baseline as current policy and review gates; move historical rationale or implementation detail to ADR/reference pages.
  • Create an ADR index with status and supersession information.
  • ADR-001: Electra hardware-presence specialisations and the single-generation model.
  • ADR-002: workload placement criteria for native NixOS services, containers, and wrapper repositories.
  • ADR-003: network exposure, loopback bindings, mesh access, and relay/ingress topology.
  • ADR-004: Engram as durable cross-session agent memory and its boundary with canonical documentation.
  • ADR-005: auto-update as a fleet reliability/control-plane system rather than a simple timer.
  • ADR-006: service/host-scoped secret files instead of a monolithic encrypted file.
  • For each ADR, reconstruct rationale from repository history, closed issues, verified memories, and current implementation; clearly distinguish confirmed rationale from inference.
  • Mark transitional decisions and known exceptions instead of rewriting history to make the current state appear cleaner than it is.
  • Validate all links and run git -C ~/nixos-config.wiki diff --check.
  • Commit and push coherent governance/ADR groups; record commits and remaining work in issue comments.

Completion criteria

  • Governance says where work and knowledge live and how changes progress.
  • Security policy is actionable and does not masquerade as a one-time audit report.
  • Each ADR records a real consequential decision, its alternatives and consequences, and links to current reference/runbook material.
  • No ADR is merely a renamed implementation guide.

Resume and handoff protocol

At session start, read this issue and its latest comments, pull both repositories, and resume from the first unchecked page. Before drafting an ADR, collect and cite its verified evidence. At every stopping point, comment with source commit, wiki commit, ADRs/pages completed, evidence still missing, validation performed, and the exact next checklist item. Commit finished ADRs before stopping; leave incomplete research described in the issue rather than only in memory or chat.

# Objective Establish first-class governance, security policy, and Architecture Decision Records without turning decision pages into duplicated reference manuals or runbooks. ## Prerequisites and durable context - Milestone: `Wiki Knowledge Architecture Rebuild` - Complete the foundation issue first. The System Atlas may proceed in parallel only where its terminology and links are already stable. - Project label: `project:wiki-rebuild` - The live repository and completed Forgejo issue evidence are authoritative. Engram memories are discovery aids and must be verified before use. ## Documentation rule Each subject may have several page types, but each page owns one question: - Reference: what exists now? - ADR: why was this choice made and what follows from it? - Runbook: how is it operated or recovered? - Policy: what is required or prohibited? - Tutorial: how does a learner understand it? Cross-link those pages. Do not repeat the same explanation in each. ## Scope and checklist - [x] Rewrite Project and Change Governance around the current Forgejo issue/milestone lifecycle, risk-based change workflow, validation, canaries, deployment evidence, and wiki promotion boundary. - [x] Rewrite Security Baseline as current policy and review gates; move historical rationale or implementation detail to ADR/reference pages. - [x] Create an ADR index with status and supersession information. - [x] ADR-001: Electra hardware-presence specialisations and the single-generation model. - [x] ADR-002: workload placement criteria for native NixOS services, containers, and wrapper repositories. - [x] ADR-003: network exposure, loopback bindings, mesh access, and relay/ingress topology. - [x] ADR-004: Engram as durable cross-session agent memory and its boundary with canonical documentation. - [x] ADR-005: auto-update as a fleet reliability/control-plane system rather than a simple timer. - [x] ADR-006: service/host-scoped secret files instead of a monolithic encrypted file. - [x] For each ADR, reconstruct rationale from repository history, closed issues, verified memories, and current implementation; clearly distinguish confirmed rationale from inference. - [x] Mark transitional decisions and known exceptions instead of rewriting history to make the current state appear cleaner than it is. - [x] Validate all links and run `git -C ~/nixos-config.wiki diff --check`. - [x] Commit and push coherent governance/ADR groups; record commits and remaining work in issue comments. ## Completion criteria - Governance says where work and knowledge live and how changes progress. - Security policy is actionable and does not masquerade as a one-time audit report. - Each ADR records a real consequential decision, its alternatives and consequences, and links to current reference/runbook material. - No ADR is merely a renamed implementation guide. ## Resume and handoff protocol At session start, read this issue and its latest comments, pull both repositories, and resume from the first unchecked page. Before drafting an ADR, collect and cite its verified evidence. At every stopping point, comment with source commit, wiki commit, ADRs/pages completed, evidence still missing, validation performed, and the exact next checklist item. Commit finished ADRs before stopping; leave incomplete research described in the issue rather than only in memory or chat.
nimmo commented 2026-09-12 16:30:31 +01:00
Author
Owner
Copy link

Phase 3 started. Source baseline: 556df88494. Published wiki commit 3c993b8 (docs: establish project change governance), rewriting 23-Project-Tracking.md as the current Project and Change Governance policy and updating the governance index. Verified against AGENTS.md, README.md, and .forgejo/ai-review.md; git diff --check passed and all new internal link targets exist. Next checklist item: reconcile and rewrite 24-Security-Baseline.md as actionable current policy, using the System Atlas exposure and backup findings while separating implementation detail and ADR rationale.

Phase 3 started. Source baseline: 556df88494686003b1c4f20c8e0b99b5afc16a6e. Published wiki commit 3c993b8 (docs: establish project change governance), rewriting 23-Project-Tracking.md as the current Project and Change Governance policy and updating the governance index. Verified against AGENTS.md, README.md, and .forgejo/ai-review.md; git diff --check passed and all new internal link targets exist. Next checklist item: reconcile and rewrite 24-Security-Baseline.md as actionable current policy, using the System Atlas exposure and backup findings while separating implementation detail and ADR rationale.
nimmo commented 2026-09-12 16:36:34 +01:00
Author
Owner
Copy link

Phase 3 checkpoint. Published wiki commit d6251ec, rewriting 24-Security-Baseline.md as actionable policy with required controls, the host/service review gate, enforcement, and repository-derived current exceptions. Published wiki commit 0d0201b, creating the current ADR register and accepted ADR-001 for Electra single-generation hardware-presence specialisations; evidence came from current implementation and source commits 6f772ce, 8ce867f, and a5eaf18. Host Inventory now links to the decision. Validation: git diff --check passed and all internal wiki link targets resolve. Source baseline remains 556df88494. Next checklist item: collect implementation, history, and closed-issue evidence for ADR-002, workload placement among native NixOS services, containers, and wrapper repositories.

Phase 3 checkpoint. Published wiki commit d6251ec, rewriting 24-Security-Baseline.md as actionable policy with required controls, the host/service review gate, enforcement, and repository-derived current exceptions. Published wiki commit 0d0201b, creating the current ADR register and accepted ADR-001 for Electra single-generation hardware-presence specialisations; evidence came from current implementation and source commits 6f772ce, 8ce867f, and a5eaf18. Host Inventory now links to the decision. Validation: git diff --check passed and all internal wiki link targets resolve. Source baseline remains 556df88494686003b1c4f20c8e0b99b5afc16a6e. Next checklist item: collect implementation, history, and closed-issue evidence for ADR-002, workload placement among native NixOS services, containers, and wrapper repositories.
nimmo commented 2026-09-12 17:07:21 +01:00
Author
Owner
Copy link

Phase 3 complete.

Source baseline:

  • Relevant content verified against source commit 556df88494.
  • Current source HEAD is c4c18eb0df; the intervening change is flake.lock-only and does not alter the documented behaviour or policy.

Published wiki groups:

  • 3c993b8 — Project and Change Governance
  • d6251ec — Security Baseline
  • 0d0201b — ADR index and ADR-001
  • f4f7399 — ADR-002 workload placement
  • 6b1bdf4 — ADR-003 network exposure
  • 7304185 — ADR-004 Engram durable memory
  • 63463ce — ADR-005 auto-update control plane
  • 4137148 — ADR-006 scoped secret files
  • a9f2b96 — final cross-page review and current governance index

All six records distinguish current implementation from rationale, alternatives, and consequences. Inferred rationale is labelled where contemporary evidence was incomplete. Transitional implementation exceptions remain explicit in the policy/decision layer rather than being silently normalised.

Validation:

  • Full-wiki local Markdown link targets checked successfully.
  • git diff --check passed.
  • Register, status, supersession fields, and cross-page ownership reviewed.
  • Wiki worktree clean after publication.

No Phase 3 work remains. Next item: issue #222, starting with an inventory of legacy operational procedures and their allocation between current runbooks and the Engineering Handbook.

Phase 3 complete. Source baseline: - Relevant content verified against source commit 556df88494686003b1c4f20c8e0b99b5afc16a6e. - Current source HEAD is c4c18eb0df39d0418dfad2f916a934908c2fb4fb; the intervening change is flake.lock-only and does not alter the documented behaviour or policy. Published wiki groups: - 3c993b8 — Project and Change Governance - d6251ec — Security Baseline - 0d0201b — ADR index and ADR-001 - f4f7399 — ADR-002 workload placement - 6b1bdf4 — ADR-003 network exposure - 7304185 — ADR-004 Engram durable memory - 63463ce — ADR-005 auto-update control plane - 4137148 — ADR-006 scoped secret files - a9f2b96 — final cross-page review and current governance index All six records distinguish current implementation from rationale, alternatives, and consequences. Inferred rationale is labelled where contemporary evidence was incomplete. Transitional implementation exceptions remain explicit in the policy/decision layer rather than being silently normalised. Validation: - Full-wiki local Markdown link targets checked successfully. - git diff --check passed. - Register, status, supersession fields, and cross-page ownership reviewed. - Wiki worktree clean after publication. No Phase 3 work remains. Next item: issue #222, starting with an inventory of legacy operational procedures and their allocation between current runbooks and the Engineering Handbook.
nimmo closed this issue 2026-09-12 17:08:02 +01:00
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
feat/issue-236-electra-nova-vega
feat/issue-233-nova-builder-credentials
docs/wiki-final-cutover
fix/remediation-evaluation-evidence
fix/remediation-evidence-review
fix/chaos-synthseek-queue
pre-electra-disko-migration
Labels
Clear labels   
area:authentication
Issues related to authentication area

  
area:flake-utilities
Issues related to flake utilities area

  
area:performance
Issues related to performance area

  
area:tbd
Area to be determined

  
host:chaos
Issues specific to the chaos host.

  
host:electra
Issues specific to the electra host.

  
host:fleet
Issues that span multiple hosts or the fleet as a whole.

  
host:lyra
Issues specific to the lyra host.

  
host:nova
Issues specific to the nova host.

  
host:vega
Issues specific to the vega host.

  
investigation
Issue is an investigation task

  
phase:cutover
The service cutover execution phase.

  
phase:deploy

   
phase:mcp

   
phase:module

   
phase:packaging

   
phase:prep
Preparation and preflight work before service cutover.

  
phase:validation
Post-cutover validation and rollback-window work.

  
priority:high
High priority issue

  
priority:medium
Medium priority issue

  
project:attic-postgres-lyra-rollout
Issues in the Attic PostgreSQL migration and Lyra rollout workstream.

  
project:auto-update-reliability
Work arising from the automated update reliability review.

  
project:auto-update-remediation
Guarded Nova-assisted diagnosis and remediation of failed automated updates.

  
project:declarative-purity-cleanup
Issues in the declarative purity cleanup workstream.

  
project:external-review
Review of external configurations for ideas and improvements

  
project:fleet-boundary-cleanup
Maintainability work that clarifies fleet configuration and automation boundaries.

  
project:host-facts-refactor
Issues in the host facts refactor workstream.

  
project:lyra-nixos-deploy
Issues in the Lyra NixOS deployment workstream.

  
project:lyra-service-stack-migration
Issues in the lyra service stack migration workstream.

  
project:nebula-mesh-network
Issues in the Nebula mesh network workstream.

  
project:nixos-build-deployment-pipeline
Issues in the NixOS Build & Deployment Pipeline workstream.

  
project:security-hardening
Work belonging to the Security Hardening milestone

  
project:service-stack-migration
Issues in the service stack migration workstream.

  
project:vega-sillytavern-cutover
Issues in the Vega SillyTavern cutover workstream.

  
project:wiki-rebuild
Re-found the repository wiki as the fleet's curated knowledge architecture.

  
repo:numtide/flake-utils
Issues related to numtide/flake-utils repository

  
repo:numtide/nix-auth
Issues related to numtide/nix-auth repository

  
repo:numtide/nixos-passthru-cache
Issues related to numtide/nixos-passthru-cache repository

  
repo:numtide/nix-relay
Issues related to numtide/nix-relay repository

  
service:auto-update
NixOS flake update, cache build, and consumer deployment automation.

  
service:mem0

   
service:nix
Issues concerning Nix build, store, cache, or deployment infrastructure.

  
service:sillytavern
Issues related to the SillyTavern service.

  
service:slskd
Soulseek daemon (slskd) work.

  
service:synthseek
Synthseek music discovery/library manager work.

No labels
area:authentication
area:flake-utilities
area:performance
area:tbd
host:chaos
host:electra
host:fleet
host:lyra
host:nova
host:vega
investigation
phase:cutover
phase:deploy
phase:mcp
phase:module
phase:packaging
phase:prep
phase:validation
priority:high
priority:medium
project:attic-postgres-lyra-rollout
project:auto-update-reliability
project:auto-update-remediation
project:declarative-purity-cleanup
project:external-review
project:fleet-boundary-cleanup
project:host-facts-refactor
project:lyra-nixos-deploy
project:lyra-service-stack-migration
project:nebula-mesh-network
project:nixos-build-deployment-pipeline
project:security-hardening
project:service-stack-migration
project:vega-sillytavern-cutover
project:wiki-rebuild
repo:numtide/flake-utils
repo:numtide/nix-auth
repo:numtide/nixos-passthru-cache
repo:numtide/nix-relay
service:auto-update
service:mem0
service:nix
service:sillytavern
service:slskd
service:synthseek
Milestone
Clear milestone
No items
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
nimmo/nixos-config#221
No description provided.