Integration Guide

This is the entry point for bringing up the sovereign workspace stack on a machine you control and for enrolling repositories into it.

The stack is a federated repository system: an umbrella repository orchestrates several independent clones, a sealed enforcement engine gates every commit and push, and compiled guards sit at the syscall boundary so the gates cannot be bypassed. It does far more than install a CI project and some hooks. Read this once end to end, then use the sections as a map.

Contents

• What this system is
• Federation map
• Trust domains and edit boundaries
• Host bring up
• Deploying the CI engine
• Installing the guard
• Integrating a consumer repository
• Quality gates and the commit flow
• Policy as code
• Companion subsystems
• Operations and recovery
• Where to next

What this system is

Three properties define the design:

• Data sovereignty. Web services, secrets, and model inference run on infrastructure you own. The agent loop does not require a vendor cloud.
• Immutability. The enforcement engine is constructed, verified, and sealed below /opt. The running artifact is never an editing target, and a bad deployment is corrected by redeploying reviewed source, never by editing the artifact in place.
• Workspace-wide compliance. Git hooks, guard policy, and quality gates apply to every nested repository. Enrollment is a decision made once; there is no per-repo opt-out afterwards.

The umbrella repository is WORKSPACE-VM. It owns the bootstrap catalog, the Makefile entrypoints, the clone manifest, the agent VM and network tooling, the local inference stack, and the benchmark suite. The other repositories under projects/ are independent clones with their own release cadence.

Federation map

The authoritative list is the clone manifest workspace/config/workspace-clones.yaml. Read the umbrella overview at WORKSPACE-VM/README.md.

flowchart TB
  operator(["Operator"])
  subgraph umbrella ["WORKSPACE-VM umbrella"]
    bootstrap["Bootstrap catalog + Makefile entrypoints"]
    clones[("projects/ independent clones")]
  end
  subgraph enforcement ["Enforcement"]
    ci["WORKSPACE-CI sealed at /opt/workspace-ci"]
    guard["WORKSPACE-GUARD at the syscall boundary"]
  end
  subgraph services ["Sovereign services"]
    gateway["WORKSPACE-GATEWAY LLM proxy + Grafana"]
    dataops["WORKSPACE-DATAOPS Postgres + identity"]
  end
  operator --> bootstrap
  bootstrap --> clones
  clones --> ci
  ci --> guard
  gateway -.-> ci
  dataops -.-> gateway

Trust domains and edit boundaries

Each path belongs to exactly one trust domain. The control column names who may write there.

Two rules follow from the table:

• Below /opt is forbidden territory. All mutations there are prohibited, and generated runtime paths are never rewritten. A failed or absent install is remedied by rerunning make deploy-ci from reviewed source.
• Root-owned policy is edited only through the secure interface. Use the guard's yaml-set, yaml-add, yaml-remove, yaml-unset, yaml-remove-comment, and yaml-delete verbs instead of rewriting files. Root ownership of .git/ metadata and config/ is the designed state, not damage.

Host bring up

Bring-up is staged so that an agent-owned clone can be prepared before any privileged installation:

make ensure-repos     # clone every repository in the manifest (non-root)
make install          # interactive bootstrap TUI, or:
make install-ci       # unattended bootstrap with fixed defaults
sudo make init        # privileged bootstrap: packages, deploy-ci, guard, hooks, log limits

make init performs several operations in one pass: it installs system packages from the catalog, publishes the sealed CI artifact with deploy-ci, installs the git guard, root-owns hooks and exemption files in every consumer repository, and enforces syslog ceilings. It fails loudly if the CI checkout is missing, so run make ensure-repos first.

Optional operator maintenance:

sudo make guard-up        # idempotent fleet bring-up (provision + guard install)
sudo make guard-refresh   # refresh guard code after a pull
make guard-check          # read-only health check

Component selection lives in workspace/config/bootstrap-components.yaml. Bootstrap binaries install into a platform-aware boot directory (.boot-linux/ or .boot-macos/) that the hooks and CLI extensions resolve by absolute path.

Deploying the CI engine

make deploy-ci is the only deployment contract. Run as root, it:

1. clones origin/main into /opt/.workspace-ci.candidate;
2. builds and verifies the candidate with local boot tools inside a private mount namespace, where the candidate is visible at its final logical path;
3. atomically publishes the candidate at /opt/workspace-ci on the same filesystem and seals it;
4. installs protected hooks as a separate operation.

The current artifact never participates in candidate construction, and candidate-path metadata is treated as a deployment failure rather than something to repair. A hook-installation failure leaves the artifact untouched; correct the failure and rerun the same flow.

When the deployed artifact itself gates every commit, recover by deploying a prior sanctioned generation, then land the fix through the restored gates and redeploy the tip:

sudo make deploy-ci REV=<commit>   # a committed ancestor of origin/main

The working checkout is never moved, and revisions that do not resolve to an ancestor are refused. The full procedure and rollback decision record are in RUNBOOK-HOOKS.md.

Installing the guard

WORKSPACE-GUARD wraps the most abusable surfaces of an agent machine. It is organized into five deployed programs:

