feat(exec): log per-attempt chain verdicts for pass rate visibility

gitea.d-ma.be:30022 is refused externally — the NodePort is only
reachable on koala locally. Use HostName 127.0.0.1 in SSH config
so git@gitea.d-ma.be connects to localhost:30022 instead.

.dockerignore

@@ -0,0 +1,10 @@
+.git
+.gitea
+.worktrees
+.DS_Store
+*.log
+.env*
+.vscode
+.idea
+bin/
+brain/

.gitea/workflows/cd.yml

@@ -0,0 +1,68 @@
+name: cd
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  deploy:
+    name: Build and deploy
+    runs-on: self-hosted
+    env:
+      SERVICE: supervisor
+      IMAGE: gitea.d-ma.be/mathias/supervisor
+      INFRA_REPO: git@gitea.d-ma.be:mathias/infra.git
+      BUILDKIT_HOST: unix:///run/buildkit/buildkitd.sock
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Build and push image
+        run: |
+          set -e
+          trap 'rm -f /tmp/supervisor-image.tar' EXIT
+          IMAGE_TAG="${{ github.sha }}"
+          echo "Building ${IMAGE}:${IMAGE_TAG}"
+
+          # Build to local OCI tar (no registry auth needed at build time)
+          buildctl --addr "${BUILDKIT_HOST}" build \
+            --frontend dockerfile.v0 \
+            --local context=. \
+            --local dockerfile=. \
+            --opt build-arg:VERSION="${IMAGE_TAG}" \
+            --output type=oci,dest=/tmp/supervisor-image.tar
+
+          # Push with skopeo using simple credential flag (avoids OAuth token flow)
+          skopeo copy \
+            oci-archive:/tmp/supervisor-image.tar \
+            docker://${IMAGE}:${IMAGE_TAG} \
+            --dest-creds "${{ secrets.REGISTRY_CREDS }}"
+
+          echo "Built and pushed ${IMAGE}:${IMAGE_TAG}"
+
+      - name: Update infra repo
+        run: |
+          set -e
+          trap 'rm -rf /tmp/infra-update; rm -f ~/.ssh/infra_deploy_key' EXIT
+          IMAGE_TAG="${{ github.sha }}"
+          # Use internal Gitea SSH (runner is on koala — NodePort 30022 is reachable locally)
+          mkdir -p ~/.ssh
+          echo "${{ secrets.INFRA_DEPLOY_KEY }}" > ~/.ssh/infra_deploy_key
+          chmod 600 ~/.ssh/infra_deploy_key
+          printf 'Host gitea.d-ma.be\n  HostName 127.0.0.1\n  Port 30022\n  StrictHostKeyChecking no\n' >> ~/.ssh/config
+
+          GIT_SSH_COMMAND="ssh -i ~/.ssh/infra_deploy_key -o IdentitiesOnly=yes" \
+            git clone "${INFRA_REPO}" /tmp/infra-update
+
+          cd /tmp/infra-update
+          sed -i "s|gitea.d-ma.be/mathias/supervisor:.*|gitea.d-ma.be/mathias/supervisor:${IMAGE_TAG}|" \
+            "k3s/apps/${SERVICE}/deployment.yaml"
+
+          git config user.email "cd-bot@d-ma.be"
+          git config user.name "CD Bot"
+          git add "k3s/apps/${SERVICE}/deployment.yaml"
+          git commit -m "chore(deploy): ${SERVICE} → ${IMAGE_TAG}"
+          GIT_SSH_COMMAND="ssh -i ~/.ssh/infra_deploy_key -o IdentitiesOnly=yes" \
+            git push
+
+          echo "Infra repo updated: ${SERVICE} → ${IMAGE_TAG}"

DECISIONS.md

@@ -44,6 +44,29 @@ Record *why* things are the way they are. Future-you will thank present-you.
 
 **Consequences**: More operational complexity than Chroma, but isolation is non-negotiable for client work.
 
+## 2026-04-22 — Hyperguild scope reset: drop parametric learning, simplify brain
+
+**Context**: After shipping Phases 1–4 (MCP server, 6 skills, model orchestration, session logging, CD pipeline), we critically reviewed what was theater vs genuinely useful.
+
+**Decisions**:
+
+1. **Drop the parametric learning pipeline.** SFT/DPO/RL extraction, `brain/training-data/` directory structure, Axolotl/LLaMA-Factory fine-tuning loop — all cut. The loop requires thousands of high-quality examples to move the needle, which a solo consultant won't generate. Better base models ship faster than any fine-tuning effort could keep up with. This is a research project, not a productivity tool.
+
+2. **Simplify the brain to plain markdown.** `brain/knowledge/` replaces `brain/wiki/ + brain/raw/ + brain/training-data/`. The trainer and retrospective workers write markdown entries. `brain_query` searches markdown. No ingestion pipeline, no tagging for significance review, no structured JSONL formats.
+
+3. **Measure the escalation chain before assuming it's useful.** Local model (phi4) only belongs in a skill's chain if it passes Claude verification at a meaningful rate. Where it fails >70% of the time, it adds cost not value. Per-skill hit rate logging is the prerequisite to honest chain configuration.
+
+4. **Keep what's real**: MCP tool surface, session logging with attempt records, tier detection, CD pipeline, bridge to Claude Code.
+
+**What to build next** (in priority order):
+- `brain_query` injection into skill handlers before spawning workers — this makes the declarative brain actually function
+- `protocols.md` — behavioral contract injected into every worker prompt
+- Per-skill pass rate logging and chain tuning
+
+**Consequences**: Simpler system with a shorter feedback loop. The brain becomes real only when skill handlers query it. Training data ambitions deferred indefinitely — revisit if local model capabilities improve enough that fine-tuning becomes worthwhile.
+
+---
+
 ## 2026-04-08 — Mistral Vibe gets its own adapter
 
 **Context**: Vibe doesn't read `AGENTS.md` — it uses `~/.vibe/prompts/` and `~/.vibe/agents/` with TOML config.

Dockerfile

@@ -0,0 +1,50 @@
+# syntax=docker/dockerfile:1
+
+# ── Build stage ───────────────────────────────────────────────────────────────
+FROM golang:1.26-bookworm AS builder
+
+ARG VERSION=dev
+WORKDIR /src
+
+COPY go.mod go.sum ./
+RUN go mod download
+
+COPY . .
+RUN CGO_ENABLED=0 GOOS=linux GOARCH=amd64 \
+    go build -trimpath -ldflags="-s -w -X main.version=${VERSION}" \
+    -o /out/supervisor ./cmd/supervisor
+
+# ── Runtime stage ─────────────────────────────────────────────────────────────
+# Node.js 22 slim — needed for claude CLI subprocess
+FROM node:22-slim
+
+# Install claude CLI (provides the `claude` binary the supervisor shells out to)
+RUN npm install -g @anthropic-ai/claude-code \
+    && claude --version \
+    && echo "claude CLI installed"
+
+# Copy supervisor binary
+COPY --from=builder /out/supervisor /usr/local/bin/supervisor
+
+# Bake in config (models.yaml + skill discipline files)
+COPY config/ /app/config/
+
+# Run as non-root
+RUN groupadd -r supervisor && useradd -r -g supervisor -d /app supervisor
+
+WORKDIR /app
+
+# brain/ is writable state — mount a PersistentVolume here
+VOLUME /app/brain
+
+ENV SUPERVISOR_CONFIG_DIR=/app/config/supervisor
+ENV SUPERVISOR_MODELS_FILE=/app/config/models.yaml
+ENV SUPERVISOR_BRAIN_DIR=/app/brain
+ENV SUPERVISOR_SESSIONS_DIR=/app/brain/sessions
+ENV SUPERVISOR_PORT=3200
+
+USER supervisor
+
+EXPOSE 3200
+
+ENTRYPOINT ["/usr/local/bin/supervisor"]

cmd/supervisor/main.go

@@ -43,6 +43,17 @@ func main() {
 		os.Exit(1)
 	}
 
+	protocolsPrompt, err := os.ReadFile(cfg.ConfigDir + "/protocols.md")
+	if err != nil {
+		logger.Error("read protocols.md", "path", cfg.ConfigDir+"/protocols.md", "err", err)
+		os.Exit(1)
+	}
+
+	// prependProtocols prepends the shared protocols to a skill discipline file.
+	prependProtocols := func(skillPrompt []byte) string {
+		return string(protocolsPrompt) + "\n---\n\n" + string(skillPrompt)
+	}
+
 	tddPrompt, err := os.ReadFile(cfg.ConfigDir + "/tdd.md")
 	if err != nil {
 		logger.Error("read tdd.md", "path", cfg.ConfigDir+"/tdd.md", "err", err)
@@ -101,7 +112,21 @@ func main() {
 			}
 			attempts := make([]iexec.AttemptRecord, 0, len(chain))
 			orch := iexec.NewOrchestrator(chain, litellmExec.Run, claudeExec.Run, verifier, models.LlamaSwapURL(), &attempts)
-			return orch.Run(ctx, req)
+			result, err := orch.Run(ctx, req)
+			result.Attempts = attempts // attach orchestration metadata before returning
+			// Log per-attempt verdicts so pass rates are visible in pod logs.
+			for i, a := range attempts {
+				logger.Info("chain attempt",
+					"skill", skill,
+					"attempt", i+1,
+					"model", a.Model,
+					"tier", a.Tier,
+					"verdict", a.Verdict,
+					"duration_ms", a.DurationMs,
+					"warm", a.WarmStart,
+				)
+			}
+			return result, err
 		}
 	}
 
