olsitec/foundation
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

chore: scaffold olsitec-foundation mono-repo

Browse source 
Repo topology, baseline overlay, planning docs (PLAN-001/002), ADR-004/005,
and the bootstrap/packages/documentation skeleton. Implementation (T00+) not started.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Andreas Niemann 2026-06-30 17:10:46 +02:00
commit f18676e6b3
22 changed files with 1174 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

72
documentation/000_baseline.md Normal file
View file

@ -0,0 +1,72 @@
# 000 — `olsitec-foundation` Baseline (Overlay)
> This project follows the **canonical Olsitec agentic baseline**.
>
> **Canonical source**: `../../ai-baseline/000_baseline.md` (git repo `ai-baseline`, hosted at
> `forge.olsitec.de/olsitec/ai-baseline` once the foundation is up). Read it for the full operating
> model, modes, prime directives, documentation thresholds, delegation, and session protocols.
>
> This file lists only **foundation-specific deviations**. Where this overlay and the canonical
> baseline disagree, **this overlay wins for foundation work**.
---
## Foundation-Specific Deviations
### D1 — Default mode is HIGH-RISK / INFRA
Almost all foundation work touches a VM, Docker, Vault, Postgres, or secrets. Treat **BOOTSTRAP /
day-zero work as HIGH-RISK / INFRA by default**: verify host/cwd/branch, log commands, snapshot
before destructive steps (canonical §2.3, §11). Drop to BUILD only for pure docs/package edits.
### D2 — The master passphrase is sacred
- `PULUMI_CONFIG_PASSPHRASE` is the single root of trust (PLAN-002 §4, ADR-002).
- **Never** print, echo, log, or commit the passphrase, the Vault root token, or Vault unseal keys —
except as the already-encrypted `secure: v1:…` values inside `Pulumi.foundation.yaml`.
- Secrets at rest live **only** in: passphrase-encrypted Pulumi config, or Vault. Never in plain
files, never in docs, never in command logs.
### D3 — Hosting is Forgejo, not gitlab.com
- The canonical baseline / ADR-003 references `gitlab.com:olsitec-nci/*`. For the foundation, the
source of truth is **foundation-Forgejo** (`forge.olsitec.de/olsitec/*`). GitLab is what we are
**replacing**.
- During day-zero (before handover) the canonical remote may be a local clone + offsite mirror; after
PLAN-002 Phase 7, origin is Forgejo.
### D4 — Pulumi runs against a remote VM over SSH
- `bootstrap/` deploys via `@pulumi/docker` over SSH to the foundation VM. Before any `pulumi up`:
confirm **which VM** the Docker provider targets, the SSH key, and that you are on the intended
stack (`pulumi stack ls`). A local edit is **not** present on the VM until applied.
### D5 — Determinism is a hard requirement
- Pin every image and tool by **digest** in `VERSIONS`. No floating tags. `preflight/` enforces it.
- Credentials: random (high-entropy, via `@pulumi/random` → Vault) vs derived (deterministic from
config). The only external secret is the passphrase (PLAN-002 §4.2).
### D6 — MCP may not know this project yet
- `olsitec-foundation` is **not** registered in Olsitec MCP at authoring time (verified: MCP returns
only omnibook/fishreg/olsitrack2/svelte_common/third_party_apis/external_data_sync/seaspots).
- Treat **this repo as the source of truth**; register the project in MCP once stable (PLAN-002 §8).
### D7 — Repo topology
- Read [000_TOPOLOGY.md](000_TOPOLOGY.md) before creating files: know whether your change belongs in
`bootstrap/`, a `packages/pulumi-*`, `documentation/`, or the separate `ai-baseline` repo.
- Never bypass the four foundation interfaces (repo in Forgejo, image/chart in Forgejo registry,
secret in Vault, CI in Forgejo Actions) once they exist.
### D8 — Document homes
- Planning & strategy → `documentation/planning/`.
- Architecture decisions → `documentation/decisions/` (ADR-NNN).
- Interface contracts (T00) → `documentation/contracts/` (CONTRACT-NNN).
- Per-task agent workspaces → `documentation/agents/task_NNN_*/` (canonical §7.2).
---
## Quick pointers
| Need | Go to |
|------|-------|
| Full workflow rules | `../../ai-baseline/000_baseline.md` |
| Why the platform is layered | `decisions/ADR_004_layered_platform_foundation.md` |
| Repo boundaries / module strategy | `decisions/ADR_005_repo_topology.md`, `000_TOPOLOGY.md` |
| The vision | `planning/PLAN-001-forgejo.md` |
| The implementation strategy & task list | `planning/PLAN-002-foundation-implementation.md` |