Build and install the git guard through the CI wrappers:

sudo make build-guard
sudo make install-guard-host-exec
make check-guard-host-exec        # read-only, runs as the agent

The guard's public description and install table are in WORKSPACE-GUARD/README.md. Policy YAML under the guard config root is edited with the sudo-gated workspace-yaml-edit binary; block and sanitize reports can be rerouted to a working-directory audit sink for agent sessions.

Integrating a consumer repository

scaffold-ci is the profile-driven bootstrapper that enrolls a repository:

make scaffold-ci CONSUMER=<path> ARGS="--force-precommit --yes"

It generates the CI integration files, including .pre-commit-config.yaml, which declares hooks, stages, and file gates. The engine reads that file and generates native .git/hooks/* scripts from it; there is no framework runtime and no remote hook environment to clone. Requirements are in REQ-SCAFFOLD-CI.md.

Enforcement is tiered per project, resolved through project_enforcement.yaml:

Any config/<stem>.yaml can be redirected at runtime without copying the whole tree. CI_CONFIG_DIR, the CI_CONFIG_OVERRIDES manifest, and per-file CI_CONFIG_PATH_{STEM} variables resolve the same way across the bash hooks, the Python checkers, and the wiki.

Quality gates and the commit flow

Three non-redundant stages run at different moments:

Mirror the push gate locally before pushing:

make check        # lint + type-check + test
make check-push   # single-pass pre-push gate

The commit flow is exactly one command: git commit with the message supplied through -F. If nothing was staged, the pre-commit gate stages everything and fails with instructions, and re-running the same command succeeds. There is no selective staging, no stash, no reset, and no --amend; history is forward-only and a dirty tree rides the next commit as-is. A failing gate is never fought: fix the source and commit again.

Policy as code

The rules the gates enforce are data, not code:

• Banned patterns (semantic prohibitions, not style rules) live in config/banned_words.yaml, with per-project narrowing in the versioned exemption file.
• Swallowed-error detectors span Python, JavaScript, shell, Ansible, and cron in one catalog.
• File classifications and exact, per-file exemptions replace broad path-wide blankets; every exemption is scoped to a rule and a path.
• Effective-exemption receipts are generated deterministically and gated for drift, the same way lockfiles are.

Add a pattern or tune a threshold in config; no code change is required. The model and its guarantees are specified in REQ-BANNED-PATTERN-MATCHING.md.

Companion subsystems

A working workspace usually adds several of these:

• LLM gateway. WORKSPACE-GATEWAY relays shared model traffic through APISIX with per-tenant keys, spend limits, and redaction, and records usage and cost in ClickHouse and Grafana. Start it with make gw-start and deploy it on boot with make -C ../WORKSPACE-GATEWAY gateway-deploy. Overview: WORKSPACE-GATEWAY/README.md.
• Local inference. make llama-setup detects hardware, builds one stack profile (llamafile or llama.cpp), bundles weights, deploys a systemd service, and runs diagnostics. Benchmarks under benchmarks/ exercise the running stack.
• Agent VMs. make vm CONFIG=... provisions an isolated sandbox; rootless Podman is the default and QEMU adds a full kernel boundary for authoritative guard tests. Lifecycle state persists under .vms/.
• Host VPN. make vpn-install and make vpn-start join a remote workspace network with a boot-directory OpenVPN client.
• Sovereign data services. WORKSPACE-DATAOPS provides PostgreSQL, Keycloak, and Vaultwarden for the federation.
• Notifications. A shared notification engine captures systemd unit failures with priorities, cooldown, escalation, and mail and issue channels.
• Storage and limits. IO-heavy trees migrate to dedicated fast storage (make mount-ws-backup / make unmount-ws-backup), capacity limits are raised with sudo make enforce-multi-server-limits, and a persistent diagnostics sampler records pressure and file-descriptor evidence across power cycles.
• Agent CLI. The workspace-oc wrapper shards the agent database per repository and supports per-run context overrides.

Operations and recovery

• Health and logs. make guard-check, make wiki-prod-status, make diagnostics-status, and the systemd user units for the gateway, wiki, and tunnel.
• Artifact recovery. Reviewed-ancestor rollback with sudo make deploy-ci REV=<commit>.
• Guard refresh. sudo make guard-refresh after pulling guard code, then make guard-check.
• Storage. Mount and unmount the backup device with the Make targets rather than editing fstab by hand.
• Wiki and TLS. Build with make wiki-prod-build, deploy on boot with make wiki-prod-deploy, and route public traffic with make wiki-tunnel-deploy. Certificate renewal is a systemd timer.

Where to next

• Documentation hub and reading order: docs/README.md
• CI engine, gates, and tiers: WORKSPACE-CI/README.md
• Umbrella subsystems: WORKSPACE-VM/README.md
• Protected hook deployment and rollback: RUNBOOK-HOOKS.md

In the wiki itself, the catalogues below are generated from the same policy sources described here: /git-hooks, /anti-patterns, /hook-configs, /sandbox-configs, /tools-scripts, /static-analysis, and /llm-gateway.