@@ -112,10 +137,11 @@ func main() {
 	reg := registry.New()
 	reg.Register(tdd.New(tdd.Config{
 		SystemPrompt:  string(systemPrompt),
-		SkillPrompt:  string(tddPrompt),
+		SkillPrompt:   prependProtocols(tddPrompt),
 		DefaultModel:  models.ChainFor("tdd", "")[0],
 		ExecutorFn:    buildOrch("tdd"),
 		SessionsDir:   cfg.SessionsDir,
+		IngestBaseURL: cfg.IngestBaseURL,
 	}))
 	reg.Register(brain.New(brain.Config{
 		IngestBaseURL: cfg.IngestBaseURL,
@@ -127,32 +153,35 @@ func main() {
 		SessionsDir: cfg.SessionsDir,
 	}))
 	reg.Register(retrospective.New(retrospective.Config{
-		SkillPrompt:  string(retroPrompt),
+		SkillPrompt:  prependProtocols(retroPrompt),
 		DefaultModel: models.ChainFor("retrospective", "")[0],
 		SessionsDir:  cfg.SessionsDir,
 		ExecutorFn:   buildOrch("retrospective"),
 	}))
 	reg.Register(review.New(review.Config{
-		SkillPrompt:  string(reviewPrompt),
+		SkillPrompt:   prependProtocols(reviewPrompt),
 		DefaultModel:  models.ChainFor("review", "")[0],
 		ExecutorFn:    buildOrch("review"),
 		SessionsDir:   cfg.SessionsDir,
+		IngestBaseURL: cfg.IngestBaseURL,
 	}))
 	reg.Register(skilldebug.New(skilldebug.Config{
-		SkillPrompt:  string(debugPrompt),
+		SkillPrompt:   prependProtocols(debugPrompt),
 		DefaultModel:  models.ChainFor("debug", "")[0],
 		ExecutorFn:    buildOrch("debug"),
 		SessionsDir:   cfg.SessionsDir,
+		IngestBaseURL: cfg.IngestBaseURL,
 	}))
 	reg.Register(spec.New(spec.Config{
-		SkillPrompt:  string(specPrompt),
+		SkillPrompt:   prependProtocols(specPrompt),
 		DefaultModel:  models.ChainFor("spec", "")[0],
 		ExecutorFn:    buildOrch("spec"),
 		SessionsDir:   cfg.SessionsDir,
+		IngestBaseURL: cfg.IngestBaseURL,
 	}))
 	reg.Register(trainer.New(trainer.Config{
-		ReaderPrompt: string(trainerReaderPrompt),
+		ReaderPrompt: prependProtocols(trainerReaderPrompt),
-		WriterPrompt: string(trainerWriterPrompt),
+		WriterPrompt: prependProtocols(trainerWriterPrompt),
 		DefaultModel: models.ChainFor("trainer", "")[0],
 		ExecutorFn:   buildOrch("trainer"),
 		SessionsDir:  cfg.SessionsDir,
@@ -164,7 +193,7 @@ func main() {
 	mux.Handle("/mcp", srv)
 
 	addr := ":" + cfg.Port
-	logger.Info("supervisor starting", "addr", addr)
+	logger.Info("supervisor starting", "addr", addr, "version", "v0.4.0")
 	if err := http.ListenAndServe(addr, mux); err != nil {
 		logger.Error("server stopped", "err", err)
 		os.Exit(1)

config/supervisor/protocols.md

@@ -1,27 +1,55 @@
-# The Hyperguild Way
+# The Hyperguild Way — Worker Protocols
 
-These protocols are injected into every worker invocation. They define how you behave as a member of the hyperguild.
+Injected into every worker invocation alongside the skill discipline file.
+Defines the behavioral contract all workers must follow regardless of skill or model.
+
+---
 
 ## Output contract
 
-Every response is raw JSON matching the response schema. No preamble, no prose, no markdown. Malformed output is treated as a failed invocation.
+Every response is raw JSON matching the skill's output schema.
+- No preamble, no explanation, no prose before or after the JSON
+- No markdown code fences around the JSON
+- Malformed output is treated as a failed invocation
+- If uncertain, return valid JSON anyway — put uncertainty in `message`
 
 ## Quality gate
 
-`verified: true` only when a subprocess exit code confirms the outcome. Never self-assess. "I think the tests pass" is not verified.
+`verified: true` means the artifact was independently confirmed correct:
+- For code: the test runner exited 0
+- For files: the file exists at the path you wrote
+- Never set `verified: true` based on self-assessment — only on external confirmation
+- "I think the tests pass" is not verified. Run them.
 
 ## Escalation
 
-If stuck after 3 attempts, return `status: error` with a clear `message` explaining why. Do not retry silently. Do not fabricate a passing result.
+If stuck after a genuine attempt:
+- Return `status: error` with a clear reason in `message`
+- Do not retry silently or produce low-confidence output labelled as a pass
+- Do not hallucinate file paths, test results, or exit codes
+- Maximum 3 attempts per phase — if output is identical across two consecutive attempts, stop immediately
 
-## Working offline
+## Context usage
 
-If brain context is absent from your prompt, proceed using your discipline file only. Note the gap in your `message` field: "no brain context available".
+You may receive a `## Relevant knowledge` block and/or a `## Session history` block before your task.
+- **Relevant knowledge**: patterns, decisions, and conventions from past sessions. Let them inform your approach — do not contradict them without reason.
+- **Session history**: what has already happened in this session. Build on it, do not repeat it.
+- If either block is absent, proceed with the skill discipline file only. Note the absence in `message` if it materially affects quality.
 
-## Handoff format
+## Handoff discipline
 
-Structure your output so the next worker in a chain can consume it without transformation. Use the standard result schema. Do not add extra fields.
+Structure output so the next worker in a chain can consume it without transformation:
+- `file_path`: absolute path to the primary artifact you produced
+- `runner_output`: verbatim stdout+stderr from the last command you ran (truncate to 2000 chars if longer)
+- `message`: one sentence — what you did and whether it worked
+
+## Scope
+
+You have access to `Bash`, `Read`, and `Write` only.
+- Do not attempt to call MCP tools or make HTTP requests
+- Do not modify files outside `project_root` without explicit instruction
+- If the task requires capabilities you do not have, return `status: error`
 
 ## Session logging
 
-The Go skill handler records your invocation in the session log automatically. You do not need to do this yourself.
+The Go skill handler records your invocation automatically. You do not need to log anything yourself.

docs/superpowers/plans/2026-04-20-cd-pipeline.md

@@ -0,0 +1,923 @@
+# CD Pipeline Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Build a GitOps CD pipeline that automatically builds a container image on `main` push and deploys it to k3s on koala via Flux.
+
+**Architecture:** BuildKit runs as a systemd service on koala (same host as the Gitea runner); CD pushes images to the Gitea registry and commits image tag updates to the infra repo; Flux reconciles within 60s. App secrets (including ANTHROPIC_API_KEY) are SOPS-encrypted in the infra repo and decrypted by Flux at apply time.
+
+**Tech Stack:** Go 1.26, Node.js 22 (for claude CLI), BuildKit (buildctl), Gitea Actions, Flux (kustomize-controller), SOPS + age, k3s/containerd
+
+---
+
+## Environment context
+
+This plan spans three environments. Each task header notes which environment it runs in:
+
+- **[this-repo]** — `/Users/mathias/Documents/local-dev/AI/supervisor` on flamingo
+- **[koala-ssh]** — `ssh koala` (run commands via `ssh koala "..."`)
+- **[infra-repo]** — `gitea.d-ma.be/mathias/infra` (clone to a temp dir, work there, push)
+- **[gitea-ui]** — Gitea web UI at `https://gitea.d-ma.be`
+- **[kubectl]** — kubectl from flamingo (home LAN)
+
+---
+
+## File map
+
+**This repo (supervisor):**
+- Create: `Dockerfile`
+- Create: `.gitea/workflows/cd.yml`
+
+**koala host:**
+- Create: `/etc/systemd/system/buildkitd.service` (or user-level equivalent)
+- Create: `/root/.config/buildkit/buildkitd.toml` (registry auth config)
+
+**Infra repo (`gitea.d-ma.be/mathias/infra`):**
+- Create: `apps/supervisor/namespace.yaml`
+- Create: `apps/supervisor/deployment.yaml`
+- Create: `apps/supervisor/service.yaml`
+- Create: `apps/supervisor/secrets.enc.yaml` (SOPS-encrypted)
+- Create: `apps/supervisor/kustomization.yaml`
+- Create: `apps/imagepullsecret/secret.enc.yaml` (SOPS-encrypted)
+- Create: `apps/imagepullsecret/kustomization.yaml`
+- Modify: `clusters/koala/kustomization.yaml` (add supervisor + imagepullsecret)
+- Modify: `flux-system/kustomization.yaml` or relevant Flux Kustomization CRD (add SOPS decryption)
+
+---
+
+## Task 1: Dockerfile [this-repo]
+
+The supervisor binary depends on the `claude` CLI as a subprocess. The image uses a multi-stage build: Go builder stage compiles the binary; the runtime stage is Node.js (for `npm install -g @anthropic-ai/claude-code`). Config files are baked in. The `brain/` directory is a volume mount.
+
+**Files:**
+- Create: `Dockerfile`
+
+- [ ] **Step 1: Verify no Dockerfile exists**
+
+```bash
+ls Dockerfile 2>/dev/null || echo "confirmed: no Dockerfile"
+```
+
+Expected: `confirmed: no Dockerfile`
+
+- [ ] **Step 2: Create the Dockerfile**
+
+```dockerfile
+# syntax=docker/dockerfile:1
+
+# ── Build stage ───────────────────────────────────────────────────────────────
+FROM golang:1.26-bookworm AS builder
+
+ARG VERSION=dev
+WORKDIR /src
+
+COPY go.mod go.sum ./
+RUN go mod download
+
+COPY . .
+RUN CGO_ENABLED=0 GOOS=linux GOARCH=amd64 \
+    go build -trimpath -ldflags="-s -w -X main.version=${VERSION}" \
+    -o /out/supervisor ./cmd/supervisor
+
+# ── Runtime stage ─────────────────────────────────────────────────────────────
+# Node.js 22 slim — needed for claude CLI subprocess
+FROM node:22-slim
+
+# Install claude CLI (provides the `claude` binary the supervisor shells out to)
+RUN npm install -g @anthropic-ai/claude-code \
+    && claude --version \
+    && echo "claude CLI installed"
+
+# Copy supervisor binary
+COPY --from=builder /out/supervisor /usr/local/bin/supervisor
+
+# Bake in config (models.yaml + skill discipline files)
+COPY config/ /app/config/
+
+WORKDIR /app
+
+# brain/ is writable state — mount a PersistentVolume here
+VOLUME /app/brain
+
+ENV SUPERVISOR_CONFIG_DIR=/app/config/supervisor
+ENV SUPERVISOR_MODELS_FILE=/app/config/models.yaml
+ENV SUPERVISOR_BRAIN_DIR=/app/brain
+ENV SUPERVISOR_SESSIONS_DIR=/app/brain/sessions
+ENV SUPERVISOR_PORT=3200
+
+EXPOSE 3200
+
+ENTRYPOINT ["/usr/local/bin/supervisor"]
+```
+
+- [ ] **Step 3: Build locally to verify it compiles (no push)**
+
+```bash
+# buildctl must be available locally, OR use docker if available on flamingo
+docker build --target builder -t supervisor-build-test . && echo "build stage OK"
+# If no docker on flamingo, skip this step and verify at Task 3 on koala instead
+```
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add Dockerfile
+git commit -m "feat: add multi-stage Dockerfile with claude CLI runtime"
+```
+
+---
+
+## Task 2: BuildKit systemd service on koala [koala-ssh]
+
+Install `buildkitd` as a root-level systemd service on koala. The Gitea runner process runs as root (confirmed by PID/cgroup), so the root socket at `/run/buildkit/buildkitd.sock` is accessible to it.
+
+**Files:**
+- Create: `/etc/systemd/system/buildkitd.service` on koala
+- Create: `/etc/buildkit/buildkitd.toml` on koala (registry auth)
+
+- [ ] **Step 1: Check if buildkitd is already installed**
+
+```bash
+ssh koala "buildkitd --version 2>/dev/null || echo 'not installed'"
+```
+
+- [ ] **Step 2: Install buildkitd on koala**
+
+Download the latest buildkit release binary (arm64 or amd64 — koala has x86_64):
+
+```bash
+ssh koala "
+  BUILDKIT_VERSION=v0.21.0
+  curl -sSL https://github.com/moby/buildkit/releases/download/\${BUILDKIT_VERSION}/buildkit-\${BUILDKIT_VERSION}.linux-amd64.tar.gz \
+    | tar -xz -C /usr/local/
+  buildkitd --version
+"
+```
+
+Expected output includes: `buildkitd github.com/moby/buildkit v0.21.0`
+
+- [ ] **Step 3: Create buildkitd.toml with Gitea registry auth**
+
+The `[registry]` block configures auth for pushing to `gitea.d-ma.be`. The actual credentials come from `~/.docker/config.json` (which buildkitd reads automatically) — this toml just enables the registry:
+
+```bash
+ssh koala "
+  mkdir -p /etc/buildkit
+  cat > /etc/buildkit/buildkitd.toml << 'EOF'
+[worker.containerd]
+  enabled = false
+
+[worker.oci]
+  enabled = true
+
+[registry.\"gitea.d-ma.be\"]
+  http = false
+  insecure = false
+EOF
+"
+```
+
+- [ ] **Step 4: Create systemd unit**
+
+```bash
+ssh koala "
+  cat > /etc/systemd/system/buildkitd.service << 'EOF'
+[Unit]
+Description=BuildKit daemon
+After=network.target
+
+[Service]
+Type=notify
+ExecStart=/usr/local/bin/buildkitd --config /etc/buildkit/buildkitd.toml
+Restart=on-failure
+LimitNOFILE=1048576
+LimitNPROC=1048576
+
+[Install]
+WantedBy=multi-user.target
+EOF
+  systemctl daemon-reload
+  systemctl enable buildkitd
+  systemctl start buildkitd
+"
+```
+
+- [ ] **Step 5: Verify the socket exists and is responsive**
+
+```bash
+ssh koala "
+  systemctl status buildkitd --no-pager
+  buildctl --addr unix:///run/buildkit/buildkitd.sock debug info
+"
+```
+
+Expected: service `active (running)`, buildctl shows BuildKit version info.
+
+- [ ] **Step 6: Smoke-test build with trivial Dockerfile**
+
+```bash
+ssh koala "
+  echo 'FROM alpine:3.21
+  RUN echo hello' | buildctl --addr unix:///run/buildkit/buildkitd.sock build \
+    --frontend dockerfile.v0 \
+    --local context=/ \
+    --opt filename=Dockerfile \
+    --output type=image,name=localhost/smoke-test:latest
+  echo 'smoke test OK'
+"
+```
+
+Expected: `smoke test OK`
+
+---
+
+## Task 3: Gitea registry push auth for buildctl [koala-ssh]
+
+`buildctl` reads Docker-style credentials from `/root/.docker/config.json`. Create the credentials file so the runner can push to `gitea.d-ma.be`.
+
+**Prerequisites:** A Gitea user token or password with `write:packages` scope for the `mathias` org. Create one in Gitea → User Settings → Applications → Generate Token (scopes: `write:packages`).
+
+- [ ] **Step 1: Create Gitea access token**
+
+In Gitea UI (`https://gitea.d-ma.be`) → top-right avatar → Settings → Applications → Generate New Token.
+- Token name: `buildkit-push`
+- Scopes: `write:packages` (container registry write)
+- Copy the token — it won't be shown again.
+
+- [ ] **Step 2: Write docker config.json on koala**
+
+Replace `<TOKEN>` with the token from Step 1:
+
+```bash
+ssh koala "
+  mkdir -p /root/.docker
+  TOKEN=<TOKEN>
+  AUTH=\$(echo -n 'mathias:'\${TOKEN} | base64)
+  cat > /root/.docker/config.json << EOF
+{
+  \"auths\": {
+    \"gitea.d-ma.be\": {
+      \"auth\": \"\${AUTH}\"
+    }
+  }
+}
+EOF
+  chmod 600 /root/.docker/config.json
+  echo 'credentials written'
+"
+```
+
+- [ ] **Step 3: Verify push works**
+
+```bash
+ssh koala "
+  echo 'FROM alpine:3.21' | buildctl --addr unix:///run/buildkit/buildkitd.sock build \
+    --frontend dockerfile.v0 \
+    --local context=/ \
+    --opt filename=Dockerfile \
+    --output type=image,name=gitea.d-ma.be/mathias/supervisor:push-test,push=true
+  echo 'push OK'
+"
+```
+
+Expected: `push OK`. Verify in Gitea UI: `https://gitea.d-ma.be/mathias/supervisor/packages` should show a `push-test` tag.
+
+- [ ] **Step 4: Delete the test image tag**
+
+In Gitea UI → supervisor repo → Packages tab → delete the `push-test` tag.
+
+---
+
+## Task 4: age keypair + Flux SOPS decryption [kubectl + flamingo]
+
+Flux decrypts SOPS-encrypted secrets at apply time. It needs the age private key stored as a k8s Secret in the `flux-system` namespace.
+
+- [ ] **Step 1: Verify age is installed**
+
+```bash
+age --version || brew install age
+```
+
+- [ ] **Step 2: Generate age keypair**
+
+```bash
+age-keygen -o /tmp/supervisor-age.key
+cat /tmp/supervisor-age.key
+```
+
+Output includes two lines:
+```
+# public key: age1xxxxxx...
+AGE-SECRET-KEY-1xxxxxxx...
+```
+
+**Copy the public key** (the `age1...` value) — you'll need it in Task 7 for encrypting secrets.
+**Store the private key file securely** — back it up outside the cluster (e.g., 1Password or encrypted note).
+
+- [ ] **Step 3: Create the SOPS age secret in flux-system**
+
+```bash
+kubectl create secret generic sops-age \
+  --from-file=age.agekey=/tmp/supervisor-age.key \
+  -n flux-system
+kubectl get secret sops-age -n flux-system
+```
+
+Expected: secret exists with `age.agekey` key.
+
+- [ ] **Step 4: Shred the temp key file**
+
+```bash
+shred -u /tmp/supervisor-age.key
+```
+
+- [ ] **Step 5: Check what Flux Kustomization CRDs exist in the infra repo**
+
+```bash
+git clone git@gitea.d-ma.be:mathias/infra.git /tmp/infra-sops-setup
+ls /tmp/infra-sops-setup/flux-system/
+```
+
+Look for a `kustomization.yaml` or `gotk-sync.yaml` that defines the main Flux Kustomization resource pointing at the `clusters/koala/` path.
+
+- [ ] **Step 6: Patch the Flux Kustomization to enable SOPS decryption**
+
+Find the Kustomization resource that syncs `clusters/koala/`. It will look like:
+
+```yaml
+apiVersion: kustomize.toolkit.fluxcd.io/v1
+kind: Kustomization
+metadata:
+  name: flux-system
+  namespace: flux-system
+spec:
+  path: ./clusters/koala
+  ...
+```
+
+Add the `decryption` block:
+
+```yaml
+  decryption:
+    provider: sops
+    secretRef:
+      name: sops-age
+```
+
+Edit the file in `/tmp/infra-sops-setup/flux-system/` and commit:
+
+```bash
+cd /tmp/infra-sops-setup
+# Edit the relevant Kustomization yaml to add decryption block (shown above)
+git add flux-system/
+git commit -m "feat: enable SOPS decryption via age key in flux-system"
+git push
+```
+
+- [ ] **Step 7: Verify Flux picks up the change**
+
+```bash
+flux reconcile source git flux-system
+flux get kustomizations
+```
+
+Expected: `flux-system` Kustomization shows `Ready True` with no errors.
+
+- [ ] **Step 8: Clean up temp clone**
+
+```bash
+rm -rf /tmp/infra-sops-setup
+```
+
+---
+
+## Task 5: Infra repo — supervisor app manifests [infra-repo]
+
+Create the full k8s manifest set for the supervisor service in the infra repo. The deployment uses an `IMAGE_TAG` placeholder; the CD job patches this with the actual git sha before pushing.
+
+**Prerequisites:** age public key from Task 4 Step 2.
+
+- [ ] **Step 1: Clone the infra repo**
+
+```bash
+git clone git@gitea.d-ma.be:mathias/infra.git /tmp/infra-supervisor
+cd /tmp/infra-supervisor
+```
+
+- [ ] **Step 2: Create namespace**
+
+```bash
+mkdir -p apps/supervisor
+cat > apps/supervisor/namespace.yaml << 'EOF'
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: supervisor
+EOF
+```
+
+- [ ] **Step 3: Create deployment**
+
+The `brain` volume is a `hostPath` on koala (simplest for a single-node service; add a PVC later if needed). The image uses `imagePullSecrets` to pull from the Gitea registry.
+
+```bash
+cat > apps/supervisor/deployment.yaml << 'EOF'
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: supervisor
+  namespace: supervisor
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: supervisor
+  template:
+    metadata:
+      labels:
+        app: supervisor
+    spec:
+      nodeSelector:
+        kubernetes.io/hostname: koala
+      imagePullSecrets:
+        - name: gitea-registry
+      containers:
+        - name: supervisor
+          image: gitea.d-ma.be/mathias/supervisor:IMAGE_TAG
+          ports:
+            - containerPort: 3200
+          envFrom:
+            - secretRef:
+                name: supervisor-secrets
+          env:
+            - name: SUPERVISOR_PORT
+              value: "3200"
+            - name: LITELLM_BASE_URL
+              value: "http://iguana:4000"
+            - name: LLAMA_SWAP_URL
+              value: "http://koala:8080"
+            - name: INGEST_BASE_URL
+              value: "http://localhost:3300"
+          volumeMounts:
+            - name: brain
+              mountPath: /app/brain
+      volumes:
+        - name: brain
+          hostPath:
+            path: /var/lib/supervisor/brain
+            type: DirectoryOrCreate
+EOF
+```
+
+- [ ] **Step 4: Create service**
+
+```bash
+cat > apps/supervisor/service.yaml << 'EOF'
+apiVersion: v1
+kind: Service
+metadata:
+  name: supervisor
+  namespace: supervisor
+spec:
+  selector:
+    app: supervisor
+  ports:
+    - port: 3200
+      targetPort: 3200
+  type: ClusterIP
+EOF
+```
+
+- [ ] **Step 5: Create kustomization.yaml for supervisor**
+
+```bash
+cat > apps/supervisor/kustomization.yaml << 'EOF'
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+resources:
+  - namespace.yaml
+  - deployment.yaml
+  - service.yaml
+  - secrets.enc.yaml
+EOF
+```
+
+- [ ] **Step 6: Ensure clusters/koala/kustomization.yaml exists and includes supervisor**
+
+Check if the file exists:
+
+```bash
+cat clusters/koala/kustomization.yaml 2>/dev/null || echo "need to create"
+```
+
+If it exists, add supervisor and imagepullsecret resources. If it does not exist, create it:
+
+```bash
+cat > clusters/koala/kustomization.yaml << 'EOF'
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+resources:
+  - ../../apps/imagepullsecret
+  - ../../apps/supervisor
+EOF
+```
+
+If it already exists, add the two resource lines (preserving existing entries).
+
+- [ ] **Step 7: Commit (without secrets — those come in Task 6)**
+
+```bash
+cd /tmp/infra-supervisor
+git add apps/supervisor/ clusters/koala/
+git commit -m "feat(supervisor): add k8s manifests for supervisor service"
+git push
+```
+
+---
+
+## Task 6: SOPS-encrypted secrets in infra repo [infra-repo + flamingo]
+
+Two encrypted secret files: the imagePullSecret for the Gitea container registry, and the supervisor app secrets (ANTHROPIC_API_KEY, LITELLM_API_KEY).
+
+**Prerequisites:**
+- age public key from Task 4 Step 2 (format: `age1xxxxx...`)
+- `sops` installed (`brew install sops` if missing)
+- Gitea registry token (same one used in Task 3, or create a read-only one for pulling)
+
+- [ ] **Step 1: Verify sops is installed**
+
+```bash
+sops --version || brew install sops
+```
+
+- [ ] **Step 2: Create .sops.yaml in infra repo root**
+
+This tells sops which key to use for all files in the repo:
+
+```bash
+cd /tmp/infra-supervisor
+cat > .sops.yaml << 'EOF'
+creation_rules:
+  - age: age1REPLACE_WITH_YOUR_PUBLIC_KEY
+EOF
+git add .sops.yaml
+git commit -m "chore: add sops config (age key)"
+git push
+```
+
+Replace `age1REPLACE_WITH_YOUR_PUBLIC_KEY` with the actual age public key from Task 4.
+
+- [ ] **Step 3: Create and encrypt the imagePullSecret**
+
+The imagePullSecret is a namespace-less Secret (it will be targeted per namespace via Kustomize). Create it in the `imagepullsecret` app:
+
+```bash
+mkdir -p apps/imagepullsecret
+
+# Create a registry pull token in Gitea: Settings → Applications → Generate Token
+# Scopes: read:packages
+# Use that token here (or reuse the buildkit-push token — read access is enough for pulling)
+PULL_TOKEN=<gitea-read-packages-token>
+PULL_AUTH=$(echo -n "mathias:${PULL_TOKEN}" | base64)
+
+cat > /tmp/gitea-pull-secret.yaml << EOF
+apiVersion: v1
+kind: Secret
+metadata:
+  name: gitea-registry
+  namespace: supervisor
+type: kubernetes.io/dockerconfigjson
+stringData:
+  .dockerconfigjson: |
+    {
+      "auths": {
+        "gitea.d-ma.be": {
+          "auth": "${PULL_AUTH}"
+        }
+      }
+    }
+EOF
+
+sops --encrypt /tmp/gitea-pull-secret.yaml > apps/imagepullsecret/secret.enc.yaml
+rm /tmp/gitea-pull-secret.yaml
+
+cat > apps/imagepullsecret/kustomization.yaml << 'EOF'
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+resources:
+  - secret.enc.yaml
+EOF
+```
+
+Verify the encrypted file looks correct (should show `sops:` metadata at the bottom):
+
+```bash
+tail -20 apps/imagepullsecret/secret.enc.yaml
+```
+
+- [ ] **Step 4: Create and encrypt supervisor app secrets**
+
+```bash
+# ANTHROPIC_API_KEY: your Anthropic API key
+# LITELLM_API_KEY: the key your LiteLLM instance expects (can be any string if it's local)
+cat > /tmp/supervisor-secrets.yaml << 'EOF'
+apiVersion: v1
+kind: Secret
+metadata:
+  name: supervisor-secrets
+  namespace: supervisor
+type: Opaque
+stringData:
+  ANTHROPIC_API_KEY: "REPLACE_WITH_REAL_KEY"
+  LITELLM_API_KEY: "REPLACE_WITH_REAL_KEY"
+EOF
+
+# Edit /tmp/supervisor-secrets.yaml to insert real values, then:
+sops --encrypt /tmp/supervisor-secrets.yaml > apps/supervisor/secrets.enc.yaml
+rm /tmp/supervisor-secrets.yaml
+```
+
+Verify:
+
+```bash
+tail -20 apps/supervisor/secrets.enc.yaml
+# Should show encrypted values and sops metadata
+```
+
+- [ ] **Step 5: Commit encrypted secrets**
+
+```bash
+cd /tmp/infra-supervisor
+git add apps/imagepullsecret/ apps/supervisor/secrets.enc.yaml .sops.yaml
+git commit -m "feat: add SOPS-encrypted imagePullSecret and supervisor app secrets"
+git push
+```
+
+- [ ] **Step 6: Verify Flux reconciles and creates the secrets**
+
+Wait ~60s then:
+
+```bash
+flux reconcile kustomization flux-system --with-source
+kubectl get secrets -n supervisor
+```
+
+Expected: `gitea-registry` and `supervisor-secrets` appear in the `supervisor` namespace.
+
+- [ ] **Step 7: Clean up temp clone**
+
+```bash
+rm -rf /tmp/infra-supervisor
+```
+
+---
+
+## Task 7: Gitea org-level secrets [gitea-ui + koala-ssh]
+
+Set the three secrets that all repos in the `mathias` org will inherit. These go in the Gitea org (not individual repos).
+
+**Files:** No files — Gitea UI configuration.
+
+- [ ] **Step 1: Generate SSH deploy key for infra repo**
+
+On flamingo:
+
+```bash
+ssh-keygen -t ed25519 -C "cd-bot infra deploy key" -f /tmp/infra-deploy-key -N ""
+cat /tmp/infra-deploy-key      # private key → INFRA_DEPLOY_KEY secret
+cat /tmp/infra-deploy-key.pub  # public key → add to Gitea infra repo as deploy key
+```
+
+- [ ] **Step 2: Add public key to infra repo as a deploy key (write access)**
+
+In Gitea UI: `https://gitea.d-ma.be/mathias/infra` → Settings → Deploy Keys → Add Deploy Key.
+- Title: `cd-bot`
+- Key: paste content of `/tmp/infra-deploy-key.pub`
+- Enable write access: ✓
+
+- [ ] **Step 3: Set org-level secrets in Gitea**
+
+In Gitea UI: `https://gitea.d-ma.be/org/mathias/settings/secrets` → Add Secret.
+
+Set these three secrets:
+
+| Secret name | Value |
+|-------------|-------|
+| `INFRA_DEPLOY_KEY` | content of `/tmp/infra-deploy-key` (private key, including `-----BEGIN...` lines) |
+| `BUILDKIT_REGISTRY_AUTH` | same base64 auth string as used in Task 3 Step 2 (format: `mathias:<token>` base64-encoded) |
+
+Note: `BUILDKIT_REGISTRY_AUTH` is redundant if `/root/.docker/config.json` is already on the runner host from Task 3 — but setting it as a secret allows the `cd.yml` to explicitly pass it to `buildctl` for clarity and rotation.
+
+- [ ] **Step 4: Clean up temp key files**
+
+```bash
+shred -u /tmp/infra-deploy-key /tmp/infra-deploy-key.pub
+```
+
+- [ ] **Step 5: Verify secrets appear in Gitea**
+
+In Gitea UI: `https://gitea.d-ma.be/org/mathias/settings/secrets` — confirm both secrets are listed (values are hidden, only names shown).
+
+---
+
+## Task 8: cd.yml workflow [this-repo]
+
+Create the CD workflow that triggers after CI passes, builds the image with buildctl, and commits the updated tag to the infra repo.
+
+**Files:**
+- Create: `.gitea/workflows/cd.yml`
+
+- [ ] **Step 1: Create cd.yml**
+
+```bash
+cat > .gitea/workflows/cd.yml << 'EOF'
+name: cd
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  deploy:
+    name: Build and deploy
+    needs: [check]         # 'check' is the job name in ci.yml
+    runs-on: self-hosted
+    env:
+      SERVICE: supervisor
+      REGISTRY: gitea.d-ma.be
+      IMAGE: gitea.d-ma.be/mathias/supervisor
+      INFRA_REPO: git@gitea.d-ma.be:mathias/infra.git
+      BUILDKIT_HOST: unix:///run/buildkit/buildkitd.sock
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Build and push image
+        run: |
+          IMAGE_TAG="${{ github.sha }}"
+          echo "Building ${IMAGE}:${IMAGE_TAG}"
+          buildctl --addr "${BUILDKIT_HOST}" build \
+            --frontend dockerfile.v0 \
+            --local context=. \
+            --local dockerfile=. \
+            --opt build-arg:VERSION="${IMAGE_TAG}" \
+            --output "type=image,name=${IMAGE}:${IMAGE_TAG},push=true"
+          echo "IMAGE_TAG=${IMAGE_TAG}" >> $GITHUB_OUTPUT
+        id: build
+
+      - name: Update infra repo
+        run: |
+          IMAGE_TAG="${{ github.sha }}"
+          # Write SSH key for infra repo
+          mkdir -p ~/.ssh
+          echo "${{ secrets.INFRA_DEPLOY_KEY }}" > ~/.ssh/infra_deploy_key
+          chmod 600 ~/.ssh/infra_deploy_key
+          ssh-keyscan gitea.d-ma.be >> ~/.ssh/known_hosts 2>/dev/null
+
+          # Clone infra repo
+          GIT_SSH_COMMAND="ssh -i ~/.ssh/infra_deploy_key -o IdentitiesOnly=yes" \
+            git clone "${INFRA_REPO}" /tmp/infra-update
+
+          # Patch the image tag
+          cd /tmp/infra-update
+          sed -i "s|gitea.d-ma.be/mathias/supervisor:.*|gitea.d-ma.be/mathias/supervisor:${IMAGE_TAG}|" \
+            "apps/${SERVICE}/deployment.yaml"
+
+          # Commit and push
+          git config user.email "cd-bot@d-ma.be"
+          git config user.name "CD Bot"
+          git add "apps/${SERVICE}/deployment.yaml"
+          git commit -m "chore(deploy): ${SERVICE} → ${IMAGE_TAG}"
+          GIT_SSH_COMMAND="ssh -i ~/.ssh/infra_deploy_key -o IdentitiesOnly=yes" \
+            git push
+
+          # Clean up
+          rm -rf /tmp/infra-update
+          rm ~/.ssh/infra_deploy_key
+          echo "Infra repo updated: ${SERVICE} → ${IMAGE_TAG}"
+EOF
+```
+
+- [ ] **Step 2: Verify the `needs` job name matches ci.yml**
+
+```bash
+grep "^  [a-z].*:$" .gitea/workflows/ci.yml
+```
+
+The output should show `check:` as the quality-gate job name. The `cd.yml` uses `needs: [check]` — confirm this matches.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add .gitea/workflows/cd.yml
+git commit -m "feat: add CD workflow (buildctl → Gitea registry → infra repo update)"
+```
+
+---
+
+## Task 9: End-to-end smoke test
+
+Trigger the full pipeline and verify each stage.
+
+- [ ] **Step 1: Push to main to trigger CI + CD**
+
+```bash
+git push origin main
+```
+
+- [ ] **Step 2: Monitor CI job in Gitea**
+
+Open `https://gitea.d-ma.be/mathias/supervisor/actions` — wait for the `ci` workflow `check` job to pass.
+
+- [ ] **Step 3: Monitor CD job**
+
+In the same actions view, the `cd` workflow should start after `ci` passes. Check the `Build and push image` step output for:
+
+```
+Building gitea.d-ma.be/mathias/supervisor:<sha>
+```
+
+And the `Update infra repo` step for:
+
+```
+Infra repo updated: supervisor → <sha>
+```
+
+- [ ] **Step 4: Verify image in Gitea registry**
+
+```
+https://gitea.d-ma.be/mathias/supervisor/packages
+```
+
+Should show a new tag matching the commit sha.
+
+- [ ] **Step 5: Verify infra repo commit**
+
+```bash
+git clone git@gitea.d-ma.be:mathias/infra.git /tmp/infra-verify
+cd /tmp/infra-verify
+git log --oneline -3
+```
+
+Expected: most recent commit message is `chore(deploy): supervisor → <sha>`.
+
+```bash
+grep "image:" apps/supervisor/deployment.yaml
+```
+
+Expected: `image: gitea.d-ma.be/mathias/supervisor:<sha>`
+
+- [ ] **Step 6: Verify Flux reconciles**
+
+```bash
+flux get kustomizations
+```
+
+Expected: `flux-system` shows `Ready True` and `Applied revision: main/<infra-sha>`.
+
+```bash
+kubectl get pods -n supervisor
+```
+
+Expected: supervisor pod is `Running` with the new image sha.
+
+- [ ] **Step 7: Verify pod started correctly**
+
+```bash
+kubectl logs -n supervisor deployment/supervisor --tail=20
+```
+
+Expected: supervisor startup logs (MCP server listening on port 3200, no errors).
+
+- [ ] **Step 8: Clean up verify clone**
+
+```bash
+rm -rf /tmp/infra-verify
+```
+
+---
+
+## Task 10: Post-deploy — registry retention policy [gitea-ui]
+
+Prevent the Gitea container registry from filling up by setting a tag retention policy.
+
+- [ ] **Step 1: Set tag retention in Gitea**
+
+In Gitea UI: `https://gitea.d-ma.be/mathias/supervisor` → Settings → Packages → Container Registry.
+
+Set: Keep last **20** tags per image name.
+
+If Gitea does not expose a UI retention policy, note this for manual cleanup and open a task to automate it (e.g., a weekly Actions job that calls `docker image prune` via the Gitea API).
+
+- [ ] **Step 2: Verify existing test tags are cleaned up**
+
+Manually delete any test tags pushed during Task 3 if not already done.
+
+---
+
+## Self-review checklist (for plan author — not a task)
+
+- [x] **Spec coverage:** BuildKit systemd ✓, cd.yml ✓, Flux SOPS ✓, infra repo structure ✓, imagePullSecret ✓, app secrets ✓, Gitea org secrets ✓, error handling (implicit in workflow failures) ✓, registry retention ✓, smoke test ✓
+- [x] **Placeholders:** `REPLACE_WITH_YOUR_PUBLIC_KEY` and `REPLACE_WITH_REAL_KEY` are intentional — real values come from user's secrets; marked clearly
+- [x] **Type consistency:** No shared types across tasks (infra-only plan)
+- [x] **Known gaps:** `needs: [check]` assumes ci.yml job name is `check` — verified in Task 8 Step 2. The `sed` image tag patch assumes no other image line in deployment.yaml — the deployment template only has one `image:` line.

docs/superpowers/specs/2026-04-20-cd-pipeline-design.md

@@ -0,0 +1,218 @@
+# CD Pipeline Design
+
+**Date:** 2026-04-20  
+**Status:** Approved for implementation
+
+## Problem statement
+
+The supervisor (and future services on the koala k3s cluster) have no automated deployment path after CI passes. Images are not built, the cluster is updated manually, and there is no audit trail for what is running where.
+
+## Goal
+
+After a push to `main` passes CI, automatically build a container image, push it to the Gitea registry, and update the cluster via GitOps — with a design that scales to many repos and services without per-repo kubeconfig or secret sprawl.
+
+## Success criteria
+
+- [ ] Successful `main` push triggers image build and push to `gitea.d-ma.be/<org>/<repo>:<git-sha>`
+- [ ] Infra repo receives a commit updating the image tag for the deployed service
+- [ ] Flux reconciles within 60s of the infra repo commit; pod runs the new image
+- [ ] Rollback = one commit to infra repo reverting the tag
+- [ ] Secrets (app secrets, registry pull) are SOPS-encrypted in infra repo; no manual `kubectl create secret`
+- [ ] Adding a new service requires only: adding `apps/<service>/` to infra repo + `cd.yml` to the app repo
+- [ ] Zero changes to the k3s cluster networking or runner configuration
+
+## Constraints
+
+- Gitea Actions self-hosted runner runs as a **systemd host process** on koala — not a k8s pod; cannot use cluster DNS
+- k3s uses containerd; no Docker daemon, no nerdctl on koala
+- Flux is already running (core controllers only); image-reflector/image-automation are NOT installed and will NOT be added
+- SOPS + age is the secret management standard; no plaintext Secrets in git
+- All org-level Gitea secrets are shared across repos — minimize the set
+
+## Out of scope
+
+- Multi-cluster promotion (koala only for now; infra repo structure supports adding clusters later)
+- Automated rollback on health check failure (manual rollback via infra repo commit)
+- Build caching beyond BuildKit's local disk cache
+- PR preview environments
+
+---
+
+## Architecture
+
+```
+App repo (supervisor, n8n, etc.)
+    ↓  push to main
+Gitea Actions — ci.yml (lint + test)
+    ↓  passes
+Gitea Actions — cd.yml
+    ├─ 1. buildctl → BuildKit (unix socket on koala host)
+    │         → pushes gitea.d-ma.be/<org>/<repo>:<git-sha>
+    ├─ 2. Clone infra repo (SSH deploy key)
+    │         → patch apps/<service>/deployment.yaml IMAGE_TAG → <git-sha>
+    │         → git commit + push
+    └─ done
+
+gitea.d-ma.be/mathias/infra (Flux source)
+    ↓  Flux source-controller detects new commit (30s interval)
+kustomize-controller
+    └─ applies apps/<service>/kustomization.yaml → k3s namespace
+         ↓
+       pod runs new image (pulls from gitea.d-ma.be with imagePullSecret)
+```
+
+---
+
+## Components
+
+### 1. BuildKit — systemd service on koala
+
+BuildKit runs as a rootless systemd service on the koala host, identical to the Gitea runner pattern already in use.
+
+- Socket: `unix:///run/user/<uid>/buildkit/buildkitd.sock` (rootless) or `/run/buildkit/buildkitd.sock` (root)
+- Cache: local disk at default BuildKit cache path — persists across builds
+- Access: `buildctl --addr unix:///run/buildkit/buildkitd.sock` from the runner process (same host, same user)
+- No k3s involvement for builds
+
+### 2. Gitea Actions — `cd.yml`
+
+Separate workflow file; triggers on `main` push after `ci.yml` succeeds.
+
+```yaml
+name: cd
+on:
+  push:
+    branches: [main]
+
+jobs:
+  deploy:
+    needs: [ci]           # or workflow_run trigger — see implementation plan
+    runs-on: [self-hosted, koala]
+    env:
+      IMAGE: gitea.d-ma.be/${{ github.repository }}:${{ github.sha }}
+    steps:
+      - uses: actions/checkout@v4
+      - name: Build and push
+        run: |
+          buildctl --addr unix:///run/buildkit/buildkitd.sock \
+            build \
+            --frontend dockerfile.v0 \
+            --local context=. \
+            --local dockerfile=. \
+            --output type=image,name=$IMAGE,push=true
+        env:
+          BUILDKIT_HOST: unix:///run/buildkit/buildkitd.sock
+      - name: Update infra repo
+        run: |
+          git clone git@gitea.d-ma.be:mathias/infra.git /tmp/infra
+          cd /tmp/infra
+          sed -i "s|IMAGE_TAG|${{ github.sha }}|g" apps/${{ env.SERVICE_NAME }}/deployment.yaml
+          git config user.email "cd-bot@d-ma.be"
+          git config user.name "CD Bot"
+          git add apps/${{ env.SERVICE_NAME }}/deployment.yaml
+          git commit -m "chore(deploy): ${{ env.SERVICE_NAME }} → ${{ github.sha }}"
+          git push
+        env:
+          GIT_SSH_COMMAND: ssh -i /tmp/infra-deploy-key -o StrictHostKeyChecking=no
+```
+
+`SERVICE_NAME` is set per-repo (either hardcoded in `cd.yml` or derived from the repo name).
+
+### 3. Org-level Gitea secrets
+
+Three secrets, set once, inherited by all repos:
+
+| Secret | Purpose |
+|--------|---------|
+| `BUILDKIT_REGISTRY_AUTH` | credentials for pushing to `gitea.d-ma.be` (buildctl `--opt` or `~/.docker/config.json`) |
+| `INFRA_DEPLOY_KEY` | SSH private key with write access to `gitea.d-ma.be/mathias/infra` |
+| `KUBECONFIG_KOALA` | (optional) kubeconfig for manual `kubectl` steps if ever needed; scoped ServiceAccount |
+
+### 4. Infra repo structure
+
+```
+gitea.d-ma.be/mathias/infra
+├── clusters/
+│   └── koala/
+│       └── kustomization.yaml    # points at ../../apps/*/
+├── apps/
+│   ├── supervisor/
+│   │   ├── namespace.yaml
+│   │   ├── deployment.yaml       # image: gitea.d-ma.be/mathias/supervisor:IMAGE_TAG
+│   │   ├── service.yaml
+│   │   ├── secrets.enc.yaml      # SOPS-encrypted app secrets (ANTHROPIC_API_KEY, etc.)
+│   │   └── kustomization.yaml
+│   ├── n8n/
+│   │   └── ...
+│   └── imagepullsecret/
+│       └── secret.enc.yaml       # SOPS-encrypted imagePullSecret for gitea.d-ma.be
+└── flux-system/                  # existing Flux bootstrap manifests
+```
+
+Adding a new service = add `apps/<service>/` directory. The `clusters/koala/kustomization.yaml` uses a glob or explicit list.
+
+### 5. SOPS + age for Flux
+
+Flux decrypts SOPS-encrypted files at apply time using an age key stored as a k8s Secret in the `flux-system` namespace. Setup:
+
+1. Generate age keypair: `age-keygen`
+2. Store private key: `kubectl create secret generic sops-age --from-file=age.agekey -n flux-system`
+3. Configure Flux Kustomization with `decryption.provider: sops`
+4. Encrypt secrets before committing: `sops --encrypt --age <pubkey> secret.yaml > secret.enc.yaml`
+
+App secrets (e.g., `ANTHROPIC_API_KEY`) and the registry pull secret live as encrypted files in `apps/<service>/` and `apps/imagepullsecret/` respectively.
+
+### 6. Image pull secret
+
+Each app namespace needs a `kubernetes.io/dockerconfigjson` Secret to pull from `gitea.d-ma.be`. This Secret is SOPS-encrypted in `apps/imagepullsecret/` and applied to each app namespace via Kustomize `namespace` field or a shared Kustomize component.
+
+---
+
+## Data flow: supervisor deploy
+
+1. Push to `supervisor` main → CI passes (lint/test/vet)
+2. CD job builds image: `gitea.d-ma.be/mathias/supervisor:abc1234`
+3. CD job clones infra repo, patches `apps/supervisor/deployment.yaml`, commits
+4. Flux source-controller detects infra commit within 30s
+5. kustomize-controller applies `apps/supervisor/kustomization.yaml`
+6. Flux decrypts `secrets.enc.yaml` → k8s Secret in `supervisor` namespace
+7. k3s pulls `gitea.d-ma.be/mathias/supervisor:abc1234` using imagePullSecret
+8. Pod starts with new image; previous pod terminates
+
+Rollback: `git revert <tag-commit>` in infra repo → Flux reconciles → old image deployed.
+
+---
+
+## Error handling
+
+| Scenario | Behaviour |
+|----------|-----------|
+| CI fails | `cd.yml` does not run (`needs: ci` gate) |
+| BuildKit unreachable | `buildctl` exits non-zero → workflow fails; infra repo untouched |
+| Image push fails | Workflow fails; infra repo untouched; cluster unchanged |
+| Infra repo push conflict | Retry once with rebase; fail and alert if still conflicting |
+| Flux reconcile error | Notification-controller fires alert; pods stay on previous image |
+| Pod image pull fails | `ImagePullBackOff`; Flux reports degraded Kustomization |
+| SOPS decrypt fails | Kustomization fails; Flux reports error; no partial apply |
+
+---
+
+## Testing approach
+
+1. **BuildKit smoke test** — `buildctl build` with a trivial one-line Dockerfile; verify image appears in Gitea registry
+2. **cd.yml dry run** — trigger manually on a test branch; verify infra repo commit contains correct sha
+3. **Flux reconcile test** — push infra commit; verify `flux get kustomizations` shows `Ready` and pod runs new image sha
+4. **Pull secret test** — delete pod, verify it restarts and pulls from Gitea registry without `ImagePullBackOff`
+5. **SOPS round-trip test** — encrypt a dummy secret, push to infra repo, verify Flux decrypts and `kubectl get secret` shows correct data
+
+---
+
+## Risks
+
+| Risk | Mitigation |
+|------|------------|
+| BuildKit socket path varies by user/rootless mode | Confirm path during setup; hardcode in `cd.yml` |
+| Infra repo concurrent pushes (multiple repos deploying simultaneously) | Git rebase retry handles this; unlikely at current scale |
+| age private key lost | Back up to SOPS-accessible location; document recovery procedure |
+| Registry storage fills up | Set Gitea registry tag retention policy (keep last 20 per repo) |
+| Gitea deploy key compromised | Rotate via Gitea UI; single key for infra repo only |

ingestion/internal/api/handler.go

@@ -79,7 +79,7 @@ func (h *Handler) Write(w http.ResponseWriter, r *http.Request) {
 		filename = fmt.Sprintf("%s-auto.md", time.Now().UTC().Format("2006-01-02-150405"))
 	}
 
-	rawDir := filepath.Join(h.brainDir, "raw")
+	rawDir := filepath.Join(h.brainDir, "knowledge")
 	if err := os.MkdirAll(rawDir, 0o755); err != nil {
 		http.Error(w, "failed to create raw dir", http.StatusInternalServerError)
 		return

ingestion/internal/api/handler_test.go

@@ -20,10 +20,9 @@ import (
 func setup(t *testing.T) (string, *api.Handler) {
 	t.Helper()
 	dir := t.TempDir()
-	require.NoError(t, os.MkdirAll(filepath.Join(dir, "wiki", "concepts"), 0o755))
+	require.NoError(t, os.MkdirAll(filepath.Join(dir, "knowledge"), 0o755))
-	require.NoError(t, os.MkdirAll(filepath.Join(dir, "raw"), 0o755))
 	require.NoError(t, os.WriteFile(
-		filepath.Join(dir, "wiki", "concepts", "tdd.md"),
+		filepath.Join(dir, "knowledge", "tdd.md"),
 		[]byte("---\ntitle: TDD\ndomain: software\n---\n\nTest-driven development is a discipline.\n"),
 		0o644,
 	))
@@ -46,7 +45,7 @@ func TestQuery_ReturnsResults(t *testing.T) {
 	assert.NotEmpty(t, results)
 }
 
-func TestWrite_CreatesRawFile(t *testing.T) {
+func TestWrite_CreatesKnowledgeFile(t *testing.T) {
 	dir, h := setup(t)
 	body, _ := json.Marshal(map[string]any{
 		"content":  "# Test note\n\nSome content.",
@@ -62,8 +61,7 @@ func TestWrite_CreatesRawFile(t *testing.T) {
 	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &resp))
 	assert.NotEmpty(t, resp["path"])
 
-	written := filepath.Join(dir, "raw", "test-note.md")
+	content, err := os.ReadFile(filepath.Join(dir, "knowledge", "test-note.md"))
-	content, err := os.ReadFile(written)
 	require.NoError(t, err)
 	assert.Contains(t, string(content), "Some content.")
 }
@@ -93,7 +91,7 @@ func TestWrite_IncludesFrontmatterWhenTypeProvided(t *testing.T) {
 	h.Write(rec, req)
 
 	assert.Equal(t, http.StatusOK, rec.Code)
-	content, err := os.ReadFile(filepath.Join(dir, "raw", "typed-note.md"))
+	content, err := os.ReadFile(filepath.Join(dir, "knowledge", "typed-note.md"))
 	require.NoError(t, err)
 	assert.Contains(t, string(content), "type: concept")
 	assert.Contains(t, string(content), "domain: software")
@@ -109,7 +107,8 @@ func TestWrite_GeneratesFilenameIfAbsent(t *testing.T) {
 	h.Write(rec, req)
 
 	assert.Equal(t, http.StatusOK, rec.Code)
-	entries, _ := os.ReadDir(filepath.Join(dir, "raw"))
+	entries, _ := os.ReadDir(filepath.Join(dir, "knowledge"))
-	assert.Len(t, entries, 1)
+	// +1 because setup already wrote tdd.md
-	assert.True(t, strings.HasSuffix(entries[0].Name(), ".md"))
+	assert.Len(t, entries, 2)
+	assert.True(t, strings.HasSuffix(entries[1].Name(), ".md"))
 }

ingestion/internal/search/search.go

@@ -33,7 +33,7 @@ func Query(brainDir, query string, limit int) ([]Result, error) {
 
 	var results []Result
 
-	err := filepath.WalkDir(filepath.Join(brainDir, "wiki"), func(path string, d os.DirEntry, err error) error {
+	err := filepath.WalkDir(filepath.Join(brainDir, "knowledge"), func(path string, d os.DirEntry, err error) error {
 		if err != nil {
 			slog.Warn("search: skipping path", "path", path, "err", err)
 			return nil

ingestion/internal/search/search_test.go

@@ -14,17 +14,15 @@ import (
 
 func TestSearch_ReturnsMatchingPages(t *testing.T) {
 	dir := t.TempDir()
-	require.NoError(t, os.MkdirAll(filepath.Join(dir, "wiki", "concepts"), 0o755))
+	require.NoError(t, os.MkdirAll(filepath.Join(dir, "knowledge"), 0o755))
 
-	// Write a concept page mentioning "retry"
 	require.NoError(t, os.WriteFile(
-		filepath.Join(dir, "wiki", "concepts", "retry-logic.md"),
+		filepath.Join(dir, "knowledge", "retry-logic.md"),
 		[]byte("---\ntitle: Retry Logic\ndomain: software\n---\n\nRetry logic handles transient failures by re-attempting operations.\n"),
 		0o644,
 	))
-	// Write an unrelated page
 	require.NoError(t, os.WriteFile(
-		filepath.Join(dir, "wiki", "concepts", "database.md"),
+		filepath.Join(dir, "knowledge", "database.md"),
 		[]byte("---\ntitle: Database\ndomain: software\n---\n\nA database stores structured data.\n"),
 		0o644,
 	))
@@ -32,7 +30,7 @@ func TestSearch_ReturnsMatchingPages(t *testing.T) {
 	results, err := search.Query(dir, "retry transient", 5)
 	require.NoError(t, err)
 	require.Len(t, results, 1)
-	assert.Equal(t, "wiki/concepts/retry-logic.md", results[0].Path)
+	assert.Equal(t, "knowledge/retry-logic.md", results[0].Path)
 	assert.Equal(t, "Retry Logic", results[0].Title)
 	assert.Greater(t, results[0].Score, 0)
 	assert.Contains(t, results[0].Excerpt, "Retry")
@@ -40,10 +38,10 @@ func TestSearch_ReturnsMatchingPages(t *testing.T) {
 
 func TestSearch_RespectsLimit(t *testing.T) {
 	dir := t.TempDir()
-	require.NoError(t, os.MkdirAll(filepath.Join(dir, "wiki", "concepts"), 0o755))
+	require.NoError(t, os.MkdirAll(filepath.Join(dir, "knowledge"), 0o755))
 	for i := 0; i < 5; i++ {
 		require.NoError(t, os.WriteFile(
-			filepath.Join(dir, "wiki", "concepts", fmt.Sprintf("page-%d.md", i)),
+			filepath.Join(dir, "knowledge", fmt.Sprintf("page-%d.md", i)),
 			[]byte(fmt.Sprintf("---\ntitle: Page %d\n---\n\nThis page mentions retry.\n", i)),
 			0o644,
 		))

internal/brain/client.go

@@ -0,0 +1,76 @@
+// internal/brain/client.go
+// Package brain provides a lightweight client for querying the ingestion server.
+// Skill handlers call Query before spawning workers to inject relevant knowledge
+// from the brain into the task prompt. Errors are suppressed — the brain is
+// optional context; its absence must never block a skill invocation.
+package brain
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"log/slog"
+	"net/http"
+	"strings"
+)
+
+type queryResult struct {
+	Path    string `json:"path"`
+	Title   string `json:"title"`
+	Excerpt string `json:"excerpt"`
+	Score   int    `json:"score"`
+}
+
+// Query calls the ingestion server and returns relevant knowledge as a
+// formatted string ready to prepend to a worker task prompt.
+// Returns empty string (no error) when baseURL or query is empty,
+// when the brain is unreachable, or when no results are found.
+func Query(ctx context.Context, baseURL, query string, limit int) (string, error) {
+	if baseURL == "" || strings.TrimSpace(query) == "" {
+		return "", nil
+	}
+	if limit <= 0 {
+		limit = 3
+	}
+
+	body, _ := json.Marshal(map[string]any{"query": query, "limit": limit})
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, baseURL+"/query", bytes.NewReader(body))
+	if err != nil {
+		slog.Warn("brain: build request failed", "err", err)
+		return "", nil
+	}
+	req.Header.Set("Content-Type", "application/json")
+
+	resp, err := http.DefaultClient.Do(req)
+	if err != nil {
+		slog.Warn("brain: ingestion server unreachable", "err", err)
+		return "", nil
+	}
+	defer func() { _ = resp.Body.Close() }()
+
+	if resp.StatusCode != http.StatusOK {
+		slog.Warn("brain: ingestion server returned non-OK", "status", resp.StatusCode)
+		return "", nil
+	}
+
+	out, _ := io.ReadAll(resp.Body)
+	var result struct {
+		Results []queryResult `json:"results"`
+	}
+	if err := json.Unmarshal(out, &result); err != nil || len(result.Results) == 0 {
+		return "", nil
+	}
+
+	var b strings.Builder
+	b.WriteString("## Relevant knowledge\n\n")
+	for _, r := range result.Results {
+		title := r.Title
+		if title == "" {
+			title = r.Path
+		}
+		fmt.Fprintf(&b, "### %s\n%s\n\n", title, r.Excerpt)
+	}
+	return b.String(), nil
+}

internal/brain/client_test.go

@@ -0,0 +1,67 @@
+package brain_test
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/mathiasbq/supervisor/internal/brain"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestQueryEmptyBaseURL(t *testing.T) {
+	result, err := brain.Query(context.Background(), "", "tdd patterns", 3)
+	require.NoError(t, err)
+	assert.Empty(t, result)
+}
+
+func TestQueryEmptyQuery(t *testing.T) {
+	result, err := brain.Query(context.Background(), "http://localhost:9999", "", 3)
+	require.NoError(t, err)
+	assert.Empty(t, result)
+}
+
+func TestQueryFormatsResults(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		assert.Equal(t, "/query", r.URL.Path)
+		var req map[string]any
+		require.NoError(t, json.NewDecoder(r.Body).Decode(&req))
+		assert.Equal(t, "tdd patterns", req["query"])
+
+		json.NewEncoder(w).Encode(map[string]any{ //nolint:errcheck
+			"results": []map[string]any{
+				{"path": "knowledge/tdd.md", "title": "TDD Guide", "excerpt": "Always write tests first.", "score": 5},
+				{"path": "knowledge/go.md", "title": "Go Conventions", "excerpt": "Use table-driven tests.", "score": 3},
+			},
+		})
+	}))
+	defer srv.Close()
+
+	result, err := brain.Query(context.Background(), srv.URL, "tdd patterns", 3)
+	require.NoError(t, err)
+	assert.Contains(t, result, "## Relevant knowledge")
+	assert.Contains(t, result, "TDD Guide")
+	assert.Contains(t, result, "Always write tests first.")
+	assert.Contains(t, result, "Go Conventions")
+}
+
+func TestQueryEmptyResults(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		json.NewEncoder(w).Encode(map[string]any{"results": []any{}}) //nolint:errcheck
+	}))
+	defer srv.Close()
+
+	result, err := brain.Query(context.Background(), srv.URL, "obscure query", 3)
+	require.NoError(t, err)
+	assert.Empty(t, result)
+}
+
+func TestQueryUnavailableServerReturnsEmpty(t *testing.T) {
+	// Brain unavailable — should degrade gracefully, no error
+	result, err := brain.Query(context.Background(), "http://127.0.0.1:19999", "query", 3)
+	require.NoError(t, err)
+	assert.Empty(t, result)
+}

internal/exec/result.go

@@ -17,6 +17,7 @@ type Result struct {
 	Verified     bool            `json:"verified"`           // based on exit code, never self-report
 	ModelUsed    string          `json:"model_used"`         // model name or "self"
 	Message      string          `json:"message"`            // one sentence summary
+	Attempts     []AttemptRecord `json:"attempts,omitempty"` // populated by orchestrator, not Claude
 }
 
 var validStatuses = map[string]bool{"pass": true, "fail": true, "error": true}

internal/session/attempts.go

@@ -0,0 +1,26 @@
+// internal/session/attempts.go
+package session
+
+import iexec "github.com/mathiasbq/supervisor/internal/exec"
+
+// AttemptsFrom converts exec.AttemptRecord slice to session.Attempt slice
+// for writing into a session JSONL entry.
+func AttemptsFrom(records []iexec.AttemptRecord) []Attempt {
+	if len(records) == 0 {
+		return nil
+	}
+	out := make([]Attempt, len(records))
+	for i, r := range records {
+		out[i] = Attempt{
+			Attempt:    i + 1,
+			Model:      r.Model,
+			Tier:       r.Tier,
+			DurationMs: r.DurationMs,
+			WarmStart:  r.WarmStart,
+			Verdict:    r.Verdict,
+			Feedback:   r.Feedback,
+			Verified:   r.Verdict == "accept",
+		}
+	}
+	return out
+}

internal/session/attempts_test.go

@@ -0,0 +1,37 @@
+package session_test
+
+import (
+	"testing"
+
+	"github.com/mathiasbq/supervisor/internal/exec"
+	"github.com/mathiasbq/supervisor/internal/session"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestAttemptsFromEmpty(t *testing.T) {
+	result := session.AttemptsFrom(nil)
+	assert.Empty(t, result)
+}
+
+func TestAttemptsFromSetsIndex(t *testing.T) {
+	records := []exec.AttemptRecord{
+		{Model: "ollama/phi4", Tier: "local", DurationMs: 1200, WarmStart: true, Verdict: "escalate", Feedback: "too vague"},
+		{Model: "claude-sonnet-4-6", Tier: "subagent", DurationMs: 3400, WarmStart: false, Verdict: "accept"},
+	}
+	result := session.AttemptsFrom(records)
+	require.Len(t, result, 2)
+
+	assert.Equal(t, 1, result[0].Attempt)
+	assert.Equal(t, "ollama/phi4", result[0].Model)
+	assert.Equal(t, "local", result[0].Tier)
+	assert.Equal(t, int64(1200), result[0].DurationMs)
+	assert.True(t, result[0].WarmStart)
+	assert.Equal(t, "escalate", result[0].Verdict)
+	assert.Equal(t, "too vague", result[0].Feedback)
+	assert.False(t, result[0].Verified)
+
+	assert.Equal(t, 2, result[1].Attempt)
+	assert.Equal(t, "claude-sonnet-4-6", result[1].Model)
+	assert.True(t, result[1].Verified)
+}

internal/session/history.go

@@ -36,3 +36,21 @@ func FormatHistory(entries []Entry, excludePhase string) string {
 	}
 	return b.String()
 }
+
+// PrependHistory reads the session log for sessionID and prepends a formatted
+// history block to task. Returns task unchanged if sessionID or sessionsDir is
+// empty, or if no prior entries exist.
+func PrependHistory(sessionsDir, sessionID, currentPhase, task string) string {
+	if sessionID == "" || sessionsDir == "" {
+		return task
+	}
+	entries, err := Read(sessionsDir, sessionID)
+	if err != nil || len(entries) == 0 {
+		return task
+	}
+	history := FormatHistory(entries, currentPhase)
+	if history == "" {
+		return task
+	}
+	return history + "\n---\n\n" + task
+}

internal/session/history_test.go

@@ -2,11 +2,13 @@
 package session_test
 
 import (
+	"strings"
 	"testing"
 	"time"
 
 	"github.com/mathiasbq/supervisor/internal/session"
 	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
 )
 
 func TestFormatHistoryEmpty(t *testing.T) {
@@ -39,3 +41,45 @@ func TestFormatHistoryExcludesCurrentPhase(t *testing.T) {
 	assert.Contains(t, result, "red done")
 	assert.NotContains(t, result, "green done")
 }
+
+func TestPrependHistoryNoSessionID(t *testing.T) {
+	result := session.PrependHistory("", "", "review", "do the task")
+	assert.Equal(t, "do the task", result)
+}
+
+func TestPrependHistoryNoLog(t *testing.T) {
+	dir := t.TempDir()
+	result := session.PrependHistory(dir, "sess-abc", "review", "do the task")
+	assert.Equal(t, "do the task", result)
+}
+
+func TestPrependHistoryPrependsHistory(t *testing.T) {
+	dir := t.TempDir()
+	entry := session.Entry{
+		SessionID: "sess-abc", Skill: "tdd", Phase: "red",
+		FinalStatus: "pass", Message: "wrote test",
+		Timestamp: time.Now(),
+	}
+	require.NoError(t, session.Append(dir, "sess-abc", entry))
+
+	result := session.PrependHistory(dir, "sess-abc", "review", "do the task")
+	assert.Contains(t, result, "## Session history")
+	assert.Contains(t, result, "wrote test")
+	assert.True(t, strings.HasSuffix(result, "do the task"))
+}
+
+func TestPrependHistoryExcludesCurrentPhase(t *testing.T) {
+	dir := t.TempDir()
+	require.NoError(t, session.Append(dir, "sess-abc", session.Entry{
+		SessionID: "sess-abc", Skill: "tdd", Phase: "red",
+		FinalStatus: "pass", Message: "red done", Timestamp: time.Now(),
+	}))
+	require.NoError(t, session.Append(dir, "sess-abc", session.Entry{
+		SessionID: "sess-abc", Skill: "tdd", Phase: "green",
+		FinalStatus: "pass", Message: "green done", Timestamp: time.Now(),
+	}))
+
+	result := session.PrependHistory(dir, "sess-abc", "green", "do the task")
+	assert.Contains(t, result, "red done")
+	assert.NotContains(t, result, "green done")
+}

internal/skills/debug/handlers.go

@@ -5,7 +5,9 @@ import (
 	"context"
 	"encoding/json"
 	"fmt"
+	"time"
 
+	"github.com/mathiasbq/supervisor/internal/brain"
 	iexec "github.com/mathiasbq/supervisor/internal/exec"
 	"github.com/mathiasbq/supervisor/internal/session"
 )
@@ -39,15 +41,21 @@ func (s *Skill) Handle(ctx context.Context, tool string, args json.RawMessage) (
 		model = s.cfg.DefaultModel
 	}
 
+	brainCtx, _ := brain.Query(ctx, s.cfg.IngestBaseURL, a.Error+" "+a.Context, 3)
+
 	task := fmt.Sprintf(
 		"phase: debug\nproject_root: %s\nerror: %s\ncontext: %s\nmodel: %s",
 		a.ProjectRoot, a.Error, a.Context, model,
 	)
-	task = s.prependHistory(a.SessionID, "debug", task)
+	task = session.PrependHistory(s.cfg.SessionsDir, a.SessionID, "debug", task)
+	if brainCtx != "" {
+		task = brainCtx + "\n---\n\n" + task
+	}
 
 	if s.cfg.ExecutorFn == nil {
 		return nil, fmt.Errorf("no executor configured")
 	}
+	t0 := time.Now()
 	result, err := s.cfg.ExecutorFn(ctx, iexec.Request{
 		SkillPrompt: s.cfg.SkillPrompt,
 		TaskPrompt:  task,
@@ -57,24 +65,25 @@ func (s *Skill) Handle(ctx context.Context, tool string, args json.RawMessage) (
 	if err != nil {
 		return nil, err
 	}
+
+	if a.SessionID != "" && s.cfg.SessionsDir != "" {
+		_ = session.Append(s.cfg.SessionsDir, a.SessionID, session.Entry{
+			SessionID:   a.SessionID,
+			Timestamp:   time.Now(),
+			Skill:       "debug",
+			Phase:       "debug",
+			ProjectRoot: a.ProjectRoot,
+			Attempts:    session.AttemptsFrom(result.Attempts),
+			FinalStatus: result.Status,
+			ModelUsed:   result.ModelUsed,
+			DurationMs:  time.Since(t0).Milliseconds(),
+			Message:     result.Message,
+		})
+	}
+
 	b, err := json.Marshal(result)
 	if err != nil {
 		return nil, fmt.Errorf("marshal result: %w", err)
 	}
 	return b, nil
 }
-
-func (s *Skill) prependHistory(sessionID, currentPhase, task string) string {
-	if sessionID == "" || s.cfg.SessionsDir == "" {
-		return task
-	}
-	entries, err := session.Read(s.cfg.SessionsDir, sessionID)
-	if err != nil || len(entries) == 0 {
-		return task
-	}
-	history := session.FormatHistory(entries, currentPhase)
-	if history == "" {
-		return task
-	}
-	return history + "\n---\n\n" + task
-}

internal/skills/debug/skill.go

@@ -18,6 +18,7 @@ type Config struct {
 	DefaultModel  string
 	ExecutorFn    ExecutorFn
 	SessionsDir   string
+	IngestBaseURL string // optional: base URL of ingestion server for brain context
 }
 
 // Skill implements the debug MCP tool.

internal/skills/retrospective/handlers.go

@@ -5,6 +5,7 @@ import (
 	"context"
 	"encoding/json"
 	"fmt"
+	"time"
 
 	iexec "github.com/mathiasbq/supervisor/internal/exec"
 	"github.com/mathiasbq/supervisor/internal/session"
@@ -52,6 +53,7 @@ func (s *Skill) Handle(ctx context.Context, tool string, args json.RawMessage) (
 	if s.cfg.ExecutorFn == nil {
 		return nil, fmt.Errorf("no executor configured")
 	}
+	t0 := time.Now()
 	result, err := s.cfg.ExecutorFn(ctx, iexec.Request{
 		SkillPrompt: s.cfg.SkillPrompt,
 		TaskPrompt:  taskPrompt,
@@ -62,6 +64,18 @@ func (s *Skill) Handle(ctx context.Context, tool string, args json.RawMessage) (
 		return nil, fmt.Errorf("retrospective worker: %w", err)
 	}
 
+	_ = session.Append(s.cfg.SessionsDir, a.SessionID, session.Entry{
+		SessionID:   a.SessionID,
+		Timestamp:   time.Now(),
+		Skill:       "retrospective",
+		Phase:       "retrospective",
+		Attempts:    session.AttemptsFrom(result.Attempts),
+		FinalStatus: result.Status,
+		ModelUsed:   result.ModelUsed,
+		DurationMs:  time.Since(t0).Milliseconds(),
+		Message:     result.Message,
+	})
+
 	b, err := json.Marshal(result)
 	if err != nil {
 		return nil, fmt.Errorf("marshal result: %w", err)

internal/skills/review/handlers.go

@@ -6,7 +6,9 @@ import (
 	"encoding/json"
 	"fmt"
 	"strings"
+	"time"
 
+	"github.com/mathiasbq/supervisor/internal/brain"
 	iexec "github.com/mathiasbq/supervisor/internal/exec"
 	"github.com/mathiasbq/supervisor/internal/session"
 )
@@ -40,15 +42,21 @@ func (s *Skill) Handle(ctx context.Context, tool string, args json.RawMessage) (
 		model = s.cfg.DefaultModel
 	}
 
+	brainCtx, _ := brain.Query(ctx, s.cfg.IngestBaseURL, strings.Join(a.Files, " ")+" "+a.Context, 3)
+
 	task := fmt.Sprintf(
 		"phase: review\nproject_root: %s\nfiles: %s\ncontext: %s\nmodel: %s",
 		a.ProjectRoot, strings.Join(a.Files, ", "), a.Context, model,
 	)
-	task = s.prependHistory(a.SessionID, "review", task)
+	task = session.PrependHistory(s.cfg.SessionsDir, a.SessionID, "review", task)
+	if brainCtx != "" {
+		task = brainCtx + "\n---\n\n" + task
+	}
 
 	if s.cfg.ExecutorFn == nil {
 		return nil, fmt.Errorf("no executor configured")
 	}
+	t0 := time.Now()
 	result, err := s.cfg.ExecutorFn(ctx, iexec.Request{
 		SkillPrompt: s.cfg.SkillPrompt,
 		TaskPrompt:  task,
@@ -58,24 +66,26 @@ func (s *Skill) Handle(ctx context.Context, tool string, args json.RawMessage) (
 	if err != nil {
 		return nil, err
 	}
+
+	if a.SessionID != "" && s.cfg.SessionsDir != "" {
+		_ = session.Append(s.cfg.SessionsDir, a.SessionID, session.Entry{
+			SessionID:   a.SessionID,
+			Timestamp:   time.Now(),
+			Skill:       "review",
+			Phase:       "review",
+			ProjectRoot: a.ProjectRoot,
+			Attempts:    session.AttemptsFrom(result.Attempts),
+			FinalStatus: result.Status,
+			FilePath:    result.FilePath,
+			ModelUsed:   result.ModelUsed,
+			DurationMs:  time.Since(t0).Milliseconds(),
+			Message:     result.Message,
+		})
+	}
+
 	b, err := json.Marshal(result)
 	if err != nil {
 		return nil, fmt.Errorf("marshal result: %w", err)
 	}
 	return b, nil
 }
-
-func (s *Skill) prependHistory(sessionID, currentPhase, task string) string {
-	if sessionID == "" || s.cfg.SessionsDir == "" {
-		return task
-	}
-	entries, err := session.Read(s.cfg.SessionsDir, sessionID)
-	if err != nil || len(entries) == 0 {
-		return task
-	}
-	history := session.FormatHistory(entries, currentPhase)
-	if history == "" {
-		return task
-	}
-	return history + "\n---\n\n" + task
-}

internal/skills/review/skill.go

@@ -18,6 +18,7 @@ type Config struct {
 	DefaultModel  string
 	ExecutorFn    ExecutorFn
 	SessionsDir   string
+	IngestBaseURL string // optional: base URL of ingestion server for brain context
 }
 
 // Skill implements the review MCP tool.

internal/skills/spec/handlers.go

@@ -5,7 +5,9 @@ import (
 	"context"
 	"encoding/json"
 	"fmt"
+	"time"
 
+	"github.com/mathiasbq/supervisor/internal/brain"
 	iexec "github.com/mathiasbq/supervisor/internal/exec"
 	"github.com/mathiasbq/supervisor/internal/session"
 )
@@ -44,15 +46,21 @@ func (s *Skill) Handle(ctx context.Context, tool string, args json.RawMessage) (
 		model = s.cfg.DefaultModel
 	}
 
+	brainCtx, _ := brain.Query(ctx, s.cfg.IngestBaseURL, a.Requirements+" "+a.Context, 3)
+
 	task := fmt.Sprintf(
 		"phase: spec\nproject_root: %s\nrequirements: %s\noutput_path: %s\ncontext: %s\nmodel: %s",
 		a.ProjectRoot, a.Requirements, outputPath, a.Context, model,
 	)
-	task = s.prependHistory(a.SessionID, "spec", task)
+	task = session.PrependHistory(s.cfg.SessionsDir, a.SessionID, "spec", task)
+	if brainCtx != "" {
+		task = brainCtx + "\n---\n\n" + task
+	}
 
 	if s.cfg.ExecutorFn == nil {
 		return nil, fmt.Errorf("no executor configured")
 	}
+	t0 := time.Now()
 	result, err := s.cfg.ExecutorFn(ctx, iexec.Request{
 		SkillPrompt: s.cfg.SkillPrompt,
 		TaskPrompt:  task,
@@ -62,24 +70,26 @@ func (s *Skill) Handle(ctx context.Context, tool string, args json.RawMessage) (
 	if err != nil {
 		return nil, err
 	}
+
+	if a.SessionID != "" && s.cfg.SessionsDir != "" {
+		_ = session.Append(s.cfg.SessionsDir, a.SessionID, session.Entry{
+			SessionID:   a.SessionID,
+			Timestamp:   time.Now(),
+			Skill:       "spec",
+			Phase:       "spec",
+			ProjectRoot: a.ProjectRoot,
+			Attempts:    session.AttemptsFrom(result.Attempts),
+			FinalStatus: result.Status,
+			FilePath:    result.FilePath,
+			ModelUsed:   result.ModelUsed,
+			DurationMs:  time.Since(t0).Milliseconds(),
+			Message:     result.Message,
+		})
+	}
+
 	b, err := json.Marshal(result)
 	if err != nil {
 		return nil, fmt.Errorf("marshal result: %w", err)
 	}
 	return b, nil
 }
-
-func (s *Skill) prependHistory(sessionID, currentPhase, task string) string {
-	if sessionID == "" || s.cfg.SessionsDir == "" {
-		return task
-	}
-	entries, err := session.Read(s.cfg.SessionsDir, sessionID)
-	if err != nil || len(entries) == 0 {
-		return task
-	}
-	history := session.FormatHistory(entries, currentPhase)
-	if history == "" {
-		return task
-	}
-	return history + "\n---\n\n" + task
-}

internal/skills/spec/skill.go

@@ -18,6 +18,7 @@ type Config struct {
 	DefaultModel  string
 	ExecutorFn    ExecutorFn
 	SessionsDir   string
+	IngestBaseURL string // optional: base URL of ingestion server for brain context
 }
 
 // Skill implements the spec MCP tool.

internal/skills/tdd/handlers.go

@@ -4,7 +4,9 @@ import (
 	"context"
 	"encoding/json"
 	"fmt"
+	"time"
 
+	"github.com/mathiasbq/supervisor/internal/brain"
 	iexec "github.com/mathiasbq/supervisor/internal/exec"
 	"github.com/mathiasbq/supervisor/internal/session"
 )
@@ -40,10 +42,15 @@ func (s *Skill) handleRed(ctx context.Context, raw json.RawMessage) (json.RawMes
 	if args.Spec == "" {
 		return nil, fmt.Errorf("spec is required")
 	}
+	brainCtx, _ := brain.Query(ctx, s.cfg.IngestBaseURL, args.Spec, 3)
+
 	task := fmt.Sprintf(
 		"phase: red\nproject_root: %s\nspec: %s\nmodel: %s\ntest_cmd: %s",
 		args.ProjectRoot, args.Spec, s.resolveModel(args.Model), args.TestCmd,
 	)
+	if brainCtx != "" {
+		task = brainCtx + "\n---\n\n" + task
+	}
 	return s.execute(ctx, task)
 }
 
@@ -70,8 +77,15 @@ func (s *Skill) handleGreen(ctx context.Context, raw json.RawMessage) (json.RawM
 		"phase: green\nproject_root: %s\ntest_path: %s\nmodel: %s\ntest_cmd: %s",
 		args.ProjectRoot, args.TestPath, s.resolveModel(args.Model), args.TestCmd,
 	)
-	task = s.prependHistory(args.SessionID, "green", task)
+	task = session.PrependHistory(s.cfg.SessionsDir, args.SessionID, "green", task)
-	return s.execute(ctx, task)
+
+	t0 := time.Now()
+	result, err := s.execute(ctx, task)
+	if err != nil {
+		return nil, err
+	}
+	s.logAttempt(args.SessionID, args.ProjectRoot, "tdd", "green", t0, result)
+	return result, nil
 }
 
 type refactorArgs struct {
@@ -101,23 +115,15 @@ func (s *Skill) handleRefactor(ctx context.Context, raw json.RawMessage) (json.R
 		"phase: refactor\nproject_root: %s\ntest_path: %s\nimpl_path: %s\nmodel: %s\ntest_cmd: %s",
 		args.ProjectRoot, args.TestPath, args.ImplPath, s.resolveModel(args.Model), args.TestCmd,
 	)
-	task = s.prependHistory(args.SessionID, "refactor", task)
+	task = session.PrependHistory(s.cfg.SessionsDir, args.SessionID, "refactor", task)
-	return s.execute(ctx, task)
-}
 
-func (s *Skill) prependHistory(sessionID, currentPhase, task string) string {
+	t0 := time.Now()
-	if sessionID == "" || s.cfg.SessionsDir == "" {
+	result, err := s.execute(ctx, task)
-		return task
+	if err != nil {
+		return nil, err
 	}
-	entries, err := session.Read(s.cfg.SessionsDir, sessionID)
+	s.logAttempt(args.SessionID, args.ProjectRoot, "tdd", "refactor", t0, result)
-	if err != nil || len(entries) == 0 {
+	return result, nil
-		return task
-	}
-	history := session.FormatHistory(entries, currentPhase)
-	if history == "" {
-		return task
-	}
-	return history + "\n---\n\n" + task
 }
 
 func (s *Skill) resolveModel(override string) string {
@@ -127,6 +133,7 @@ func (s *Skill) resolveModel(override string) string {
 	return s.cfg.DefaultModel
 }
 
+// execute calls ExecutorFn and returns the marshaled result.
 func (s *Skill) execute(ctx context.Context, task string) (json.RawMessage, error) {
 	if s.cfg.ExecutorFn == nil {
 		return nil, fmt.Errorf("no executor configured")
@@ -141,3 +148,28 @@ func (s *Skill) execute(ctx context.Context, task string) (json.RawMessage, erro
 	}
 	return json.Marshal(result)
 }
+
+// logAttempt writes a session.Entry for a completed phase if session_id is set.
+// raw is the marshaled Result returned by execute; we unmarshal to extract fields.
+func (s *Skill) logAttempt(sessionID, projectRoot, skill, phase string, t0 time.Time, raw json.RawMessage) {
+	if sessionID == "" || s.cfg.SessionsDir == "" {
+		return
+	}
+	var result iexec.Result
+	if err := json.Unmarshal(raw, &result); err != nil {
+		return
+	}
+	_ = session.Append(s.cfg.SessionsDir, sessionID, session.Entry{
+		SessionID:   sessionID,
+		Timestamp:   time.Now(),
+		Skill:       skill,
+		Phase:       phase,
+		ProjectRoot: projectRoot,
+		Attempts:    session.AttemptsFrom(result.Attempts),
+		FinalStatus: result.Status,
+		FilePath:    result.FilePath,
+		ModelUsed:   result.ModelUsed,
+		DurationMs:  time.Since(t0).Milliseconds(),
+		Message:     result.Message,
+	})
+}

internal/skills/tdd/skill.go

@@ -17,6 +17,7 @@ type Config struct {
 	ExecutorFn    ExecutorFn // nil = no executor (tests that don't reach execute())
 	DefaultModel  string
 	SessionsDir   string // optional: path to brain/sessions/ for history injection
+	IngestBaseURL string // optional: base URL of ingestion server for brain context
 }
 
 type Skill struct {

internal/skills/trainer/handlers.go

@@ -5,6 +5,7 @@ import (
 	"context"
 	"encoding/json"
 	"fmt"
+	"time"
 
 	iexec "github.com/mathiasbq/supervisor/internal/exec"
 	"github.com/mathiasbq/supervisor/internal/session"
@@ -58,6 +59,7 @@ func (s *Skill) Handle(ctx context.Context, tool string, args json.RawMessage) (
 	}
 
 	// ── Step 2: Writer agent (receives reader candidates) ────────────────────
+	t0 := time.Now()
 	writerTask := fmt.Sprintf(
 		"role: writer\nsession_id: %s\nbrain_dir: %s\n\nreader_summary: %s\nreader_candidates:\n%s",
 		a.SessionID, s.cfg.BrainDir, readerResult.Message, readerResult.RunnerOutput,
@@ -72,6 +74,18 @@ func (s *Skill) Handle(ctx context.Context, tool string, args json.RawMessage) (
 		return nil, fmt.Errorf("writer agent: %w", err)
 	}
 
+	_ = session.Append(s.cfg.SessionsDir, a.SessionID, session.Entry{
+		SessionID:   a.SessionID,
+		Timestamp:   time.Now(),
+		Skill:       "trainer",
+		Phase:       "trainer",
+		Attempts:    session.AttemptsFrom(writerResult.Attempts),
+		FinalStatus: writerResult.Status,
+		ModelUsed:   writerResult.ModelUsed,
+		DurationMs:  time.Since(t0).Milliseconds(),
+		Message:     writerResult.Message,
+	})
+
 	b, err := json.Marshal(writerResult)
 	if err != nil {
 		return nil, fmt.Errorf("marshal result: %w", err)