Andreas Niemann
f18676e6b3
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>
72 lines
3.9 KiB
Markdown
72 lines
3.9 KiB
Markdown
# 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` |
|