feat: add FOS/credential standards, big-picture guidance, and CUST-WP-0025 workplan
- canon/standards/credential-management_v0.1.md: single root-of-trust credential hierarchy standard - canon/standards/federated-organization-standard_v1.0.md: FOS reference architecture (VSM-based) - wiki/BigPictureGuidance.md: integration guidance for OAS + FOS orthogonal layers - workplans/CUST-WP-0025-fos-hub-bootstrap.md: 4-phase plan (identity, hub-core extraction, ops-hub, fin-hub) - state-hub/Makefile: treat exit 2 (warnings-only) as success in check-consistency targets Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
300
canon/standards/credential-management_v0.1.md
Normal file
300
canon/standards/credential-management_v0.1.md
Normal file
@@ -0,0 +1,300 @@
|
||||
---
|
||||
title: "Credential Management Standard"
|
||||
version: "0.1"
|
||||
status: "Draft Standard"
|
||||
domain: custodian
|
||||
scope: all-domains
|
||||
created: "2026-03-20"
|
||||
---
|
||||
|
||||
# Credential Management Standard
|
||||
|
||||
**Version:** 0.1
|
||||
**Status:** Draft Standard
|
||||
**Scope:** All domains and repositories in the federated organization
|
||||
|
||||
---
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
This standard defines how credentials, secrets, and key material are
|
||||
managed across all systems — from a developer workstation with no
|
||||
infrastructure, to a fully operational Kubernetes cluster.
|
||||
|
||||
The core principle is a **single root of trust**: one operator keypair
|
||||
anchors all credential storage and encryption. Every secret can be
|
||||
traced back to that root. No secret lives outside this hierarchy.
|
||||
|
||||
---
|
||||
|
||||
## 2. Trust Hierarchy
|
||||
|
||||
```
|
||||
Operator passphrase (human memory only — never stored anywhere)
|
||||
│
|
||||
└── age keypair (~/.config/sops/age/key.txt — one per operator)
|
||||
│
|
||||
├── SOPS encryption (GitOps secrets in all repos)
|
||||
│ └── secrets/**/*.sops.yaml — encrypted at rest in git
|
||||
│
|
||||
├── Ops bundle (age-encrypted tar — offsite backup)
|
||||
│ └── ops-bundle-<date>.tar.age
|
||||
│ └── all service secrets at point-in-time
|
||||
│
|
||||
└── KeePassXC (pre-cluster primary credential store)
|
||||
│ └── master password = operator passphrase (or derived)
|
||||
│
|
||||
├── Infrastructure credentials
|
||||
│ ├── SSH keys (server access)
|
||||
│ ├── API tokens (Gitea, HostEurope, Hetzner)
|
||||
│ └── Cloud credentials
|
||||
│
|
||||
├── Service secrets (per-domain groups)
|
||||
│ ├── net-kingdom/privacyidea/
|
||||
│ ├── net-kingdom/lldap/
|
||||
│ ├── net-kingdom/authelia/
|
||||
│ ├── net-kingdom/keycape/
|
||||
│ └── railiance/postgres/
|
||||
│
|
||||
└── Vault root token (in-cluster phase, stored here)
|
||||
└── HashiCorp Vault
|
||||
└── External Secrets Operator (ESO)
|
||||
└── K8s Secrets → pods
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Phases
|
||||
|
||||
### Phase 0 — Pre-cluster (bootstrap)
|
||||
|
||||
**Used when:** No Kubernetes cluster is available. Local development,
|
||||
initial server provisioning, CI bootstrap.
|
||||
|
||||
**Tools:** age keypair + KeePassXC + ops bundle
|
||||
|
||||
**Flow:**
|
||||
1. Generate service secrets with a `gen-secrets.sh` script
|
||||
2. Copy each secret manually into KeePassXC (under the appropriate group)
|
||||
3. Encrypt a point-in-time ops bundle: `pack-bundle.sh <secrets-dir> <age-pub-key>`
|
||||
4. Store the ops bundle offsite (separate physical location from KeePassXC)
|
||||
5. Shred the plaintext secrets directory: `find secrets/ -type f -exec shred -u {} \;`
|
||||
6. When deploying to k8s, read each secret from KeePassXC and inject via
|
||||
`create-secrets.sh` scripts that produce K8s Secrets
|
||||
|
||||
**Invariant:** Plaintext secrets MUST NOT persist on disk after being
|
||||
stored in KeePassXC. The only durable forms are: KeePassXC + ops bundle.
|
||||
|
||||
---
|
||||
|
||||
### Phase 1 — GitOps secrets (SOPS)
|
||||
|
||||
**Used when:** Secrets need to live alongside infrastructure code in git.
|
||||
All repos with infrastructure manifests use this pattern.
|
||||
|
||||
**Tools:** SOPS + age
|
||||
|
||||
**Configuration (`.sops.yaml` in repo root):**
|
||||
```yaml
|
||||
creation_rules:
|
||||
- path_regex: secrets/.*$
|
||||
age: >-
|
||||
<operator-age-public-key>
|
||||
- path_regex: .*\.sops\.yaml$
|
||||
age: >-
|
||||
<operator-age-public-key>
|
||||
```
|
||||
|
||||
**Multi-operator:** When a second operator joins, add their age public key
|
||||
as an additional recipient and re-encrypt all secrets with `sops updatekeys`.
|
||||
Both keys can decrypt independently — no single point of failure.
|
||||
|
||||
**Invariant:** The age private key is NEVER committed to git. The public
|
||||
key is committed (in `.sops.yaml` and `keys/age.pub`). Encrypted values
|
||||
in git are safe to store and review.
|
||||
|
||||
---
|
||||
|
||||
### Phase 2 — In-cluster (HashiCorp Vault)
|
||||
|
||||
**Used when:** Kubernetes cluster is operational and stable.
|
||||
|
||||
**Tools:** HashiCorp Vault + External Secrets Operator (ESO)
|
||||
|
||||
**Why ESO over Vault Agent Injector:** ESO produces standard K8s Secrets,
|
||||
which are compatible with plain Helm charts and do not require pod
|
||||
annotation changes. Decision D4 (net-kingdom DECISIONS.md).
|
||||
|
||||
**Flow:**
|
||||
1. Bootstrap Vault with the root token stored in KeePassXC
|
||||
2. Enable Kubernetes auth method (`vault auth enable kubernetes`)
|
||||
3. Create per-service policies with least-privilege access
|
||||
4. Migrate each service secret from KeePassXC into Vault
|
||||
5. Deploy ESO `SecretStore` pointing to Vault
|
||||
6. Replace `create-secrets.sh` calls with `ExternalSecret` manifests
|
||||
7. Vault reconciles secrets into K8s Secrets automatically
|
||||
|
||||
**KeePassXC post-cluster:** Remains the source of truth for:
|
||||
- The Vault root/unseal keys (emergency only)
|
||||
- Dev/sandbox systems that do not connect to in-cluster Vault
|
||||
- New secrets before they are migrated into Vault
|
||||
|
||||
---
|
||||
|
||||
## 4. KeePassXC Group Structure
|
||||
|
||||
All service secrets are organized under a standardized group hierarchy:
|
||||
|
||||
```
|
||||
KeePassXC root
|
||||
├── Infrastructure
|
||||
│ ├── SSH Keys
|
||||
│ │ └── <hostname> (private key as attachment, public key as note)
|
||||
│ ├── API Tokens
|
||||
│ │ ├── gitea-admin
|
||||
│ │ ├── hosteurope-api
|
||||
│ │ └── hetzner-api
|
||||
│ └── Cloud Credentials
|
||||
│ └── <provider>
|
||||
│
|
||||
├── net-kingdom
|
||||
│ ├── privacyidea
|
||||
│ │ ├── PI_SECRET_KEY
|
||||
│ │ ├── PI_PEPPER
|
||||
│ │ ├── PI_DB_PASSWORD
|
||||
│ │ ├── pi-admin (password + totp-seed)
|
||||
│ │ ├── trigger-admin (password + API token)
|
||||
│ │ └── enckey (attachment: enckey file + audit keypair)
|
||||
│ ├── lldap
|
||||
│ │ ├── LLDAP_JWT_SECRET
|
||||
│ │ └── LLDAP_LDAP_USER_PASS
|
||||
│ ├── authelia
|
||||
│ │ ├── AUTHELIA_JWT_SECRET
|
||||
│ │ ├── AUTHELIA_SESSION_SECRET
|
||||
│ │ ├── AUTHELIA_STORAGE_ENCRYPTION_KEY
|
||||
│ │ ├── AUTHELIA_OIDC_HMAC_SECRET
|
||||
│ │ └── AUTHELIA_KEYCAPE_CLIENT_SECRET
|
||||
│ └── keycape
|
||||
│ ├── RSA signing key (attachment: private + public PEM)
|
||||
│ └── PI_ADMIN_TOKEN
|
||||
│
|
||||
├── railiance
|
||||
│ ├── postgres
|
||||
│ │ └── PG_ROOT_PASSWORD
|
||||
│ └── sops-age
|
||||
│ └── age private key (attachment: key.txt)
|
||||
│
|
||||
└── vault
|
||||
├── root-token
|
||||
└── unseal-keys (attachment: unseal-keys.txt, gpg-encrypted)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Age Keypair Management
|
||||
|
||||
**One keypair per operator.** The same key is used for:
|
||||
- SOPS encryption across all repos
|
||||
- Ops bundle encryption
|
||||
|
||||
**Generate:**
|
||||
```bash
|
||||
age-keygen -o ~/.config/sops/age/key.txt
|
||||
# output: Public key: age1...
|
||||
```
|
||||
|
||||
**Add to repos:** Copy the public key into `.sops.yaml` of each repo and
|
||||
into `keys/age.pub`. Commit both.
|
||||
|
||||
**Back up:** The private key file MUST be stored in KeePassXC as an
|
||||
attachment under `railiance/sops-age/age private key`. The KeePassXC
|
||||
database is the disaster recovery path for the age private key.
|
||||
|
||||
**Rotation:** If the private key is compromised, generate a new keypair,
|
||||
add the new public key to all repos, re-encrypt all secrets with
|
||||
`sops updatekeys`, then revoke the old key from all `.sops.yaml` files.
|
||||
|
||||
---
|
||||
|
||||
## 6. Ops Bundle
|
||||
|
||||
The ops bundle is a point-in-time snapshot of all service secrets,
|
||||
encrypted with age and stored offsite.
|
||||
|
||||
**Create:**
|
||||
```bash
|
||||
bash gen-secrets.sh ./secrets # generates all secrets as env files
|
||||
# ... enter each into KeePassXC ...
|
||||
bash pack-bundle.sh ./secrets <age-pub-key> # → ops-bundle-<date>.tar.age
|
||||
find secrets/ -type f -exec shred -u {} \; # shred plaintext
|
||||
```
|
||||
|
||||
**Restore:**
|
||||
```bash
|
||||
age -d -i ~/.config/sops/age/key.txt -o secrets.tar ops-bundle-<date>.tar.age
|
||||
tar xf secrets.tar
|
||||
# re-run create-secrets.sh scripts from restored env files
|
||||
```
|
||||
|
||||
**Frequency:** Create a new ops bundle:
|
||||
- Before any major cluster operation (migration, upgrade, rekey)
|
||||
- After adding or rotating any service secret
|
||||
- At least once per quarter
|
||||
|
||||
---
|
||||
|
||||
## 7. Prohibited Patterns
|
||||
|
||||
These are hard violations regardless of context:
|
||||
|
||||
| Pattern | Why prohibited |
|
||||
|---------|----------------|
|
||||
| Plaintext secrets committed to git | Unrecoverable leak |
|
||||
| Secrets in environment variables in shell history | ~/.bash_history exposure |
|
||||
| Sharing secrets via chat, email, or issue trackers | Uncontrolled propagation |
|
||||
| Using the same password for multiple services | Single-point compromise |
|
||||
| Storing age private key only on a single machine | Catastrophic loss on disk failure |
|
||||
| Hardcoded secrets in application code or Helm values | Accidental publishing |
|
||||
|
||||
---
|
||||
|
||||
## 8. Multi-operator Extension
|
||||
|
||||
When a second operator needs access:
|
||||
|
||||
1. They generate their own age keypair (`age-keygen`)
|
||||
2. Share only the **public key** (never the private key)
|
||||
3. Primary operator adds it to `.sops.yaml` in all repos
|
||||
4. Primary operator runs `sops updatekeys <file>` on all encrypted files
|
||||
5. Both operators can now encrypt and decrypt independently
|
||||
6. Share KeePassXC database via an encrypted channel (never plaintext)
|
||||
— the other operator opens it with their own master password after import
|
||||
|
||||
---
|
||||
|
||||
## 9. Vault Migration Checklist
|
||||
|
||||
When the cluster is stable enough to operate Vault:
|
||||
|
||||
- [ ] Deploy Vault via Helm with HA mode (3 replicas minimum)
|
||||
- [ ] Store root token and unseal keys in KeePassXC (vault/ group)
|
||||
- [ ] Enable Kubernetes auth method
|
||||
- [ ] Create per-service Vault policies (least privilege)
|
||||
- [ ] Deploy ESO `ClusterSecretStore` pointing to Vault
|
||||
- [ ] For each service: create `ExternalSecret` manifest, verify K8s Secret
|
||||
reconciles correctly, then delete the manually-created K8s Secret
|
||||
- [ ] Verify ESO auto-rotation works (reduce TTL to 1h, confirm rotation)
|
||||
- [ ] Remove `create-secrets.sh` scripts from deployment runbooks
|
||||
- [ ] Update this standard to Phase 2 operational status
|
||||
|
||||
---
|
||||
|
||||
## 10. Summary
|
||||
|
||||
| Situation | Tool | Source of truth |
|
||||
|-----------|------|----------------|
|
||||
| No cluster, local dev | KeePassXC + create-secrets.sh | KeePassXC |
|
||||
| GitOps secrets in repo | SOPS + age | Git (ciphertext) |
|
||||
| Cluster operational | Vault + ESO | Vault (KeePassXC holds root) |
|
||||
| Disaster recovery | Ops bundle (age) | Offsite encrypted archive |
|
||||
| Multi-operator | SOPS multi-recipient | Each operator's age keypair |
|
||||
977
canon/standards/federated-organization-standard_v1.0.md
Normal file
977
canon/standards/federated-organization-standard_v1.0.md
Normal file
@@ -0,0 +1,977 @@
|
||||
FederatedOrganizationStandard
|
||||
|
||||
*Building blocks for scalable organizations*
|
||||
|
||||
# FederatedOrganisationStandard (FOS)
|
||||
|
||||
*A reference architecture standard for viable, scalable organizations composed of autonomous domains, coordinated through hubs and governed through explicit recursion*
|
||||
|
||||
**Version:** 1.0
|
||||
**Status:** Draft Reference Standard
|
||||
|
||||
---
|
||||
|
||||
# 1. Purpose
|
||||
|
||||
The **FederatedOrganisationStandard (FOS)** defines an organizational architecture for building and operating a scalable entity — or a collection of entities — through a **federated system of domains and hubs**.
|
||||
|
||||
It is intended for organizations that:
|
||||
|
||||
* combine humans and artificial agents
|
||||
* operate across multiple management domains
|
||||
* require strong separation of concerns
|
||||
* want sovereignty, auditability, and rebuildability
|
||||
* need to scale recursively from projects to companies to foundation-like umbrella structures
|
||||
|
||||
The standard introduces the concept of a **federated organization**:
|
||||
|
||||
> A viable organization composed of semi-autonomous operational domains, each coordinated through a domain hub, and aligned through shared policy, escalation, and identity structures.
|
||||
|
||||
The standard provides:
|
||||
|
||||
* a conceptual model
|
||||
* a VSM framing
|
||||
* a core hub set for scalable organizations
|
||||
* separation-of-concerns rules
|
||||
* a cross-hub coupling model
|
||||
* a recursion model for long-term organizational growth
|
||||
|
||||
---
|
||||
|
||||
# 2. Core Concept
|
||||
|
||||
## 2.1 Federated Organization
|
||||
|
||||
A **federated organization** is an organization in which:
|
||||
|
||||
* operational variety is handled locally where possible
|
||||
* coordination is provided through explicit hubs
|
||||
* authority is bounded and visible
|
||||
* domain-specific systems remain autonomous
|
||||
* global coherence is achieved through policy, escalation, and shared protocols rather than through monolithic control
|
||||
|
||||
This is not a flat platform, and it is not a centralized command stack.
|
||||
|
||||
It is an architecture in which:
|
||||
|
||||
* domains remain responsible for their own reality
|
||||
* hubs reduce coordination cost
|
||||
* higher-order governance constrains without micromanaging
|
||||
* the same pattern can recur across multiple levels of organizational scale
|
||||
|
||||
---
|
||||
|
||||
## 2.2 Hub
|
||||
|
||||
A **hub** is:
|
||||
|
||||
> A domain-specific coordination and orientation layer that makes the state, tensions, requests, and responsibilities of a domain visible and actionable without collapsing that domain into centralized authority.
|
||||
|
||||
A hub is not primarily a source of truth.
|
||||
A hub is primarily a **derived coordination surface**.
|
||||
|
||||
---
|
||||
|
||||
## 2.3 Federation
|
||||
|
||||
Within this standard, **federation** means:
|
||||
|
||||
* multiple domains
|
||||
* multiple hubs
|
||||
* explicit boundaries
|
||||
* structured coupling
|
||||
* recursive viability
|
||||
|
||||
Federation does not imply weak structure.
|
||||
It implies **bounded autonomy plus disciplined coordination**.
|
||||
|
||||
---
|
||||
|
||||
# 3. Why This Standard Exists
|
||||
|
||||
Organizations that grow across technical, operational, financial, legal, and strategic concerns tend to fail in one of two ways:
|
||||
|
||||
## 3.1 Centralized Mud
|
||||
|
||||
Everything is routed through one giant management layer, one dashboard, one database, one leadership abstraction, or one agent layer.
|
||||
|
||||
This creates:
|
||||
|
||||
* overloaded coordination channels
|
||||
* mixed time horizons
|
||||
* authority confusion
|
||||
* brittle central systems
|
||||
* low adaptability
|
||||
|
||||
---
|
||||
|
||||
## 3.2 Fragmented Drift
|
||||
|
||||
Each domain builds its own world without shared coupling structures.
|
||||
|
||||
This creates:
|
||||
|
||||
* invisible tensions
|
||||
* misaligned incentives
|
||||
* cross-domain blockers
|
||||
* duplicated capabilities
|
||||
* late escalation of risk
|
||||
|
||||
---
|
||||
|
||||
## 3.3 FOS Response
|
||||
|
||||
FOS exists to establish a middle path:
|
||||
|
||||
* autonomy where possible
|
||||
* coordination where necessary
|
||||
* escalation where required
|
||||
* identity where non-negotiable
|
||||
|
||||
---
|
||||
|
||||
# 4. VSM Framing
|
||||
|
||||
The **FederatedOrganisationStandard** is explicitly informed by the logic of the **Viable System Model (VSM)**.
|
||||
|
||||
It assumes that a viable organization requires distinct but connected functions for:
|
||||
|
||||
* operations
|
||||
* coordination
|
||||
* internal control
|
||||
* audit / direct inspection
|
||||
* intelligence / adaptation
|
||||
* identity / policy
|
||||
|
||||
FOS uses VSM not as a rigid org chart, but as an architectural framing for keeping complexity manageable.
|
||||
|
||||
---
|
||||
|
||||
## 4.1 VSM Systems in FOS
|
||||
|
||||
### System 1 — Operations
|
||||
|
||||
These are the units that actually do work.
|
||||
|
||||
Examples:
|
||||
|
||||
* software development domains
|
||||
* infrastructure operations
|
||||
* finance administration
|
||||
* legal/governance operations
|
||||
* customer-facing service domains
|
||||
* product teams
|
||||
* business units
|
||||
|
||||
System 1 units should absorb as much variety locally as they can.
|
||||
|
||||
---
|
||||
|
||||
### System 2 — Coordination
|
||||
|
||||
This is the layer that reduces oscillation and friction across operational units.
|
||||
|
||||
In FOS, hubs provide much of this coordination through:
|
||||
|
||||
* shared summaries
|
||||
* request routing
|
||||
* dependency visibility
|
||||
* inboxes and message flows
|
||||
* standard rituals for orientation and handoff
|
||||
|
||||
---
|
||||
|
||||
### System 3 — Internal Control
|
||||
|
||||
This is the layer concerned with:
|
||||
|
||||
* current performance
|
||||
* resource use
|
||||
* compliance with internal expectations
|
||||
* operational coherence
|
||||
|
||||
In FOS, each domain hub typically includes System 3 functions relevant to its domain.
|
||||
|
||||
---
|
||||
|
||||
### System 3* — Audit / Direct Inspection
|
||||
|
||||
This is the probing, checking, validating function that bypasses polished reporting when necessary.
|
||||
|
||||
Examples in FOS:
|
||||
|
||||
* consistency checks
|
||||
* force refresh
|
||||
* direct probes
|
||||
* posture validation
|
||||
* raw-state inspection
|
||||
* anomaly review
|
||||
|
||||
---
|
||||
|
||||
### System 4 — Intelligence / Adaptation
|
||||
|
||||
This is the outward- and forward-facing function.
|
||||
|
||||
It handles:
|
||||
|
||||
* future architecture
|
||||
* emerging risks
|
||||
* adaptation
|
||||
* opportunity sensing
|
||||
* long-term redesign
|
||||
* environmental shifts
|
||||
|
||||
System 4 may be partially implemented within hubs, but should not be collapsed into day-to-day control.
|
||||
|
||||
---
|
||||
|
||||
### System 5 — Identity / Policy
|
||||
|
||||
This is the function that answers:
|
||||
|
||||
* who are we
|
||||
* what must remain true
|
||||
* what are our non-delegable boundaries
|
||||
* what may never be optimized away
|
||||
|
||||
In FOS, this role is anchored through a **Canon Hub** or equivalent constitutional layer.
|
||||
|
||||
---
|
||||
|
||||
# 5. Design Principles
|
||||
|
||||
## 5.1 Explicit Separation of Concerns
|
||||
|
||||
Each hub MUST be domain-specific.
|
||||
|
||||
A hub MUST NOT simultaneously serve as:
|
||||
|
||||
* development hub
|
||||
* operations hub
|
||||
* finance hub
|
||||
* security hub
|
||||
* constitutional governance hub
|
||||
|
||||
Blending these domains leads to mixed incentives and architectural confusion.
|
||||
|
||||
---
|
||||
|
||||
## 5.2 Derived-State Preference
|
||||
|
||||
A hub SHOULD be a derived coordination system wherever possible.
|
||||
|
||||
That means:
|
||||
|
||||
* source artefacts remain authoritative elsewhere
|
||||
* hub data is computed, indexed, summarized, routed, or logged
|
||||
* deleting and rebuilding the hub should not destroy organizational truth
|
||||
|
||||
---
|
||||
|
||||
## 5.3 Bounded Authority
|
||||
|
||||
Every hub MUST define:
|
||||
|
||||
* what it can observe
|
||||
* what it can derive
|
||||
* what it can recommend
|
||||
* what it can route
|
||||
* what it can decide
|
||||
* what it must escalate
|
||||
|
||||
---
|
||||
|
||||
## 5.4 Recursive Viability
|
||||
|
||||
The same organizational pattern should work at multiple levels:
|
||||
|
||||
* repo or subsystem
|
||||
* domain
|
||||
* operating entity
|
||||
* umbrella entity
|
||||
* foundation structure
|
||||
|
||||
Each level should be viable in its own right.
|
||||
|
||||
---
|
||||
|
||||
## 5.5 Informational Coupling Without Structural Fusion
|
||||
|
||||
Domains should exchange information through explicit protocols, not by collapsing into one giant shared state model.
|
||||
|
||||
This is the core of federation.
|
||||
|
||||
---
|
||||
|
||||
## 5.6 Sovereignty by Default
|
||||
|
||||
The organization should retain operational control over its own coordination systems.
|
||||
|
||||
FOS therefore favors:
|
||||
|
||||
* local-first systems
|
||||
* open interfaces
|
||||
* inspectable stores
|
||||
* append-only histories
|
||||
* explicit exports
|
||||
|
||||
---
|
||||
|
||||
# 6. Core Organizational Primitive: The Hub
|
||||
|
||||
## 6.1 Definition
|
||||
|
||||
A hub is:
|
||||
|
||||
> A domain-specific, bounded coordination layer that exposes the present state, requests, tensions, and responsibilities of a domain in a way that humans and agents can act upon.
|
||||
|
||||
---
|
||||
|
||||
## 6.2 Minimal Hub Responsibilities
|
||||
|
||||
Every hub MUST provide:
|
||||
|
||||
* orientation
|
||||
* coordination
|
||||
* escalation
|
||||
* event traceability
|
||||
* bounded interfaces
|
||||
* domain summaries
|
||||
|
||||
---
|
||||
|
||||
## 6.3 Minimal Hub Constraints
|
||||
|
||||
Every hub MUST avoid:
|
||||
|
||||
* becoming the sole source of truth without justification
|
||||
* hidden authority
|
||||
* invisible side effects
|
||||
* silent irreversible automation
|
||||
* uncontrolled cross-domain sprawl
|
||||
|
||||
---
|
||||
|
||||
# 7. Core Hub Set for a Scalable Organization
|
||||
|
||||
FOS defines a **core set of hubs** that together support a scalable organization.
|
||||
|
||||
Not every organization must implement all of them immediately, but the standard treats them as the canonical target set.
|
||||
|
||||
---
|
||||
|
||||
## 7.1 Canon Hub
|
||||
|
||||
**Role:** Identity, policy, constitutional boundaries
|
||||
**Dominant VSM Role:** System 5
|
||||
|
||||
### Purpose
|
||||
|
||||
The Canon Hub defines the stable normative frame of the organization.
|
||||
|
||||
It answers:
|
||||
|
||||
* what the organization is for
|
||||
* which roles and mandates exist
|
||||
* what agents may not do autonomously
|
||||
* how authority is delegated
|
||||
* what hard boundaries constrain all lower domains
|
||||
|
||||
### Typical Sources
|
||||
|
||||
* constitution
|
||||
* policy documents
|
||||
* foundational ADRs
|
||||
* role charters
|
||||
* mandate definitions
|
||||
* delegation matrices
|
||||
|
||||
### Typical Derived Views
|
||||
|
||||
* policy map
|
||||
* authority map
|
||||
* escalation destinations
|
||||
* unresolved governance questions
|
||||
* conflicts between policies or mandates
|
||||
|
||||
### Separation Rule
|
||||
|
||||
The Canon Hub MUST remain sparse, stable, and deliberately slower-moving than operational hubs.
|
||||
|
||||
---
|
||||
|
||||
## 7.2 Dev Hub
|
||||
|
||||
**Role:** Software production coordination
|
||||
**Dominant VSM Roles:** System 2, 3, 3*
|
||||
|
||||
### Purpose
|
||||
|
||||
The Dev Hub coordinates software design and implementation work across repositories, workstreams, and coding agents.
|
||||
|
||||
It answers:
|
||||
|
||||
* what are we building
|
||||
* what is blocked
|
||||
* what changed
|
||||
* what capabilities exist
|
||||
* what should happen next in development
|
||||
|
||||
### Typical Sources
|
||||
|
||||
* repositories
|
||||
* workplans
|
||||
* scope files
|
||||
* ADRs
|
||||
* dependency manifests
|
||||
* capability declarations
|
||||
|
||||
### Typical Derived Views
|
||||
|
||||
* workstream summaries
|
||||
* blocker maps
|
||||
* dependency graphs
|
||||
* capability catalogs
|
||||
* decision boards
|
||||
* development health indicators
|
||||
|
||||
### Separation Rule
|
||||
|
||||
The Dev Hub MUST NOT become a runtime operations dashboard or security control plane.
|
||||
|
||||
---
|
||||
|
||||
## 7.3 Ops Hub
|
||||
|
||||
**Role:** Runtime operations coordination
|
||||
**Dominant VSM Roles:** System 2, 3, 3*
|
||||
|
||||
### Purpose
|
||||
|
||||
The Ops Hub coordinates the running system.
|
||||
|
||||
It answers:
|
||||
|
||||
* what is running
|
||||
* what is degraded
|
||||
* what needs intervention now
|
||||
* which access paths exist
|
||||
* where operational risk is accumulating
|
||||
|
||||
### Typical Sources
|
||||
|
||||
* monitoring systems
|
||||
* runtime topology
|
||||
* host or cluster state
|
||||
* alerts
|
||||
* operational runbooks
|
||||
* change records
|
||||
* backup and certificate metadata
|
||||
* access bridge definitions
|
||||
|
||||
### Typical Derived Views
|
||||
|
||||
* now view
|
||||
* incident board
|
||||
* resilience posture
|
||||
* access map
|
||||
* operational debt view
|
||||
* capacity risk view
|
||||
|
||||
### Separation Rule
|
||||
|
||||
The Ops Hub MUST NOT become the owner of infrastructure intent; desired state belongs in infra repositories or equivalent canonical systems.
|
||||
|
||||
---
|
||||
|
||||
## 7.4 Sec Hub
|
||||
|
||||
**Role:** Trust, control, and security posture
|
||||
**Dominant VSM Roles:** System 3, 3*, and strong coupling to System 5
|
||||
|
||||
### Purpose
|
||||
|
||||
The Sec Hub governs the trust structure of the organization.
|
||||
|
||||
It answers:
|
||||
|
||||
* what is trusted
|
||||
* what is exposed
|
||||
* which controls are present or missing
|
||||
* where exceptions are aging
|
||||
* where access or identity posture is drifting
|
||||
|
||||
### Typical Sources
|
||||
|
||||
* IAM systems
|
||||
* audit logs
|
||||
* policy baselines
|
||||
* vulnerability data
|
||||
* exception registers
|
||||
* certificate and secret metadata
|
||||
* control definitions
|
||||
|
||||
### Typical Derived Views
|
||||
|
||||
* control coverage
|
||||
* exposure map
|
||||
* exception aging
|
||||
* privileged-path map
|
||||
* trust posture summary
|
||||
|
||||
### Separation Rule
|
||||
|
||||
The Sec Hub MUST remain distinct from the Ops Hub even when tightly coupled to it.
|
||||
|
||||
Ops may observe and execute; Sec governs and constrains.
|
||||
|
||||
---
|
||||
|
||||
## 7.5 Fin Hub
|
||||
|
||||
**Role:** Resource viability and allocation
|
||||
**Dominant VSM Roles:** System 3 and 4
|
||||
|
||||
### Purpose
|
||||
|
||||
The Fin Hub governs resource viability.
|
||||
|
||||
It answers:
|
||||
|
||||
* what can we afford
|
||||
* what is committed
|
||||
* where burn is rising
|
||||
* what resource tensions exist across domains
|
||||
* which initiatives threaten long-term viability
|
||||
|
||||
### Typical Sources
|
||||
|
||||
* budget artifacts
|
||||
* accounting exports
|
||||
* cloud cost data
|
||||
* resource allocation plans
|
||||
* obligations and commitments
|
||||
* investment or reserve tracking
|
||||
|
||||
### Typical Derived Views
|
||||
|
||||
* runway view
|
||||
* burn by domain
|
||||
* committed vs flexible spend
|
||||
* allocation conflicts
|
||||
* capital tension alerts
|
||||
|
||||
### Separation Rule
|
||||
|
||||
The Fin Hub MUST NOT be replaced by ad hoc development or operations heuristics when the organization reaches meaningful scale.
|
||||
|
||||
---
|
||||
|
||||
## 7.6 Optional Domain Hubs
|
||||
|
||||
As the organization grows, additional hubs may appear, such as:
|
||||
|
||||
* Legal Hub
|
||||
* People Hub
|
||||
* Portfolio Hub
|
||||
* Research Hub
|
||||
* Partnership Hub
|
||||
* Venture Hub
|
||||
|
||||
These should only be introduced when the domain is stable and distinct enough to justify its own coordination surface.
|
||||
|
||||
---
|
||||
|
||||
# 8. Separation of Concerns
|
||||
|
||||
## 8.1 Why Separation Matters
|
||||
|
||||
Different domains have:
|
||||
|
||||
* different time horizons
|
||||
* different failure modes
|
||||
* different kinds of authority
|
||||
* different acceptable risk profiles
|
||||
* different source artefacts
|
||||
|
||||
When these are mixed, the organization loses clarity.
|
||||
|
||||
---
|
||||
|
||||
## 8.2 Time-Horizon Separation
|
||||
|
||||
A useful default reading is:
|
||||
|
||||
* Canon Hub: years
|
||||
* Fin Hub: quarters to years
|
||||
* Dev Hub: days to months
|
||||
* Ops Hub: seconds to weeks
|
||||
* Sec Hub: minutes to quarters, depending on the issue
|
||||
|
||||
A hub that mixes radically different horizons will tend toward overload.
|
||||
|
||||
---
|
||||
|
||||
## 8.3 Responsibility Separation
|
||||
|
||||
A practical shorthand:
|
||||
|
||||
* **Canon Hub** asks: what must remain true?
|
||||
* **Dev Hub** asks: what should be built?
|
||||
* **Ops Hub** asks: what must be kept running?
|
||||
* **Sec Hub** asks: what must be trusted or contained?
|
||||
* **Fin Hub** asks: what remains viable?
|
||||
|
||||
---
|
||||
|
||||
## 8.4 Source-of-Truth Separation
|
||||
|
||||
Canonical artefacts should live where they belong:
|
||||
|
||||
* code and workplans in repos
|
||||
* runtime intent in infra repos or control-plane definitions
|
||||
* trust policy in security/policy artefacts
|
||||
* financial truth in accounting or finance systems
|
||||
* constitutional truth in governance canon
|
||||
|
||||
Hubs summarize, route, and coordinate across these.
|
||||
|
||||
---
|
||||
|
||||
# 9. Cross-Hub Coupling Model
|
||||
|
||||
## 9.1 Principle
|
||||
|
||||
Hubs should be **loosely coupled but informationally rich**.
|
||||
|
||||
This means:
|
||||
|
||||
* each hub remains structurally separate
|
||||
* hubs exchange messages, requests, summaries, risks, and escalations
|
||||
* hubs do not require one giant shared mutable database to cooperate
|
||||
|
||||
---
|
||||
|
||||
## 9.2 Coupling Modes
|
||||
|
||||
FOS recognizes five primary coupling modes.
|
||||
|
||||
### 9.2.1 Summary Coupling
|
||||
|
||||
One hub provides a compact domain summary to another or to a higher recursion level.
|
||||
|
||||
Example:
|
||||
|
||||
* Ops Hub reports system readiness to Canon or entity-level governance
|
||||
* Fin Hub reports budget pressure to leadership
|
||||
|
||||
---
|
||||
|
||||
### 9.2.2 Request Coupling
|
||||
|
||||
One hub requests capability, support, or action from another.
|
||||
|
||||
Example:
|
||||
|
||||
* Dev Hub requests infrastructure provisioning from Ops Hub
|
||||
* Ops Hub requests a code fix from Dev Hub
|
||||
* Sec Hub requests remediation from Ops Hub or Dev Hub
|
||||
|
||||
---
|
||||
|
||||
### 9.2.3 Risk Coupling
|
||||
|
||||
One hub surfaces a risk that another hub must absorb or act on.
|
||||
|
||||
Example:
|
||||
|
||||
* Sec Hub surfaces identity drift to Ops Hub
|
||||
* Fin Hub surfaces budget pressure to Dev Hub
|
||||
* Ops Hub surfaces resilience risk to Canon or entity management
|
||||
|
||||
---
|
||||
|
||||
### 9.2.4 Escalation Coupling
|
||||
|
||||
A domain issue exceeds local authority or capacity and is explicitly escalated.
|
||||
|
||||
Example:
|
||||
|
||||
* Sec Hub escalates a policy breach to Canon Hub
|
||||
* Ops Hub escalates a risk involving major spend to Fin Hub
|
||||
* Dev Hub escalates unresolved architectural conflict to System 4 functions
|
||||
|
||||
---
|
||||
|
||||
### 9.2.5 Event Coupling
|
||||
|
||||
Hubs share relevant append-only events to preserve cross-domain traceability.
|
||||
|
||||
Example:
|
||||
|
||||
* a deployment event in Dev becomes a change signal in Ops
|
||||
* an access exception in Sec becomes an operational constraint in Ops
|
||||
|
||||
---
|
||||
|
||||
## 9.3 Coupling Rules
|
||||
|
||||
Cross-hub coupling MUST obey the following rules:
|
||||
|
||||
### Rule 1: No hidden dependencies
|
||||
|
||||
If one hub depends on another, the dependency should be visible.
|
||||
|
||||
### Rule 2: No authority smuggling
|
||||
|
||||
A hub must not use messaging to silently take over another hub’s mandate.
|
||||
|
||||
### Rule 3: No unbounded chatter
|
||||
|
||||
Coupling should reduce, not amplify, organizational noise.
|
||||
|
||||
### Rule 4: Summaries upward, detail locally
|
||||
|
||||
Higher levels should receive compressed meaning, not raw variety dumps.
|
||||
|
||||
### Rule 5: Hard boundaries remain hard
|
||||
|
||||
Cross-hub coordination must not bypass constitutional, security, or financial constraints.
|
||||
|
||||
---
|
||||
|
||||
# 10. Standard Cross-Hub Contract
|
||||
|
||||
To support federation, all hubs SHOULD expose a minimal common contract.
|
||||
|
||||
## 10.1 Required Generic Functions
|
||||
|
||||
### Orientation
|
||||
|
||||
* `get_domain_summary()`
|
||||
|
||||
### Messaging
|
||||
|
||||
* `get_messages()`
|
||||
* `send_message()`
|
||||
|
||||
### Risks and Alerts
|
||||
|
||||
* `get_risks()`
|
||||
* `get_alerts()`
|
||||
|
||||
### Coordination
|
||||
|
||||
* `request_capability()`
|
||||
* `record_event()`
|
||||
|
||||
### Escalation
|
||||
|
||||
* `escalate_issue()`
|
||||
|
||||
---
|
||||
|
||||
## 10.2 Domain-Specific Extensions
|
||||
|
||||
Beyond the shared contract, each hub SHOULD expose domain-specific functions.
|
||||
|
||||
Examples:
|
||||
|
||||
* Dev Hub: workstreams, capabilities, decisions
|
||||
* Ops Hub: services, incidents, runbooks, access paths
|
||||
* Sec Hub: controls, exposures, exceptions
|
||||
* Fin Hub: budgets, commitments, runway
|
||||
* Canon Hub: mandates, policies, delegation rules
|
||||
|
||||
---
|
||||
|
||||
# 11. Organizational Recursion
|
||||
|
||||
## 11.1 Recursion Principle
|
||||
|
||||
A federated organization may exist at multiple levels simultaneously.
|
||||
|
||||
Examples:
|
||||
|
||||
* a repo as a micro-domain
|
||||
* a hub as a domain-level coordinator
|
||||
* an operating company as a viable entity
|
||||
* a foundation or family structure as a higher-order viable system
|
||||
* a portfolio of ventures as a still higher recursion layer
|
||||
|
||||
The same viability logic should hold at each level.
|
||||
|
||||
---
|
||||
|
||||
## 11.2 Canonical Recursion Levels
|
||||
|
||||
### L0 — Subsystem / Repo / Service
|
||||
|
||||
A bounded working unit.
|
||||
|
||||
### L1 — Domain Hub
|
||||
|
||||
Dev, Ops, Sec, Fin, etc.
|
||||
|
||||
### L2 — Operating Entity
|
||||
|
||||
The company or core operating body.
|
||||
|
||||
### L3 — Umbrella Governance Entity
|
||||
|
||||
Foundation, holding structure, or multi-venture umbrella.
|
||||
|
||||
---
|
||||
|
||||
## 11.3 Escalation Across Recursion Levels
|
||||
|
||||
Escalation should occur when:
|
||||
|
||||
* local authority is insufficient
|
||||
* risk exceeds local tolerance
|
||||
* policy conflict cannot be resolved locally
|
||||
* resource conflict crosses domain boundaries
|
||||
* strategic redesign is required
|
||||
|
||||
The higher recursion level should receive a summary plus context, not raw noise.
|
||||
|
||||
---
|
||||
|
||||
# 12. Role Logic in a Federated Organization
|
||||
|
||||
FOS does not prescribe a rigid human org chart, but it does define role logic.
|
||||
|
||||
## 12.1 Every Domain Needs at Least
|
||||
|
||||
* an operational role
|
||||
* a coordination role
|
||||
* an analytical or review role
|
||||
|
||||
These may be human, artificial, or hybrid.
|
||||
|
||||
---
|
||||
|
||||
## 12.2 Higher-Order Roles
|
||||
|
||||
As the organization grows, meta-roles may emerge, such as:
|
||||
|
||||
* chief technical operator
|
||||
* security steward
|
||||
* portfolio strategist
|
||||
* constitutional steward
|
||||
* financial allocator
|
||||
|
||||
These roles should coordinate across hubs, not erase them.
|
||||
|
||||
---
|
||||
|
||||
# 13. Anti-Patterns
|
||||
|
||||
## 13.1 The Mega-Hub
|
||||
|
||||
One hub for everything.
|
||||
|
||||
This destroys separation of concerns and creates central mud.
|
||||
|
||||
---
|
||||
|
||||
## 13.2 The Silent Empire
|
||||
|
||||
A hub accumulates hidden authority and becomes de facto sovereign.
|
||||
|
||||
This undermines explicit governance.
|
||||
|
||||
---
|
||||
|
||||
## 13.3 Domain Collapse
|
||||
|
||||
Development, operations, security, and finance are treated as one blended management problem.
|
||||
|
||||
This guarantees confusion.
|
||||
|
||||
---
|
||||
|
||||
## 13.4 Connector Spaghetti
|
||||
|
||||
Cross-hub integration grows ad hoc without standard contracts.
|
||||
|
||||
This creates invisible fragility.
|
||||
|
||||
---
|
||||
|
||||
## 13.5 Upward Variety Flooding
|
||||
|
||||
Higher-order governance is flooded with low-level events and raw detail.
|
||||
|
||||
This breaks recursion.
|
||||
|
||||
---
|
||||
|
||||
# 14. Maturity Model
|
||||
|
||||
## Level 0 — Unstructured
|
||||
|
||||
No explicit hub logic, ad hoc coordination.
|
||||
|
||||
## Level 1 — Single-Hub Emergence
|
||||
|
||||
One hub exists, but boundaries are still mixed.
|
||||
|
||||
## Level 2 — Domain Hub Clarity
|
||||
|
||||
At least Dev and Ops are distinct.
|
||||
|
||||
## Level 3 — Core Federation
|
||||
|
||||
Canon, Dev, Ops, Sec, and Fin are conceptually separated and partially operational.
|
||||
|
||||
## Level 4 — Protocolized Coupling
|
||||
|
||||
Cross-hub messaging, requests, risks, and escalations follow standard contracts.
|
||||
|
||||
## Level 5 — Recursive Federation
|
||||
|
||||
Multiple entities or ventures operate under shared constitutional logic while retaining local autonomy.
|
||||
|
||||
---
|
||||
|
||||
# 15. Minimal Reference Architecture
|
||||
|
||||
A minimal scalable FOS architecture contains:
|
||||
|
||||
* one **Canon Hub**
|
||||
* one **Dev Hub**
|
||||
* one **Ops Hub**
|
||||
* one **Sec Hub**
|
||||
* one **Fin Hub**
|
||||
* one **common cross-hub protocol**
|
||||
* one **shared event and escalation vocabulary**
|
||||
* one **explicit recursion model**
|
||||
|
||||
Not all must be implemented at once, but the organization should know where it is heading.
|
||||
|
||||
---
|
||||
|
||||
# 16. Key Insight
|
||||
|
||||
> A scalable organization is not built by centralizing everything.
|
||||
> It is built by creating viable domains with clean boundaries, then coupling them through explicit hubs, shared protocols, and constitutional constraints.
|
||||
|
||||
---
|
||||
|
||||
# 17. Closing Statement
|
||||
|
||||
The **FederatedOrganisationStandard** defines an organization as a federation of viable domains rather than as a monolithic machine.
|
||||
|
||||
Its core commitments are:
|
||||
|
||||
* autonomy with accountability
|
||||
* coordination without collapse
|
||||
* policy without micromanagement
|
||||
* recursion without chaos
|
||||
* visibility without loss of sovereignty
|
||||
|
||||
It provides a path by which a single evolving project can grow into a multi-domain, multi-entity, foundation-compatible structure without losing clarity of identity or operational coherence.
|
||||
|
||||
xxx
|
||||
Reference in New Issue
Block a user