feat(mode): brain+gitea in all modes; drop iceboxed routing entry (#75)

Step 7 of the consolidation: reflect gitea-mcp as an available connection
(Gitea-as-audit-trail is an invariant going forward) and stop emitting the
now-iceboxed routing pod.

- cmd/hyperguild mode.go: every mode (cloud/client-local/sovereign) now lists
  brain + gitea; removed the client-local `routing` entry (koala:30310, the
  iceboxed pod). Tests updated to the new contract.
- .mcp.json: add gitea-mcp (git-mcp.d-ma.be, Bearer ${GITEA_MCP_TOKEN}).
- cmd/hyperguild/README: modes doc updated (brain+gitea, no routing).

Refs #75.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

.gitea/workflows/cd.yml

@@ -14,7 +14,6 @@ jobs:
     environment: staging
     env:
       INGESTION_IMAGE: git.d-ma.be/mathias/ingestion
-      ROUTING_IMAGE: git.d-ma.be/mathias/routing
       INFRA_REPO: git@git.d-ma.be:mathias/infra.git
       BUILDKIT_HOST: unix:///run/buildkit/buildkitd.sock
     steps:
@@ -41,28 +40,6 @@ jobs:
 
           echo "Built and pushed ${INGESTION_IMAGE}:${IMAGE_TAG}"
 
-      - name: Build and push routing image
-        run: |
-          set -e
-          trap 'rm -f /tmp/routing-image.tar' EXIT
-          IMAGE_TAG="${{ github.sha }}"
-          echo "Building ${ROUTING_IMAGE}:${IMAGE_TAG}"
-
-          buildctl --addr "${BUILDKIT_HOST}" build \
-            --frontend dockerfile.v0 \
-            --local context=. \
-            --local dockerfile=. \
-            --opt filename=Dockerfile.routing \
-            --opt build-arg:VERSION="${IMAGE_TAG}" \
-            --output type=oci,dest=/tmp/routing-image.tar
-
-          skopeo copy \
-            oci-archive:/tmp/routing-image.tar \
-            docker://${ROUTING_IMAGE}:${IMAGE_TAG} \
-            --dest-creds "${{ secrets.REGISTRY_CREDS }}"
-
-          echo "Built and pushed ${ROUTING_IMAGE}:${IMAGE_TAG}"
-
       - name: Update infra repo
         run: |
           set -e
@@ -81,18 +58,14 @@ jobs:
           sed -i "s|git.d-ma.be/mathias/ingestion:.*|git.d-ma.be/mathias/ingestion:${IMAGE_TAG}|" \
             "k3s/apps/supervisor/ingestion-deployment.yaml"
 
-          sed -i "s|git.d-ma.be/mathias/routing:.*|git.d-ma.be/mathias/routing:${IMAGE_TAG}|" \
-            "k3s/apps/routing/deployment.yaml"
-
           git config user.email "cd-bot@d-ma.be"
           git config user.name "CD Bot"
-          git add "k3s/apps/supervisor/ingestion-deployment.yaml" \
+          git add "k3s/apps/supervisor/ingestion-deployment.yaml"
-                  "k3s/apps/routing/deployment.yaml"
+          git commit -m "chore(deploy): ingestion → ${IMAGE_TAG}"
-          git commit -m "chore(deploy): ingestion+routing → ${IMAGE_TAG}"
           GIT_SSH_COMMAND="ssh -i ~/.ssh/infra_deploy_key -o IdentitiesOnly=yes" \
             git push
 
-          echo "Infra repo updated: ingestion+routing → ${IMAGE_TAG}"
+          echo "Infra repo updated: ingestion → ${IMAGE_TAG}"
 
       - name: Trigger Flux reconcile (immediate)
         run: |
@@ -132,35 +105,3 @@ jobs:
             kubectl describe pods -n supervisor -l app=ingestion | tail -40
             exit 1
           }
-
-      - name: Wait for Flux to apply new routing image
-        run: |
-          EXPECTED="git.d-ma.be/mathias/routing:${{ github.sha }}"
-          for i in $(seq 1 60); do
-            CURRENT=$(kubectl get deploy routing -n routing \
-              -o jsonpath='{.spec.template.spec.containers[0].image}' 2>/dev/null || echo "")
-            if [ "$CURRENT" = "$EXPECTED" ]; then
-              echo "✓ Flux applied routing image after ${i}s"
-              break
-            fi
-            sleep 1
-          done
-          kubectl get deploy routing -n routing \
-            -o jsonpath='{.spec.template.spec.containers[0].image}' \
-            | grep -qx "$EXPECTED" \
-            || { echo "✗ Flux did not apply routing image within 60s"; exit 1; }
-
-      - name: Verify routing rollout
-        run: |
-          kubectl rollout status deployment/routing \
-            --namespace routing \
-            --timeout=120s \
-          || {
-            echo "── pod status ──"
-            kubectl get pods -n routing -o wide
-            echo "── events ──"
-            kubectl get events -n routing --sort-by='.lastTimestamp' | tail -20
-            echo "── describe ──"
-            kubectl describe pods -n routing -l app=routing | tail -40
-            exit 1
-          }

.mcp.json

@@ -6,6 +6,13 @@
       "headers": {
         "Authorization": "Bearer ${BRAIN_MCP_TOKEN}"
       }
+    },
+    "gitea": {
+      "type": "http",
+      "url": "https://git-mcp.d-ma.be/mcp",
+      "headers": {
+        "Authorization": "Bearer ${GITEA_MCP_TOKEN}"
+      }
     }
   }
 }

Dockerfile.routing

@@ -1,30 +0,0 @@
-# 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/routing ./cmd/routing
-
-# ── Runtime stage ─────────────────────────────────────────────────────────────
-FROM gcr.io/distroless/base-debian12
-
-COPY --from=builder /out/routing /usr/local/bin/routing
-COPY config/ /app/config/
-
-ENV SUPERVISOR_CONFIG_DIR=/app/config/supervisor
-ENV ROUTING_PORT=3210
-
-EXPOSE 3210
-
-USER 65532:65532
-
-ENTRYPOINT ["/usr/local/bin/routing"]

ICEBOX.md

@@ -0,0 +1,49 @@
+# Icebox — retired code (recoverable, not destroyed)
+
+Per issue #75 (consolidate to a single harness), the routing-pod path was removed
+from the live tree. It is **preserved and recoverable**, not deleted without trace.
+
+## What was iceboxed (2026-07-01, issue #75)
+
+| Path | Why |
+|------|-----|
+| `cmd/routing/` | The routing MCP-server binary; every skill call was wrapped through the broken pass-rate router (`wrap(skillName)`). |
+| `internal/routing/` | Router / Fetcher / Policy / pass-rate. Signal is survivorship-biased and unusable as-is (infra#174). |
+| `internal/skills/{review,debug,retrospective,trainer,project}/` | Skill handlers usable **only** through `cmd/routing` (verified: each imported solely by `cmd/routing`). |
+| `Dockerfile.routing` | Built `cmd/routing` exclusively. |
+| `.gitea/workflows/cd.yml` (routing steps only) | Removed the routing image build + infra image-bump + Flux-wait/rollout-verify for routing; **ingestion build/deploy is unchanged**. |
+
+## Why
+
+The live minimal harness is `cmd/hyperguild` + `brain-mcp` (+ `gitea-mcp` available) —
+that is what ran the infra#170 loop-1 experiment (routing/injection machinery off) and
+closed it twice. `cmd/hyperguild` has **zero** transitive dependency on `internal/routing`
+or `cmd/routing`'s packages (it imports only `internal/tier`). The routing pass-rate signal
+is being retired, not resurrected (fresh start, per infra#174).
+
+## How to recover
+
+Everything above is preserved at commit `00e5f62` under:
+
+- **tag** `icebox/cmd-routing-2026-07-01`
+- **branch** `icebox/cmd-routing`
+
+```bash
+# inspect
+git checkout icebox/cmd-routing-2026-07-01
+
+# restore specific packages onto a branch
+git checkout icebox/cmd-routing-2026-07-01 -- cmd/routing internal/routing \
+  internal/skills/review internal/skills/debug internal/skills/retrospective \
+  internal/skills/trainer internal/skills/project Dockerfile.routing
+```
+
+## Deliberately NOT touched here (separate scope)
+
+- **Live k8s routing deployment** (`infra` repo, `k3s/apps/routing/`) still runs its last
+  image; CD no longer rebuilds/redeploys it. Tearing down that deployment is a separate
+  infra-repo task.
+- **`internal/skills/{brain,org,sessionlog}/`** — kept per #75; already had no importer
+  (orphaned before this cut), harmless, compile + test green.
+- **`config/supervisor/{review,debug,retrospective,trainer-*}.md`** — routing skill prompts,
+  now orphaned data; left in place (not code, no build impact).

cmd/hyperguild/README.md

@@ -112,16 +112,15 @@ Flags:
 - `--out PATH` — output file (default `./.mcp.json`)
 - `--force` — overwrite an existing file
 
-Modes:
+Modes (all list **brain + gitea** — Gitea is the audit-trail invariant of the
+consolidated single harness, #75):
 
-- **cloud** — brain MCP only. Claude Code with no routing.
+- **cloud** — brain + gitea MCP.
-- **client-local** — brain + routing pod. The `routing` entry points at
+- **client-local** — brain + gitea MCP. (The former `routing` entry pointing at
-  `koala:30310/mcp` (the routing pod, deployed in Plan 6). The
+  `koala:30310/mcp` was removed — the routing pod is iceboxed, #75.)
-  `X-Hyperguild-Mode: client-local` header is forward-compat for future
+- **sovereign** — brain + gitea, with a `_mode_note` explaining that this mode
-  modes; the pod treats absent or unknown values as `client-local`.
+  primarily uses Crush + LiteLLM and the `.mcp.json` is a Claude Code fallback
-- **sovereign** — brain only, with a `_mode_note` explaining that this
+  for emergency offline use.
-  mode primarily uses Crush + LiteLLM and the `.mcp.json` is a Claude
-  Code fallback for emergency offline use.
 
 ## Environment
 

cmd/hyperguild/mode.go

@@ -59,31 +59,40 @@ func runMode(ctx context.Context, args []string, _ io.Reader, stdout, stderr io.
 	return nil
 }
 
+// giteaMCPURL is the public Gitea MCP endpoint (OAuth via Dex/Authentik). Gitea
+// is the audit-trail invariant of the consolidated single harness (#75), so every
+// mode lists it as an available connection.
+const giteaMCPURL = "https://git-mcp.d-ma.be/mcp"
+
+func brainEntry(brainURL string) map[string]any {
+	return map[string]any{
+		"url":         brainURL + "/mcp",
+		"description": "Brain MCP — knowledge query, write, ingestion, session log",
+	}
+}
+
+func giteaEntry() map[string]any {
+	return map[string]any{
+		"url":         giteaMCPURL,
+		"description": "Gitea MCP — issues/PRs/repo ops (audit-trail invariant)",
+	}
+}
+
 func modeCloud(brainURL string) map[string]any {
 	return map[string]any{
 		"mcpServers": map[string]any{
-			"brain": map[string]any{
+			"brain": brainEntry(brainURL),
-				"url":         brainURL + "/mcp",
+			"gitea": giteaEntry(),
-				"description": "Brain MCP — knowledge query, write, ingestion, session log",
-			},
 		},
 	}
 }
 
 func modeClientLocal(brainURL string) map[string]any {
+	// The routing pod is iceboxed (#75); the consolidated harness is brain + gitea.
 	return map[string]any{
 		"mcpServers": map[string]any{
-			"brain": map[string]any{
+			"brain": brainEntry(brainURL),
-				"url":         brainURL + "/mcp",
+			"gitea": giteaEntry(),
-				"description": "Brain MCP — knowledge query, write, ingestion, session log",
-			},
-			"routing": map[string]any{
-				"url":         "http://koala:30310/mcp",
-				"description": "Mode 2 routing pod — routes skill calls to LiteLLM/local",
-				"headers": map[string]any{
-					"X-Hyperguild-Mode": "client-local",
-				},
-			},
 		},
 	}
 }
@@ -92,10 +101,8 @@ func modeSovereign(brainURL string) map[string]any {
 	return map[string]any{
 		"_mode_note": "Sovereign mode primarily uses Crush + LiteLLM. This .mcp.json is provided as Claude Code fallback (e.g. emergency offline editing).",
 		"mcpServers": map[string]any{
-			"brain": map[string]any{
+			"brain": brainEntry(brainURL),
-				"url":         brainURL + "/mcp",
+			"gitea": giteaEntry(),
-				"description": "Brain MCP — knowledge query, write, ingestion, session log",
-			},
 		},
 	}
 }

cmd/hyperguild/mode_test.go

@@ -35,11 +35,13 @@ func TestRunMode_Cloud_Default(t *testing.T) {
 	servers, ok := got["mcpServers"].(map[string]any)
 	require.True(t, ok, "mcpServers must be a JSON object")
 	assert.Contains(t, servers, "brain")
+	assert.Contains(t, servers, "gitea")
 	assert.NotContains(t, servers, "routing")
 	assert.NotContains(t, got, "_mode_note")
 }
 
-func TestRunMode_ClientLocal_HasRoutingEntry(t *testing.T) {
+func TestRunMode_ClientLocal_NoRouting_HasGitea(t *testing.T) {
+	// #75: the routing pod is iceboxed; the consolidated harness is brain + gitea.
 	dir := t.TempDir()
 	outPath := filepath.Join(dir, ".mcp.json")
 	t.Setenv("BRAIN_URL", "http://koala:30330")
@@ -51,17 +53,11 @@ func TestRunMode_ClientLocal_HasRoutingEntry(t *testing.T) {
 	got := readJSON(t, outPath)
 	servers := got["mcpServers"].(map[string]any)
 	require.Contains(t, servers, "brain")
-	require.Contains(t, servers, "routing")
+	require.Contains(t, servers, "gitea")
-
+	assert.NotContains(t, servers, "routing", "routing pod iceboxed (#75)")
-	routing := servers["routing"].(map[string]any)
-	assert.NotContains(t, routing, "_routing_pending", "placeholder should be removed once Plan 6 ships")
-
-	headers, ok := routing["headers"].(map[string]any)
-	require.True(t, ok, "routing entry should have headers block")
-	assert.Equal(t, "client-local", headers["X-Hyperguild-Mode"])
 }
 
-func TestModeClientLocalHasRoutingHeader(t *testing.T) {
+func TestModeGiteaEntryPresentAndWellFormed(t *testing.T) {
 	tmp := t.TempDir() + "/mcp.json"
 	out := &bytes.Buffer{}
 	stderr := &bytes.Buffer{}
@@ -73,13 +69,10 @@ func TestModeClientLocalHasRoutingHeader(t *testing.T) {
 	require.NoError(t, json.Unmarshal(body, &doc))
 
 	servers := doc["mcpServers"].(map[string]any)
-	routing := servers["routing"].(map[string]any)
+	require.NotContains(t, servers, "routing")
-	assert.Equal(t, "http://koala:30310/mcp", routing["url"])
+	gitea, ok := servers["gitea"].(map[string]any)
-	assert.NotContains(t, routing, "_routing_pending", "placeholder should be removed once Plan 6 ships")
+	require.True(t, ok, "gitea entry must be present (audit-trail invariant)")
-
+	assert.Equal(t, "https://git-mcp.d-ma.be/mcp", gitea["url"])
-	headers, ok := routing["headers"].(map[string]any)
-	require.True(t, ok, "routing entry should have headers block")
-	assert.Equal(t, "client-local", headers["X-Hyperguild-Mode"])
 }
 
 func TestRunMode_Sovereign_HasModeNote(t *testing.T) {
@@ -94,6 +87,7 @@ func TestRunMode_Sovereign_HasModeNote(t *testing.T) {
 	assert.Contains(t, got, "_mode_note")
 	servers := got["mcpServers"].(map[string]any)
 	assert.Contains(t, servers, "brain")
+	assert.Contains(t, servers, "gitea")
 	assert.NotContains(t, servers, "routing")
 }
 

cmd/routing/main.go

@@ -1,170 +0,0 @@
-package main
-
-// The internal/skills/{debug,retrospective,review,trainer} packages imported
-// below are also imported by cmd/supervisor. Plan 7 (supervisor retirement)
-// MUST NOT delete these four packages — the routing pod is their second
-// consumer. Plan 7 deletes only internal/skills/{tdd,spec,tier} (the skills
-// that don't route to local), the supervisor binary, and supervisor manifests.
-// See docs/superpowers/specs/2026-05-04-mode-2-routing-pod-design.md (Constraints).
-
-import (
-	"context"
-	"log/slog"
-	"net/http"
-	"os"
-	"time"
-
-	"github.com/mathiasbq/supervisor/internal/auth"
-	"github.com/mathiasbq/supervisor/internal/config"
-	iexec "github.com/mathiasbq/supervisor/internal/exec"
-	"github.com/mathiasbq/supervisor/internal/githubclient"
-	"github.com/mathiasbq/supervisor/internal/mcp"
-	"github.com/mathiasbq/supervisor/internal/mcpclient"
-	"github.com/mathiasbq/supervisor/internal/registry"
-	"github.com/mathiasbq/supervisor/internal/routing"
-	"github.com/mathiasbq/supervisor/internal/skills/debug"
-	"github.com/mathiasbq/supervisor/internal/skills/project"
-	"github.com/mathiasbq/supervisor/internal/skills/retrospective"
-	"github.com/mathiasbq/supervisor/internal/skills/review"
-	"github.com/mathiasbq/supervisor/internal/skills/trainer"
-)
-
-func main() {
-	logger := slog.New(slog.NewTextHandler(os.Stderr, nil))
-	slog.SetDefault(logger)
-
-	cfg, err := config.LoadRouting()
-	if err != nil {
-		logger.Error("config load failed", "err", err)
-		os.Exit(1)
-	}
-
-	configDir := envOr("SUPERVISOR_CONFIG_DIR", "/app/config/supervisor")
-	mustRead := func(path string) string {
-		b, err := os.ReadFile(configDir + "/" + path)
-		if err != nil {
-			logger.Error("read prompt failed", "path", path, "err", err)
-			os.Exit(1)
-		}
-		return string(b)
-	}
-
-	llm := iexec.NewLiteLLM(cfg.LiteLLMBaseURL, cfg.LiteLLMAPIKey, 0)
-
-	router := &routing.Router{
-		Fetcher:       routing.NewFetcher(cfg.BrainURL, "7d", time.Duration(cfg.PassRateTTLSeconds)*time.Second),
-		Logger:        routing.NewLogger(cfg.BrainURL),
-		Policy:        routing.Policy{Floor: cfg.RouteLocalFloor, Ceil: cfg.RouteLocalCeil},
-		FastModel:     cfg.FastModel,
-		ThinkingModel: cfg.ThinkingModel,
-		Complete:      llm.Complete,
-	}
-
-	// Skill packages call CompleteFunc(ctx, model, system, user) — no session_id
-	// or project_root in the signature. Rather than modifying every skill's API
-	// (and inflating Plan 6's blast radius), the routing pod logs every decision
-	// under a fixed session_id "_routing". Operators query
-	// `GET /pass-rate?skill=_routing&window=...` to inspect routing health.
-	const routingSessionID = "_routing"
-	wrap := func(skillName string) routing.CompleteFunc {
-		return func(ctx context.Context, _, system, user string) (string, int64, error) {
-			// The model param is ignored: the router picks the model based on policy.
-			return router.Run(ctx, routing.RunInput{
-				Skill:       skillName,
-				System:      system,
-				User:        user,
-				SessionID:   routingSessionID,
-				ProjectRoot: "",
-			})
-		}
-	}
-
-	reg := registry.New()
-	reg.Register(review.New(review.Config{
-		SkillPrompt:  mustRead("review.md"),
-		DefaultModel: cfg.FastModel,
-		CompleteFunc: review.CompleteFunc(wrap("review")),
-	}))
-	reg.Register(debug.New(debug.Config{
-		SkillPrompt:  mustRead("debug.md"),
-		DefaultModel: cfg.FastModel,
-		CompleteFunc: debug.CompleteFunc(wrap("debug")),
-	}))
-	reg.Register(retrospective.New(retrospective.Config{
-		SkillPrompt:  mustRead("retrospective.md"),
-		DefaultModel: cfg.FastModel,
-		CompleteFunc: retrospective.CompleteFunc(wrap("retrospective")),
-	}))
-	reg.Register(trainer.New(trainer.Config{
-		ReaderPrompt: mustRead("trainer-reader.md"),
-		WriterPrompt: mustRead("trainer-writer.md"),
-		DefaultModel: cfg.FastModel,
-		CompleteFunc: trainer.CompleteFunc(wrap("trainer")),
-	}))
-
-	if cfg.GiteaMCPURL != "" {
-		mcpC, err := mcpclient.New(cfg.GiteaMCPURL, cfg.GiteaMCPToken)
-		if err != nil {
-			logger.Error("mcpclient init for project_create — GITEA_MCP_URL is set but GITEA_MCP_TOKEN is empty (check routing-secrets)", "err", err)
-			os.Exit(1)
-		}
-		var ghClient *githubclient.Client
-		if cfg.GitHubPAT != "" {
-			ghClient = githubclient.New(cfg.GitHubPAT)
-		}
-		reg.Register(project.New(project.Config{
-			Client:      mcpC,
-			GitHub:      ghClient,
-			GiteaOwner:  cfg.GiteaOwner,
-			GitHubOwner: cfg.GitHubOwner,
-			GitHubPAT:   cfg.GitHubPAT,
-			InfraRepo:   cfg.InfraRepo,
-		}))
-		logger.Info("project_create registered", "gitea_mcp_url", cfg.GiteaMCPURL,
-			"gitea_owner", cfg.GiteaOwner, "github_owner", cfg.GitHubOwner,
-			"infra_repo", cfg.InfraRepo, "github_pat_set", cfg.GitHubPAT != "")
-	} else {
-		logger.Info("project_create skipped — GITEA_MCP_URL not set")
-	}
-
-	var validator *auth.Validator
-	if dexURL := os.Getenv("DEX_ISSUER_URL"); dexURL != "" {
-		audience := os.Getenv("MCP_AUDIENCE")
-		v, err := auth.NewValidator(dexURL, audience)
-		if err != nil {
-			logger.Error("build jwt validator", "err", err)
-			os.Exit(1)
-		}
-		validator = v
-		logger.Info("jwt auth enabled", "issuer", dexURL)
-	}
-
-	srv := mcp.NewServer(reg, cfg.MCPAuthToken, validator)
-	mux := http.NewServeMux()
-	mux.Handle("/mcp", srv)
-	mux.HandleFunc("/healthz", func(w http.ResponseWriter, _ *http.Request) {
-		w.WriteHeader(http.StatusOK)
-	})
-
-	if dexURL := os.Getenv("DEX_ISSUER_URL"); dexURL != "" {
-		resourceURL := os.Getenv("MCP_RESOURCE_URL")
-		mux.HandleFunc("GET /.well-known/oauth-protected-resource",
-			auth.ProtectedResourceHandler(resourceURL, dexURL))
-	}
-
-	addr := ":" + cfg.Port
-	logger.Info("routing pod starting", "addr", addr,
-		"fast", cfg.FastModel, "thinking", cfg.ThinkingModel,
-		"floor", cfg.RouteLocalFloor, "ceil", cfg.RouteLocalCeil)
-	if err := http.ListenAndServe(addr, mux); err != nil { //nolint:gosec
-		logger.Error("server stopped", "err", err)
-		os.Exit(1)
-	}
-}
-
-func envOr(key, def string) string {
-	if v := os.Getenv(key); v != "" {
-		return v
-	}
-	return def
-}

cmd/routing/main_test.go

@@ -1,135 +0,0 @@
-package main_test
-
-import (
-	"context"
-	"encoding/json"
-	"io"
-	"net"
-	"net/http"
-	"net/http/httptest"
-	"os"
-	"os/exec"
-	"strconv"
-	"strings"
-	"testing"
-	"time"
-
-	"github.com/stretchr/testify/assert"
-	"github.com/stretchr/testify/require"
-)
-
-// TestRoutingPodEndToEnd boots the binary against fake LiteLLM + brain servers,
-// calls tools/list and one tools/call, and verifies the brain saw a session_log POST.
-func TestRoutingPodEndToEnd(t *testing.T) {
-	if testing.Short() {
-		t.Skip("end-to-end binary boot")
-	}
-
-	var brainHits int
-	llm := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
-		_ = json.NewEncoder(w).Encode(map[string]any{
-			"choices": []map[string]any{{"message": map[string]any{"role": "assistant", "content": "stub"}}},
-		})
-	}))
-	defer llm.Close()
-
-	brain := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		switch r.URL.Path {
-		case "/pass-rate":
-			brainHits++
-			_ = json.NewEncoder(w).Encode(map[string]any{"pass_rate": 0.95})
-		case "/mcp":
-			brainHits++
-			_ = json.NewEncoder(w).Encode(map[string]any{"jsonrpc": "2.0", "id": 1, "result": map[string]any{}})
-		}
-	}))
-	defer brain.Close()
-
-	port := freePort(t)
-	addr := "127.0.0.1:" + port
-	baseURL := "http://" + addr
-
-	bin := buildRouting(t)
-	cmd := exec.Command(bin)
-	cmd.Env = []string{
-		"ROUTING_PORT=" + port,
-		"LITELLM_BASE_URL=" + llm.URL,
-		"LITELLM_API_KEY=stub",
-		"BRAIN_URL=" + brain.URL,
-		"SUPERVISOR_CONFIG_DIR=../../config/supervisor",
-		"PATH=" + os.Getenv("PATH"),
-		"HOME=" + os.Getenv("HOME"),
-	}
-	require.NoError(t, cmd.Start())
-	t.Cleanup(func() { _ = cmd.Process.Kill() })
-
-	require.NoError(t, waitForPort(t, addr, 30*time.Second))
-
-	resp := mcpCall(t, baseURL+"/mcp", `{"jsonrpc":"2.0","id":1,"method":"tools/list"}`)
-	assert.Contains(t, resp, `"review"`)
-	assert.Contains(t, resp, `"debug"`)
-	assert.Contains(t, resp, `"retrospective"`)
-	assert.Contains(t, resp, `"trainer"`)
-
-	resp = mcpCall(t, baseURL+"/mcp", `{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"review","arguments":{"project_root":"/tmp","files":["README.md"]}}}`)
-	_ = resp // shape varies by skill; we only need a 200
-
-	// Wait briefly for the async session_log to land.
-	deadline := time.Now().Add(2 * time.Second)
-	for time.Now().Before(deadline) && brainHits < 2 {
-		time.Sleep(50 * time.Millisecond)
-	}
-	assert.GreaterOrEqual(t, brainHits, 2, "expected at least one /pass-rate hit and one /mcp session_log hit")
-}
-
-func buildRouting(t *testing.T) string {
-	t.Helper()
-	bin := t.TempDir() + "/routing"
-	out, err := exec.Command("go", "build", "-o", bin, "github.com/mathiasbq/supervisor/cmd/routing").CombinedOutput()
-	require.NoError(t, err, "build failed: %s", out)
-	return bin
-}
-
-func waitForPort(_ *testing.T, addr string, dur time.Duration) error {
-	deadline := time.Now().Add(dur)
-	for time.Now().Before(deadline) {
-		c, err := http.Get("http://" + addr + "/healthz") //nolint:noctx
-		if err == nil {
-			_ = c.Body.Close()
-			return nil
-		}
-		conn, err := http.NewRequest(http.MethodPost, "http://"+addr+"/mcp", strings.NewReader(`{}`))
-		if err == nil {
-			r, err := http.DefaultClient.Do(conn)
-			if err == nil {
-				_ = r.Body.Close()
-				return nil
-			}
-		}
-		time.Sleep(50 * time.Millisecond)
-	}
-	return context.DeadlineExceeded
-}
-
-func mcpCall(t *testing.T, url, body string) string {
-	t.Helper()
-	r, err := http.Post(url, "application/json", strings.NewReader(body)) //nolint:noctx
-	require.NoError(t, err)
-	defer func() { _ = r.Body.Close() }()
-	raw, err := io.ReadAll(r.Body)
-	require.NoError(t, err)
-	return string(raw)
-}
-
-// freePort grabs an OS-assigned TCP port and releases it. There is a small
-// race window before the subprocess re-binds it, but it is acceptable for
-// test isolation against a hardcoded port colliding with another test or
-// stray process.
-func freePort(t *testing.T) string {
-	t.Helper()
-	l, err := net.Listen("tcp", "127.0.0.1:0")
-	require.NoError(t, err)
-	port := l.Addr().(*net.TCPAddr).Port
-	require.NoError(t, l.Close())
-	return strconv.Itoa(port)
-}

docs/runbooks/exercising-pass-rate-traffic.md

@@ -0,0 +1,104 @@
+# Runbook: exercising review/debug traffic to fill the pass-rate dataset
+
+**Why this exists:** the routing pod's local-vs-cloud decision is gated on a
+pass-rate history that only accrues from real `review`/`debug` invocations
+**through the pod**. Until the dataset has data, the fast (local) path never
+activates and the core hypothesis (hyperguild #35) can't be validated. This
+runbook is how you spin that flywheel.
+
+## The one trap
+
+Pass-rate accrues **only** when a skill tool is called via the routing pod's MCP
+endpoint. These look like they should count but **do not**:
+
+- **Crush** — talks to LiteLLM directly, bypasses the pod. No log.
+- **claude.ai web / Claude Desktop without the connector** — no log.
+- **Running the local `code-review` / `debug` skills** (`~/dev/.skills`) inline in
+  a Claude Code session — those are local skills, not the pod's MCP tools. No log.
+
+Only a `tools/call` to the routing pod records a pass/fail.
+
+## Endpoints
+
+| Purpose | URL | Auth |
+|---------|-----|------|
+| Routing MCP (local, Tailscale) | `http://koala:30310/mcp` | Bearer `ROUTING_MCP_TOKEN` |
+| Routing MCP (remote) | `https://routing-mcp.d-ma.be/mcp` | OAuth via `auth.d-ma.be` (audience `claude-ai`) |
+| Pass-rate readout | `http://koala:30330/pass-rate?skill=<name>` | none (read-only) |
+
+Tools advertised: **`review`**, **`debug`** (the two the #35 gate measures),
+plus `session_log`, `retrospective`, `trainer`.
+
+## Step 1 — connect the routing pod as an MCP server
+
+**Local** (needs the bearer token; keep it out of argv via 1Password):
+
+```bash
+op run --env-file ~/.op-env -- \
+  claude mcp add routing --transport http http://koala:30310/mcp \
+    --header "Authorization: Bearer $ROUTING_MCP_TOKEN"
+```
+
+**Remote** (claude.ai / Claude Desktop): add a custom connector pointing at
+`https://routing-mcp.d-ma.be/mcp`; it completes OAuth against `auth.d-ma.be`,
+no static token.
+
+Verify: a `tools/list` should return `review`, `debug`, `session_log`,
+`retrospective`, `trainer`.
+
+## Step 2 — route real work through it
+
+In normal sessions, invoke the pod's tools instead of reviewing/debugging inline:
+
+- *"Use the **routing** `review` tool on this diff."*
+- *"**debug** this failure through the routing pod."*
+
+Each call logs an outcome to ingestion → `/pass-rate` ticks up.
+
+## Step 3 — how routing actually picks the model
+
+Per `internal/routing/policy.go`:
+
+1. pass-rate `nil` (cold) → **local** fast tier. The router defaults to local
+   from invocation #1, not to cloud — so the fast tier is exercised immediately.
+2. pass-rate `>= 0.90` (floor) → **local**; `< 0.70` (ceil) → **cloud/thinking**;
+   in the `[0.70, 0.90)` band a request-hash bit samples 50/50.
+3. On a local execution error the router falls open to the thinking model for
+   that one call (logged `thinking_fallback`).
+
+So you are not "paying in on cloud" — cold calls already run on the (validated)
+local fast tier **`koala/qwen36-35b-a3b`** (Qwen3.6-35B-A3B MTP, promoted
+2026-06-29, infra `c66a195`, `HYPERGUILD_FAST_MODEL`). Accumulating passes just
+keeps it there once real pass-rate is computed.
+
+> **Instrumentation note (#73, fixed 2026-06-30):** until v0.11.1 the pod logged
+> successes as `"skip"` (not `"pass"`), under `skill:"_routing"`, via an
+> unauthenticated POST that silently 401'd — so `/pass-rate` stayed at zero no
+> matter how much you used it. That's fixed and verified (a real review call now
+> moves `/pass-rate?skill=review` 0→1). If you see traffic not registering,
+> re-check #73's three failure modes first.
+
+## Target & verification
+
+- **50 logged invocations** across `review` + `debug` within the 14-day window.
+  The clock restarts **2026-06-30** (the day instrumentation was verified working;
+  the original 2026-06-26→07-10 window measured broken plumbing) → **kill-date
+  2026-07-14**, ~4 calls/day (1 already logged from the #73 smoke test).
+- Check progress anytime:
+
+  ```bash
+  curl -s "http://koala:30330/pass-rate?skill=review"
+  curl -s "http://koala:30330/pass-rate?skill=debug"
+  ```
+
+- If ~4–5/day isn't realistic alongside Crush, that is **not** a failure — per
+  #35 deliverable #1 it's the signal hyperguild isn't on the work critical path,
+  and the pre-decided **Berget fallback** (`gpt-oss-120b` / `qwen3-32b`) carries
+  the fast tier instead.
+
+## Refs
+
+- hyperguild #35 — the validation issue (data gate = deliverable #1)
+- `docs/multi-model-routing.md` — routing policy
+- brain: `wiki/homelab/hypotheses/qwen36-35b-a3b-fast-model-experiment-2026-05-28.md`
+- infra `c66a195` — qwen36 promotion; `models.yml` / `llama-swap-configmap.yaml`

ingestion/cmd/server/main.go

@@ -8,18 +8,19 @@ import (
 	"net/http"
 	"net/url"
 	"os"
+	"path/filepath"
 	"strconv"
 	"strings"
 	"time"
 
-	chassisauth "gitea.d-ma.be/mathias/mcp-chassis/auth"
+	chassisauth "git.d-ma.be/mathias/mcp-chassis/auth"
 
 	"github.com/mathiasbq/hyperguild/ingestion/internal/api"
-	"github.com/mathiasbq/hyperguild/ingestion/internal/claudewatcher"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/audit"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/capture"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/capturehttp"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/classification"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/claudewatcher"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/embed"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/gitea"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/graphstore"
@@ -123,6 +124,35 @@ func envInt(key string, fallback int) int {
 	return fallback
 }
 
+// buildAuditSink selects the capture audit sink. When BRAIN_LOKI_URL is
+// set it builds the classification-aware DegradingSink (loki central +
+// durable file buffer + optional ntfy) and starts the reconcile loop;
+// otherwise it falls back to a plain slog sink. The buffer lives under the
+// brain dir so it survives process restarts.
+func buildAuditSink(ctx context.Context, brainDir string, logger *slog.Logger) capture.AuditSink {
+	lokiURL := os.Getenv("BRAIN_LOKI_URL")
+	central := audit.NewLokiCentral(lokiURL)
+	if central == nil {
+		logger.Info("capture audit: slog sink (BRAIN_LOKI_URL unset)")
+		return audit.NewSlogSink(logger)
+	}
+	buffer, err := audit.NewFileBuffer(filepath.Join(brainDir, ".audit-buffer", "capture.jsonl"))
+	if err != nil {
+		logger.Error("capture audit buffer init", "err", err)
+		os.Exit(1)
+	}
+	// Keep notifier as a nil interface (not a typed-nil) when unconfigured
+	// so DegradingSink/Reconcile skip it cleanly.
+	var notifier audit.Notifier
+	if n := audit.NewNtfyNotifier(os.Getenv("BRAIN_NTFY_URL"), os.Getenv("BRAIN_NTFY_TOKEN")); n != nil {
+		notifier = n
+	}
+	reconcileInterval := time.Duration(envInt("BRAIN_AUDIT_RECONCILE_INTERVAL", 60)) * time.Second
+	audit.StartReconcile(ctx, central, buffer, notifier, reconcileInterval)
+	logger.Info("capture audit: loki+buffer sink", "loki", lokiURL, "reconcile_s", int(reconcileInterval.Seconds()))
+	return audit.NewDegradingSink(central, buffer, notifier)
+}
+
 // splitList parses a comma-separated env value into a trimmed,
 // empty-free slice. Used for the capture sovereign-principal allowlist.
 func splitList(v string) []string {
@@ -339,6 +369,8 @@ func main() {
 	mux.HandleFunc("POST /ingest-path", h.IngestPath)
 	mux.HandleFunc("POST /ingest-raw", h.IngestRaw)
 	mux.HandleFunc("POST /backfill-refs", h.BackfillRefs)
+	mux.HandleFunc("GET /pending", h.Pending)
+	mux.HandleFunc("POST /promote", h.Promote)
 	mux.HandleFunc("POST /backfill-embeddings", h.BackfillEmbeddings)
 	mux.HandleFunc("GET /pass-rate", h.PassRate)
 	jwtValidator, err := chassisauth.NewJWTValidator(ctx, os.Getenv("DEX_ISSUER_URL"), os.Getenv("MCP_AUDIENCE"))
@@ -365,11 +397,12 @@ func main() {
 
 	mux.Handle("/mcp", chassisauth.BearerMiddleware(mcpToken, jwtValidator, "brain", resourceMetadataURL, mcpSrv))
 
-	// POST /capture (#53): the uniform capture REST door. Needs a ticket
+	// POST /capture (#53/#54): the uniform capture REST door. Needs a ticket
 	// tracker to file action items, so it only mounts when Gitea is
 	// configured. It reuses the MCP server's graph-wired brain store (one
-	// implementation), the classification tags for the I1 gate, and a slog
+	// implementation), the classification tags for the I1 gate, and a
-	// audit sink (the loki+buffer sink lands in #54). The handler does its
+	// classification-aware audit sink (loki + durable buffer + ntfy when
+	// BRAIN_LOKI_URL is set, else a plain slog sink). The handler does its
 	// own auth (static + JWT) because it needs the principal to derive the
 	// trust-zone origin — the chassis middleware hides it.
 	if tracker := mcpSrv.IssueTracker(); tracker != nil {
@@ -378,13 +411,23 @@ func main() {
 			logger.Error("load classification config", "err", cerr)
 			os.Exit(1)
 		}
+		auditSink := buildAuditSink(ctx, brainDir, logger)
+		// The Gitea client also satisfies SummaryWriter (#66): session
+		// summaries are written to mathias/ai-sessions over the same API
+		// token. nil only if a future tracker impl lacks file writes.
+		summaryWriter, _ := tracker.(capture.SummaryWriter)
 		captureSvc := capture.NewService(
-			mcpSrv.BrainStore(), tracker, nil, classCfg, audit.NewSlogSink(logger))
+			mcpSrv.BrainStore(), tracker, summaryWriter, classCfg, auditSink)
 		sovereign := splitList(os.Getenv("BRAIN_CAPTURE_SOVEREIGN_PRINCIPALS"))
-		captureH := capturehttp.New(captureSvc, jwtValidator, mcpToken, "local-cli",
+		resolver := capturehttp.NewOriginResolver(sovereign)
-			capturehttp.NewOriginResolver(sovereign))
+		captureH := capturehttp.New(captureSvc, jwtValidator, mcpToken, "local-cli", resolver)
 		mux.Handle("POST /capture", captureH)
-		logger.Info("capture endpoint enabled", "sovereign_principals", len(sovereign))
+		// Same use-case behind the MCP `capture` tool (#55 relay) so MCP-native
+		// harnesses (claude.ai, Crush, Pi, LLM Council) reach capture through
+		// the existing /mcp OAuth connector. mcpSrv is already wrapped above;
+		// WithCapture mutates the same instance, so the tool appears live.
+		mcpSrv.WithCapture(captureSvc, jwtValidator, mcpToken, "local-cli", resolver)
+		logger.Info("capture enabled (REST + MCP tool)", "sovereign_principals", len(sovereign))
 	} else {
 		logger.Info("capture endpoint disabled (BRAIN_GITEA_TOKEN unset)")
 	}

ingestion/go.mod

@@ -2,19 +2,22 @@ module github.com/mathiasbq/hyperguild/ingestion
 
 go 1.26.1
 
+require github.com/stretchr/testify v1.11.1
+
 require (
-	github.com/lestrrat-go/jwx/v2 v2.1.6
+	github.com/kr/text v0.2.0 // indirect
-	github.com/stretchr/testify v1.11.1
+	github.com/lestrrat-go/jwx/v2 v2.1.6 // indirect
+	github.com/rogpeppe/go-internal v1.15.0 // indirect
 )
 
 require (
-	gitea.d-ma.be/mathias/mcp-chassis v0.1.0 // indirect
+	git.d-ma.be/mathias/mcp-chassis v0.2.0
 	github.com/davecgh/go-spew v1.1.1 // indirect
 	github.com/decred/dcrd/dcrec/secp256k1/v4 v4.4.0 // indirect
 	github.com/goccy/go-json v0.10.3 // indirect
 	github.com/jackc/pgpassfile v1.0.0 // indirect
 	github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 // indirect
-	github.com/jackc/pgx/v5 v5.9.2 // indirect
+	github.com/jackc/pgx/v5 v5.9.2
 	github.com/jackc/puddle/v2 v2.2.2 // indirect
 	github.com/lestrrat-go/blackmagic v1.0.3 // indirect
 	github.com/lestrrat-go/httpcc v1.0.1 // indirect
@@ -27,5 +30,5 @@ require (
 	golang.org/x/sync v0.17.0 // indirect
 	golang.org/x/sys v0.31.0 // indirect
 	golang.org/x/text v0.29.0 // indirect
-	gopkg.in/yaml.v3 v3.0.1 // indirect
+	gopkg.in/yaml.v3 v3.0.1
 )

ingestion/go.sum

@@ -1,5 +1,6 @@
-gitea.d-ma.be/mathias/mcp-chassis v0.1.0 h1:8RXO34+n7Vu8HnUMagars6fc4oemqRpMu7MVtjaj4qY=
+git.d-ma.be/mathias/mcp-chassis v0.2.0 h1:6fLmb7xqRa2nNVWsHaUbbfbArgDXJw/gDhb09clBIjo=
-gitea.d-ma.be/mathias/mcp-chassis v0.1.0/go.mod h1:ajbLlwr2L7FAN3TBU39KucZkKJM02wTbKbDKDEW2YvE=
+git.d-ma.be/mathias/mcp-chassis v0.2.0/go.mod h1:Ks7EK2UnGAN0H3rJjKUxUagX8/ZBdtLrOlcUbv0RwH8=
+github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E=
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
@@ -15,6 +16,10 @@ github.com/jackc/pgx/v5 v5.9.2 h1:3ZhOzMWnR4yJ+RW1XImIPsD1aNSz4T4fyP7zlQb56hw=
 github.com/jackc/pgx/v5 v5.9.2/go.mod h1:mal1tBGAFfLHvZzaYh77YS/eC6IX9OWbRV1QIIM0Jn4=
 github.com/jackc/puddle/v2 v2.2.2 h1:PR8nw+E/1w0GLuRFSmiioY6UooMp6KJv0/61nB7icHo=
 github.com/jackc/puddle/v2 v2.2.2/go.mod h1:vriiEXHvEE654aYKXXjOvZM39qJ0q+azkZFrfEOc3H4=
+github.com/kr/pretty v0.3.0 h1:WgNl7dwNpEZ6jJ9k1snq4pZsg7DOEN8hP9Xw0Tsjwk0=
+github.com/kr/pretty v0.3.0/go.mod h1:640gp4NfQd8pI5XOwp5fnNeVWj67G7CFk/SaSQn7NBk=
+github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
+github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
 github.com/lestrrat-go/blackmagic v1.0.3 h1:94HXkVLxkZO9vJI/w2u1T0DAoprShFd13xtnSINtDWs=
 github.com/lestrrat-go/blackmagic v1.0.3/go.mod h1:6AWFyKNNj0zEXQYfTMPfZrAXUWUfTIZ5ECEUEJaijtw=
 github.com/lestrrat-go/httpcc v1.0.1 h1:ydWCStUeJLkpYyjLDHihupbn2tYmZ7m22BGkcvZZrIE=
@@ -29,6 +34,8 @@ github.com/lestrrat-go/option v1.0.1 h1:oAzP2fvZGQKWkvHa1/SAcFolBEca1oN+mQ7eooNB
 github.com/lestrrat-go/option v1.0.1/go.mod h1:5ZHFbivi4xwXxhxY9XHDe2FHo6/Z7WWmtT7T5nBBp3I=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/rogpeppe/go-internal v1.15.0 h1:D0RCU5rMAp+SpgkiNdrjfJ+LX4J1M32V2NeCY7EJ6hc=
+github.com/rogpeppe/go-internal v1.15.0/go.mod h1:DrUVZyrJU+txYW5/1kwtXQSMFio52ZOxX7yM1VHvnxs=
 github.com/segmentio/asm v1.2.0 h1:9BQrFxC+YOHJlTlHGkTrFWf59nbL3XnCoFLTwDCI7ys=
 github.com/segmentio/asm v1.2.0/go.mod h1:BqMnlJP91P8d+4ibuonYZw9mfnzI9HfxselHZr5aAcs=
 github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
@@ -46,9 +53,9 @@ golang.org/x/sys v0.31.0 h1:ioabZlmFYtWhL+TRYpcnNlLwhyxaM9kWTDEmfnprqik=
 golang.org/x/sys v0.31.0/go.mod h1:BJP2sWEmIv4KK5OTEluFJCKSidICx8ciO85XgH3Ak8k=
 golang.org/x/text v0.29.0 h1:1neNs90w9YzJ9BocxfsQNHKuAT4pkghyXc4nhZ6sJvk=
 golang.org/x/text v0.29.0/go.mod h1:7MhJOA9CD2qZyOKYazxdYMF85OwPdEr9jTtBpO7ydH4=
-gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=
 gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

ingestion/internal/api/handler.go

@@ -483,6 +483,40 @@ func (h *Handler) BackfillRefs(w http.ResponseWriter, r *http.Request) {
 	writeJSON(w, map[string]int{"updated": n})
 }
 
+// Pending handles GET /pending — list raw/ notes awaiting promotion.
+func (h *Handler) Pending(w http.ResponseWriter, _ *http.Request) {
+	pending, err := ListPending(h.brainDir)
+	if err != nil {
+		h.logger.Error("pending failed", "err", err)
+		writeError(w, http.StatusInternalServerError, "pending error")
+		return
+	}
+	writeJSON(w, map[string]any{"pending": pending})
+}
+
+type promoteRequest struct {
+	Filename string `json:"filename"`
+	Wing     string `json:"wing"`
+	Hall     string `json:"hall"`
+	Slug     string `json:"slug,omitempty"`
+}
+
+// Promote handles POST /promote — move a raw/ note into the wiki. A bad
+// hall / collision / missing source is a 400 (caller error), not a 500.
+func (h *Handler) Promote(w http.ResponseWriter, r *http.Request) {
+	var req promoteRequest
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		writeError(w, http.StatusBadRequest, "invalid JSON")
+		return
+	}
+	rel, err := PromoteNote(h.brainDir, PromoteOptions(req))
+	if err != nil {
+		writeError(w, http.StatusBadRequest, err.Error())
+		return
+	}
+	writeJSON(w, map[string]string{"path": rel})
+}
+
 func writeJSON(w http.ResponseWriter, v any) {
 	w.Header().Set("Content-Type", "application/json")
 	json.NewEncoder(w).Encode(v) //nolint:errcheck

ingestion/internal/api/promote.go

@@ -0,0 +1,156 @@
+package api
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"regexp"
+	"sort"
+	"strings"
+	"time"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brain"
+)
+
+// PendingNote describes a raw/ note awaiting human promotion to the wiki.
+type PendingNote struct {
+	Filename  string `json:"filename"`
+	CreatedAt string `json:"created_at"`
+	SizeBytes int64  `json:"size_bytes"`
+	Excerpt   string `json:"excerpt"`
+}
+
+// datePrefix matches a leading YYYY-MM-DD- on a raw filename, stripped when
+// deriving the default promoted slug.
+var datePrefix = regexp.MustCompile(`^\d{4}-\d{2}-\d{2}-`)
+
+// ListPending returns the notes in brain/raw/ awaiting review, oldest-first
+// (natural review order). An absent raw/ dir yields an empty slice, not an
+// error. Only .md files are listed; tunnel-candidate files are skipped.
+func ListPending(brainDir string) ([]PendingNote, error) {
+	dir := filepath.Join(brainDir, "raw")
+	entries, err := os.ReadDir(dir)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return []PendingNote{}, nil
+		}
+		return nil, fmt.Errorf("read raw dir: %w", err)
+	}
+
+	out := make([]PendingNote, 0, len(entries))
+	for _, e := range entries {
+		if e.IsDir() || !strings.HasSuffix(e.Name(), ".md") || strings.HasPrefix(e.Name(), "tunnel-candidates-") {
+			continue
+		}
+		info, statErr := e.Info()
+		if statErr != nil {
+			continue
+		}
+		raw, readErr := os.ReadFile(filepath.Join(dir, e.Name()))
+		if readErr != nil {
+			continue
+		}
+		fm, body := parseFrontmatter(string(raw))
+		created := fm.get("created_at")
+		if created == "" {
+			created = info.ModTime().UTC().Format(time.RFC3339)
+		}
+		out = append(out, PendingNote{
+			Filename:  e.Name(),
+			CreatedAt: created,
+			SizeBytes: info.Size(),
+			Excerpt:   excerpt(body, 200),
+		})
+	}
+	sort.SliceStable(out, func(i, j int) bool { return out[i].CreatedAt < out[j].CreatedAt })
+	return out, nil
+}
+
+// PromoteOptions identifies a raw note to promote and its wiki destination.
+type PromoteOptions struct {
+	Filename string // basename in brain/raw/
+	Wing     string
+	Hall     string
+	Slug     string // optional; defaults to Filename minus date prefix + .md
+}
+
+// PromoteNote moves a note from brain/raw/ into the structured wiki: it
+// rewrites frontmatter (sets wing/hall/promoted_at, preserves created_at and
+// any custom fields), writes to brain/wiki/<wing>/<hall>/<slug>.md, deletes
+// the source, then rebuilds the wing index and runs auto-tunnel detection.
+//
+// It is atomic from the caller's view: validation (hall, wing, slug,
+// collision) happens before any filesystem change, and the source is deleted
+// only after the destination write succeeds (write-then-delete, never move).
+// Returns the promoted note's path relative to brainDir.
+func PromoteNote(brainDir string, opts PromoteOptions) (string, error) {
+	// Validate filename (basename only — no traversal) before touching fs.
+	base := filepath.Base(opts.Filename)
+	if base != opts.Filename || base == "." || base == ".." || strings.ContainsAny(opts.Filename, `/\`) {
+		return "", fmt.Errorf("invalid filename %q", opts.Filename)
+	}
+
+	slug := opts.Slug
+	if slug == "" {
+		slug = datePrefix.ReplaceAllString(strings.TrimSuffix(base, ".md"), "")
+	}
+	// NotePath validates hall + wing + slug; do this before reading anything.
+	dest, err := brain.NotePath(brainDir, opts.Wing, opts.Hall, slug)
+	if err != nil {
+		return "", err
+	}
+
+	src := filepath.Join(brainDir, "raw", base)
+	raw, err := os.ReadFile(src)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return "", fmt.Errorf("pending note %q does not exist in raw/", base)
+		}
+		return "", fmt.Errorf("read source: %w", err)
+	}
+
+	// Collision: never silently overwrite an existing promoted note.
+	if _, statErr := os.Stat(dest); statErr == nil {
+		rel, _ := filepath.Rel(brainDir, dest)
+		return "", fmt.Errorf("target %s already exists; choose a different slug", filepath.ToSlash(rel))
+	}
+
+	fm, body := parseFrontmatter(string(raw))
+	now := time.Now().UTC().Format(time.RFC3339)
+	fm.set("wing", brain.Sanitise(opts.Wing))
+	fm.set("hall", opts.Hall)
+	if fm.get("created_at") == "" {
+		fm.set("created_at", now)
+	}
+	fm.set("promoted_at", now)
+
+	if err := os.MkdirAll(filepath.Dir(dest), 0o755); err != nil {
+		return "", fmt.Errorf("create wing dir: %w", err)
+	}
+	// Write-then-delete: the source survives any write failure.
+	if err := os.WriteFile(dest, []byte(fm.render()+body), 0o644); err != nil {
+		return "", fmt.Errorf("write promoted note: %w", err)
+	}
+	if err := os.Remove(src); err != nil {
+		return "", fmt.Errorf("promoted note written but source removal failed: %w", err)
+	}
+
+	rel, _ := filepath.Rel(brainDir, dest)
+	relSlash := filepath.ToSlash(rel)
+
+	// Best-effort wiki upkeep — the note is already promoted.
+	_ = brain.BuildWingIndex(brainDir, opts.Wing)
+	_ = brain.AutoTunnel(brainDir, relSlash, body)
+
+	return relSlash, nil
+}
+
+// excerpt returns the first n runes of s, trimmed, single-spaced.
+func excerpt(s string, n int) string {
+	s = strings.TrimSpace(s)
+	r := []rune(s)
+	if len(r) > n {
+		r = r[:n]
+	}
+	return strings.TrimSpace(string(r))
+}

ingestion/internal/api/promote_test.go

@@ -0,0 +1,121 @@
+package api
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func writeRaw(t *testing.T, brainDir, name, content string) {
+	t.Helper()
+	dir := filepath.Join(brainDir, "raw")
+	require.NoError(t, os.MkdirAll(dir, 0o755))
+	require.NoError(t, os.WriteFile(filepath.Join(dir, name), []byte(content), 0o644))
+}
+
+func TestListPendingEmptyWhenAbsent(t *testing.T) {
+	got, err := ListPending(t.TempDir())
+	require.NoError(t, err, "absent raw/ is not an error")
+	assert.Empty(t, got)
+}
+
+func TestListPendingReturnsOldestFirstWithExcerpt(t *testing.T) {
+	dir := t.TempDir()
+	writeRaw(t, dir, "2026-06-02-newer.md", "---\ncreated_at: 2026-06-02T00:00:00Z\n---\nNewer body here.\n")
+	writeRaw(t, dir, "2026-06-01-older.md", "---\ncreated_at: 2026-06-01T00:00:00Z\n---\nOlder body content.\n")
+	// non-md ignored
+	writeRaw(t, dir, "notes.txt", "ignore me")
+
+	got, err := ListPending(dir)
+	require.NoError(t, err)
+	require.Len(t, got, 2)
+	assert.Equal(t, "2026-06-01-older.md", got[0].Filename, "oldest first")
+	assert.Equal(t, "2026-06-02-newer.md", got[1].Filename)
+	assert.Contains(t, got[0].Excerpt, "Older body content")
+	assert.NotContains(t, got[0].Excerpt, "---", "excerpt is body, not frontmatter")
+	assert.Positive(t, got[0].SizeBytes)
+}
+
+func TestPromoteHappyPath(t *testing.T) {
+	dir := t.TempDir()
+	writeRaw(t, dir, "2026-06-01-lejpa-decision.md",
+		"---\ncreated_at: 2026-06-01T09:00:00Z\ncustom_field: keep-me\n---\n# LeJEPA\n\nbody.\n")
+
+	rel, err := PromoteNote(dir, PromoteOptions{
+		Filename: "2026-06-01-lejpa-decision.md", Wing: "jepa-fx", Hall: "decisions",
+	})
+	require.NoError(t, err)
+	assert.Equal(t, "wiki/jepa-fx/decisions/lejpa-decision.md", rel, "slug defaults to filename minus date prefix")
+
+	// Source deleted.
+	_, statErr := os.Stat(filepath.Join(dir, "raw", "2026-06-01-lejpa-decision.md"))
+	assert.True(t, os.IsNotExist(statErr), "source removed after promote")
+
+	got, err := os.ReadFile(filepath.Join(dir, filepath.FromSlash(rel)))
+	require.NoError(t, err)
+	s := string(got)
+	assert.Contains(t, s, "wing: jepa-fx")
+	assert.Contains(t, s, "hall: decisions")
+	assert.Contains(t, s, "created_at: 2026-06-01T09:00:00Z", "original created_at preserved")
+	assert.Contains(t, s, "promoted_at:")
+	assert.Contains(t, s, "custom_field: keep-me", "custom frontmatter preserved")
+	assert.Contains(t, s, "# LeJEPA")
+}
+
+func TestPromoteExplicitSlug(t *testing.T) {
+	dir := t.TempDir()
+	writeRaw(t, dir, "2026-06-01-x.md", "body\n")
+	rel, err := PromoteNote(dir, PromoteOptions{Filename: "2026-06-01-x.md", Wing: "a", Hall: "facts", Slug: "custom-slug"})
+	require.NoError(t, err)
+	assert.Equal(t, "wiki/a/facts/custom-slug.md", rel)
+}
+
+func TestPromoteInvalidHallErrorsBeforeTouchingFS(t *testing.T) {
+	dir := t.TempDir()
+	writeRaw(t, dir, "2026-06-01-x.md", "body\n")
+	_, err := PromoteNote(dir, PromoteOptions{Filename: "2026-06-01-x.md", Wing: "a", Hall: "garbage"})
+	require.Error(t, err)
+	// Source untouched.
+	_, statErr := os.Stat(filepath.Join(dir, "raw", "2026-06-01-x.md"))
+	assert.NoError(t, statErr, "invalid hall must not delete or move the source")
+}
+
+func TestPromoteMissingSourceErrors(t *testing.T) {
+	_, err := PromoteNote(t.TempDir(), PromoteOptions{Filename: "ghost.md", Wing: "a", Hall: "facts"})
+	require.Error(t, err)
+}
+
+func TestPromoteSlugCollisionNoOverwrite(t *testing.T) {
+	dir := t.TempDir()
+	// Pre-existing target.
+	dest := filepath.Join(dir, "wiki", "a", "facts", "x.md")
+	require.NoError(t, os.MkdirAll(filepath.Dir(dest), 0o755))
+	require.NoError(t, os.WriteFile(dest, []byte("EXISTING\n"), 0o644))
+	writeRaw(t, dir, "2026-06-01-x.md", "NEW\n")
+
+	_, err := PromoteNote(dir, PromoteOptions{Filename: "2026-06-01-x.md", Wing: "a", Hall: "facts"})
+	require.Error(t, err, "collision must error, not overwrite")
+
+	got, _ := os.ReadFile(dest)
+	assert.Equal(t, "EXISTING\n", string(got), "target not overwritten")
+	_, statErr := os.Stat(filepath.Join(dir, "raw", "2026-06-01-x.md"))
+	assert.NoError(t, statErr, "source preserved on collision (atomic: no delete without write)")
+}
+
+func TestPromoteRejectsTraversalFilename(t *testing.T) {
+	_, err := PromoteNote(t.TempDir(), PromoteOptions{Filename: "../escape.md", Wing: "a", Hall: "facts"})
+	require.Error(t, err)
+}
+
+func TestPromoteRebuildsWingIndex(t *testing.T) {
+	dir := t.TempDir()
+	writeRaw(t, dir, "2026-06-01-x.md", "---\ntitle: X Note\n---\nbody\n")
+	_, err := PromoteNote(dir, PromoteOptions{Filename: "2026-06-01-x.md", Wing: "a", Hall: "facts"})
+	require.NoError(t, err)
+	idx, err := os.ReadFile(filepath.Join(dir, "wiki", "a", "_index.md"))
+	require.NoError(t, err, "wing _index regenerated")
+	assert.Contains(t, string(idx), "x", "promoted note appears in the index")
+}

ingestion/internal/audit/buffer.go

@@ -0,0 +1,167 @@
+package audit
+
+import (
+	"bufio"
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"sync"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/capture"
+)
+
+// FileBuffer is a durable, restart-surviving audit buffer backed by a
+// JSONL file: one {id, entry} record per line. It is the internal/public
+// tier fallback when loki is unreachable. Confirm rewrites the file
+// without the confirmed record, so a record is cleared only after its
+// central write is confirmed.
+//
+// Access is serialised by a mutex; the buffer is low-throughput (only
+// written during a loki outage), so a whole-file rewrite on Confirm is
+// acceptable and keeps the on-disk format trivially correct.
+type FileBuffer struct {
+	path string
+	mu   sync.Mutex
+}
+
+type bufferLine struct {
+	ID    string              `json:"id"`
+	Entry capture.AuditEntry  `json:"entry"`
+}
+
+// NewFileBuffer returns a buffer backed by path. The parent directory is
+// created if needed. The file itself is created lazily on first Append.
+func NewFileBuffer(path string) (*FileBuffer, error) {
+	if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+		return nil, fmt.Errorf("create buffer dir: %w", err)
+	}
+	return &FileBuffer{path: path}, nil
+}
+
+// Writable reports whether the buffer file can be appended to. It probes
+// by opening the file for append (creating it if absent) — the same
+// operation Append performs — so Reserve's check matches Append's reality.
+func (b *FileBuffer) Writable() error {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	f, err := os.OpenFile(b.path, os.O_CREATE|os.O_APPEND|os.O_WRONLY, 0o644)
+	if err != nil {
+		return err
+	}
+	return f.Close()
+}
+
+// Append durably writes one audit record. The ID is derived from the
+// content + timestamp so it is stable and unique per record.
+func (b *FileBuffer) Append(e capture.AuditEntry) error {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+
+	line := bufferLine{ID: recordID(e), Entry: e}
+	data, err := json.Marshal(line)
+	if err != nil {
+		return fmt.Errorf("marshal buffer line: %w", err)
+	}
+	f, err := os.OpenFile(b.path, os.O_CREATE|os.O_APPEND|os.O_WRONLY, 0o644)
+	if err != nil {
+		return err
+	}
+	defer func() { _ = f.Close() }()
+	if _, err := f.Write(append(data, '\n')); err != nil {
+		return err
+	}
+	return f.Sync()
+}
+
+// Pending reads all buffered records. A missing file means none.
+func (b *FileBuffer) Pending() ([]Buffered, error) {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	return b.readAllLocked()
+}
+
+func (b *FileBuffer) readAllLocked() ([]Buffered, error) {
+	f, err := os.Open(b.path)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return nil, nil
+		}
+		return nil, err
+	}
+	defer func() { _ = f.Close() }()
+
+	var out []Buffered
+	sc := bufio.NewScanner(f)
+	sc.Buffer(make([]byte, 0, 64*1024), 1024*1024)
+	for sc.Scan() {
+		raw := sc.Bytes()
+		if len(raw) == 0 {
+			continue
+		}
+		var l bufferLine
+		if err := json.Unmarshal(raw, &l); err != nil {
+			return nil, fmt.Errorf("parse buffer line: %w", err)
+		}
+		out = append(out, Buffered(l))
+	}
+	return out, sc.Err()
+}
+
+// Confirm removes a single record after its central write is confirmed, by
+// rewriting the file without it. Unknown IDs are a no-op.
+func (b *FileBuffer) Confirm(id string) error {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+
+	all, err := b.readAllLocked()
+	if err != nil {
+		return err
+	}
+	tmp := b.path + ".tmp"
+	f, err := os.OpenFile(tmp, os.O_CREATE|os.O_TRUNC|os.O_WRONLY, 0o644)
+	if err != nil {
+		return err
+	}
+	w := bufio.NewWriter(f)
+	kept := 0
+	for _, rec := range all {
+		if rec.ID == id {
+			continue
+		}
+		data, _ := json.Marshal(bufferLine(rec))
+		if _, err := w.Write(append(data, '\n')); err != nil {
+			_ = f.Close()
+			return err
+		}
+		kept++
+	}
+	if err := w.Flush(); err != nil {
+		_ = f.Close()
+		return err
+	}
+	if err := f.Sync(); err != nil {
+		_ = f.Close()
+		return err
+	}
+	if err := f.Close(); err != nil {
+		return err
+	}
+	// Empty buffer → remove the file entirely so Pending sees nothing.
+	if kept == 0 {
+		_ = os.Remove(tmp)
+		return os.Remove(b.path)
+	}
+	return os.Rename(tmp, b.path)
+}
+
+// recordID is a stable per-record identifier: sha256 of the principal,
+// timestamp, and item list. Distinct captures never collide; the same
+// buffered record always hashes the same.
+func recordID(e capture.AuditEntry) string {
+	h := sha256.New()
+	_, _ = fmt.Fprintf(h, "%s|%s|%v|%s", e.Principal, e.Timestamp.UTC().Format("2006-01-02T15:04:05.000000000Z07:00"), e.Items, e.SessionRef)
+	return hex.EncodeToString(h.Sum(nil))[:16]
+}

ingestion/internal/audit/degrading.go

@@ -0,0 +1,96 @@
+package audit
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/capture"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/classification"
+)
+
+// Central is the central audit substrate (loki). Ready is a cheap
+// reachability probe used by the pre-write reserve; Push writes a record.
+type Central interface {
+	Ready(ctx context.Context) error
+	Push(ctx context.Context, e capture.AuditEntry) error
+}
+
+// Buffer is the durable local fallback for internal/public-tier records
+// when the central sink is unreachable. It must survive process restart.
+type Buffer interface {
+	// Writable reports whether the buffer can currently be appended to.
+	Writable() error
+	Append(e capture.AuditEntry) error
+	// Pending returns buffered records awaiting reconciliation, each with a
+	// stable ID used to Confirm (delete) it after a confirmed central write.
+	Pending() ([]Buffered, error)
+	Confirm(id string) error
+}
+
+// Buffered is a buffered audit record plus its stable buffer ID.
+type Buffered struct {
+	ID    string
+	Entry capture.AuditEntry
+}
+
+// Notifier raises an out-of-band alert (ntfy) about a degraded state.
+type Notifier interface {
+	Notify(ctx context.Context, msg string) error
+}
+
+// DegradingSink is the classification-aware AuditSink (§4.4):
+//
+//   - central reachable → AuditCentral (all tiers).
+//   - central down + confidential → refuse (no buffer): confidential must
+//     be centrally auditable at write time.
+//   - central down + internal/public + buffer writable → AuditBuffered.
+//   - central down + (confidential, or buffer not writable) → refuse (floor).
+//
+// The decision is made in Reserve, before any write; Record then executes it.
+type DegradingSink struct {
+	central  Central
+	buffer   Buffer
+	notifier Notifier
+}
+
+// NewDegradingSink wires the central sink, durable buffer, and notifier.
+func NewDegradingSink(central Central, buffer Buffer, notifier Notifier) *DegradingSink {
+	return &DegradingSink{central: central, buffer: buffer, notifier: notifier}
+}
+
+// Reserve decides, before any write, how the capture will be audited — or
+// returns an error to refuse it.
+func (d *DegradingSink) Reserve(ctx context.Context, level classification.Level) (capture.AuditOutcome, error) {
+	if err := d.central.Ready(ctx); err == nil {
+		return capture.AuditCentral, nil
+	}
+	// Central sink is down.
+	if level == classification.Confidential {
+		return 0, fmt.Errorf("confidential capture requires the central audit sink, which is unreachable")
+	}
+	if err := d.buffer.Writable(); err != nil {
+		// Floor: neither central nor local buffer can record the audit.
+		return 0, fmt.Errorf("audit floor: central sink down and local buffer unwritable: %w", err)
+	}
+	return capture.AuditBuffered, nil
+}
+
+// Record persists the entry per the reserved outcome. For AuditBuffered it
+// also fires the degraded-state alert.
+func (d *DegradingSink) Record(ctx context.Context, e capture.AuditEntry, outcome capture.AuditOutcome) error {
+	switch outcome {
+	case capture.AuditBuffered:
+		if err := d.buffer.Append(e); err != nil {
+			return fmt.Errorf("buffer audit record: %w", err)
+		}
+		// Best-effort alert; the record is already durably buffered.
+		if d.notifier != nil {
+			_ = d.notifier.Notify(ctx, fmt.Sprintf(
+				"capture audit BUFFERED LOCALLY (loki unreachable) — principal=%s class=%s items=%d",
+				e.Principal, e.EffectiveClassification, len(e.Items)))
+		}
+		return nil
+	default:
+		return d.central.Push(ctx, e)
+	}
+}

ingestion/internal/audit/degrading_test.go

@@ -0,0 +1,191 @@
+package audit_test
+
+import (
+	"context"
+	"errors"
+	"path/filepath"
+	"testing"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/audit"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/capture"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/classification"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// --- fakes ---
+
+type fakeCentral struct {
+	down    bool
+	pushed  []capture.AuditEntry
+	pushErr error
+}
+
+func (f *fakeCentral) Ready(context.Context) error {
+	if f.down {
+		return errors.New("loki down")
+	}
+	return nil
+}
+
+func (f *fakeCentral) Push(_ context.Context, e capture.AuditEntry) error {
+	if f.pushErr != nil {
+		return f.pushErr
+	}
+	f.pushed = append(f.pushed, e)
+	return nil
+}
+
+type fakeNotifier struct{ msgs []string }
+
+func (f *fakeNotifier) Notify(_ context.Context, msg string) error {
+	f.msgs = append(f.msgs, msg)
+	return nil
+}
+
+// unwritableBuffer always reports it cannot be written (floor condition).
+type unwritableBuffer struct{}
+
+func (unwritableBuffer) Writable() error                       { return errors.New("disk full") }
+func (unwritableBuffer) Append(capture.AuditEntry) error       { return errors.New("disk full") }
+func (unwritableBuffer) Pending() ([]audit.Buffered, error)    { return nil, nil }
+func (unwritableBuffer) Confirm(string) error                  { return nil }
+
+func newFileBuffer(t *testing.T) *audit.FileBuffer {
+	t.Helper()
+	b, err := audit.NewFileBuffer(filepath.Join(t.TempDir(), "audit-buffer.jsonl"))
+	require.NoError(t, err)
+	return b
+}
+
+func entry(principal string) capture.AuditEntry {
+	return capture.AuditEntry{Principal: principal, EffectiveClassification: "internal", Items: []string{"insight:x"}}
+}
+
+// --- Reserve: classification-aware decision ---
+
+func TestReserveCentralUpGrantsCentral(t *testing.T) {
+	d := audit.NewDegradingSink(&fakeCentral{}, newFileBuffer(t), &fakeNotifier{})
+	for _, lvl := range []classification.Level{classification.Public, classification.Internal, classification.Confidential} {
+		out, err := d.Reserve(context.Background(), lvl)
+		require.NoError(t, err)
+		assert.Equal(t, capture.AuditCentral, out)
+	}
+}
+
+func TestReserveConfidentialSinkDownRefuses(t *testing.T) {
+	d := audit.NewDegradingSink(&fakeCentral{down: true}, newFileBuffer(t), &fakeNotifier{})
+	_, err := d.Reserve(context.Background(), classification.Confidential)
+	require.Error(t, err, "confidential + sink down → refuse, no buffer")
+}
+
+func TestReserveInternalSinkDownBuffers(t *testing.T) {
+	d := audit.NewDegradingSink(&fakeCentral{down: true}, newFileBuffer(t), &fakeNotifier{})
+	out, err := d.Reserve(context.Background(), classification.Internal)
+	require.NoError(t, err)
+	assert.Equal(t, capture.AuditBuffered, out)
+}
+
+func TestReserveFloorRefusesWhenNothingCanRecord(t *testing.T) {
+	d := audit.NewDegradingSink(&fakeCentral{down: true}, unwritableBuffer{}, &fakeNotifier{})
+	_, err := d.Reserve(context.Background(), classification.Internal)
+	require.Error(t, err, "central down AND buffer unwritable → floor refuse")
+}
+
+// --- Record: executes the reserved outcome ---
+
+func TestRecordCentralPushes(t *testing.T) {
+	c := &fakeCentral{}
+	d := audit.NewDegradingSink(c, newFileBuffer(t), &fakeNotifier{})
+	require.NoError(t, d.Record(context.Background(), entry("p"), capture.AuditCentral))
+	assert.Len(t, c.pushed, 1)
+}
+
+func TestRecordBufferedAppendsAndNotifies(t *testing.T) {
+	buf := newFileBuffer(t)
+	nt := &fakeNotifier{}
+	d := audit.NewDegradingSink(&fakeCentral{down: true}, buf, nt)
+	require.NoError(t, d.Record(context.Background(), entry("p"), capture.AuditBuffered))
+
+	pending, err := buf.Pending()
+	require.NoError(t, err)
+	assert.Len(t, pending, 1)
+	assert.NotEmpty(t, nt.msgs, "degraded state alerts via ntfy")
+}
+
+// --- FileBuffer durability + Confirm ---
+
+func TestFileBufferSurvivesRestart(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "buf.jsonl")
+	b1, err := audit.NewFileBuffer(path)
+	require.NoError(t, err)
+	require.NoError(t, b1.Append(entry("p1")))
+	require.NoError(t, b1.Append(entry("p2")))
+
+	// "restart": a fresh FileBuffer over the same file sees the records.
+	b2, err := audit.NewFileBuffer(path)
+	require.NoError(t, err)
+	pending, err := b2.Pending()
+	require.NoError(t, err)
+	assert.Len(t, pending, 2)
+}
+
+func TestFileBufferConfirmRemovesOnlyThatRecord(t *testing.T) {
+	buf := newFileBuffer(t)
+	require.NoError(t, buf.Append(entry("keep")))
+	require.NoError(t, buf.Append(entry("drop")))
+
+	pending, _ := buf.Pending()
+	require.Len(t, pending, 2)
+	var dropID string
+	for _, p := range pending {
+		if p.Entry.Principal == "drop" {
+			dropID = p.ID
+		}
+	}
+	require.NoError(t, buf.Confirm(dropID))
+
+	after, _ := buf.Pending()
+	require.Len(t, after, 1)
+	assert.Equal(t, "keep", after[0].Entry.Principal)
+}
+
+// --- Reconcile ---
+
+func TestReconcileReplaysAndClearsOnlyAfterConfirmedWrite(t *testing.T) {
+	buf := newFileBuffer(t)
+	require.NoError(t, buf.Append(entry("a")))
+	require.NoError(t, buf.Append(entry("b")))
+	c := &fakeCentral{} // up
+	nt := &fakeNotifier{}
+
+	n, err := audit.Reconcile(context.Background(), c, buf, nt)
+	require.NoError(t, err)
+	assert.Equal(t, 2, n)
+	assert.Len(t, c.pushed, 2, "buffered records replayed to central")
+
+	pending, _ := buf.Pending()
+	assert.Empty(t, pending, "buffer cleared after confirmed central writes")
+}
+
+func TestReconcileNoopWhenCentralDown(t *testing.T) {
+	buf := newFileBuffer(t)
+	require.NoError(t, buf.Append(entry("a")))
+	n, err := audit.Reconcile(context.Background(), &fakeCentral{down: true}, buf, &fakeNotifier{})
+	require.NoError(t, err)
+	assert.Equal(t, 0, n)
+	pending, _ := buf.Pending()
+	assert.Len(t, pending, 1, "records stay buffered while central is down")
+}
+
+func TestReconcileKeepsRecordWhenPushFails(t *testing.T) {
+	buf := newFileBuffer(t)
+	require.NoError(t, buf.Append(entry("a")))
+	// Ready ok but Push fails → record must remain buffered (not lost).
+	c := &fakeCentral{pushErr: errors.New("push rejected")}
+	n, err := audit.Reconcile(context.Background(), c, buf, &fakeNotifier{})
+	require.NoError(t, err)
+	assert.Equal(t, 0, n)
+	pending, _ := buf.Pending()
+	assert.Len(t, pending, 1)
+}

ingestion/internal/audit/loki.go

@@ -0,0 +1,99 @@
+package audit
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/capture"
+)
+
+// LokiCentral pushes capture audit records to a Grafana Loki instance via
+// its push API, and probes readiness via /ready. It is the central audit
+// substrate behind DegradingSink.
+type LokiCentral struct {
+	baseURL string
+	labels  map[string]string
+	http    *http.Client
+}
+
+// NewLokiCentral constructs a LokiCentral for the given base URL (e.g.
+// http://loki:3100). Returns nil when baseURL is empty so callers can
+// treat missing config as "no central sink" with a single nil check.
+func NewLokiCentral(baseURL string) *LokiCentral {
+	if baseURL == "" {
+		return nil
+	}
+	return &LokiCentral{
+		baseURL: strings.TrimRight(baseURL, "/"),
+		labels:  map[string]string{"service": "brain-capture", "kind": "audit"},
+		http:    &http.Client{Timeout: 10 * time.Second},
+	}
+}
+
+// Ready probes Loki's readiness endpoint.
+func (l *LokiCentral) Ready(ctx context.Context) error {
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, l.baseURL+"/ready", nil)
+	if err != nil {
+		return err
+	}
+	resp, err := l.http.Do(req)
+	if err != nil {
+		return fmt.Errorf("loki not ready: %w", err)
+	}
+	defer func() { _ = resp.Body.Close() }()
+	if resp.StatusCode != http.StatusOK {
+		return fmt.Errorf("loki not ready: status %d", resp.StatusCode)
+	}
+	return nil
+}
+
+// pushPayload is the Loki push API body: one stream, one entry whose line
+// is the JSON-encoded audit record.
+type pushPayload struct {
+	Streams []lokiStream `json:"streams"`
+}
+
+type lokiStream struct {
+	Stream map[string]string `json:"stream"`
+	Values [][2]string       `json:"values"`
+}
+
+// Push writes one audit record to Loki as a structured log line.
+func (l *LokiCentral) Push(ctx context.Context, e capture.AuditEntry) error {
+	line, err := json.Marshal(e)
+	if err != nil {
+		return fmt.Errorf("marshal audit entry: %w", err)
+	}
+	ts := e.Timestamp
+	if ts.IsZero() {
+		ts = time.Now()
+	}
+	body, err := json.Marshal(pushPayload{Streams: []lokiStream{{
+		Stream: l.labels,
+		Values: [][2]string{{strconv.FormatInt(ts.UTC().UnixNano(), 10), string(line)}},
+	}}})
+	if err != nil {
+		return err
+	}
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost,
+		l.baseURL+"/loki/api/v1/push", bytes.NewReader(body))
+	if err != nil {
+		return err
+	}
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := l.http.Do(req)
+	if err != nil {
+		return fmt.Errorf("loki push: %w", err)
+	}
+	defer func() { _ = resp.Body.Close() }()
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		return fmt.Errorf("loki push: status %d", resp.StatusCode)
+	}
+	return nil
+}

ingestion/internal/audit/loki_ntfy_test.go

@@ -0,0 +1,86 @@
+package audit_test
+
+import (
+	"context"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/audit"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/capture"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestLokiReadyAndPush(t *testing.T) {
+	var pushBody string
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		switch r.URL.Path {
+		case "/ready":
+			w.WriteHeader(http.StatusOK)
+		case "/loki/api/v1/push":
+			b, _ := io.ReadAll(r.Body)
+			pushBody = string(b)
+			w.WriteHeader(http.StatusNoContent)
+		default:
+			w.WriteHeader(http.StatusNotFound)
+		}
+	}))
+	defer srv.Close()
+
+	c := audit.NewLokiCentral(srv.URL)
+	require.NotNil(t, c)
+	require.NoError(t, c.Ready(context.Background()))
+
+	err := c.Push(context.Background(), capture.AuditEntry{
+		Principal: "koala-cli", EffectiveClassification: "internal", Items: []string{"insight:x"},
+	})
+	require.NoError(t, err)
+	assert.Contains(t, pushBody, "streams")
+	assert.Contains(t, pushBody, "koala-cli", "audit entry serialised into the loki line")
+}
+
+func TestLokiReadyFailsWhenDown(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.WriteHeader(http.StatusServiceUnavailable)
+	}))
+	defer srv.Close()
+	require.Error(t, audit.NewLokiCentral(srv.URL).Ready(context.Background()))
+}
+
+func TestLokiNilWhenUnconfigured(t *testing.T) {
+	assert.Nil(t, audit.NewLokiCentral(""))
+}
+
+func TestNtfyNotify(t *testing.T) {
+	var gotBody, gotAuth string
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		b, _ := io.ReadAll(r.Body)
+		gotBody = string(b)
+		gotAuth = r.Header.Get("Authorization")
+		w.WriteHeader(http.StatusOK)
+	}))
+	defer srv.Close()
+
+	n := audit.NewNtfyNotifier(srv.URL, "ntfy-token")
+	require.NotNil(t, n)
+	require.NoError(t, n.Notify(context.Background(), "audit buffered locally"))
+	assert.Contains(t, gotBody, "audit buffered locally")
+	assert.Equal(t, "Bearer ntfy-token", gotAuth)
+}
+
+func TestNtfyDoesNotLeakTokenOnError(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.WriteHeader(http.StatusInternalServerError)
+	}))
+	defer srv.Close()
+	err := audit.NewNtfyNotifier(srv.URL, "secret-token").Notify(context.Background(), "x")
+	require.Error(t, err)
+	assert.False(t, strings.Contains(err.Error(), "secret-token"), "token must not leak into errors")
+}
+
+func TestNtfyNilWhenUnconfigured(t *testing.T) {
+	assert.Nil(t, audit.NewNtfyNotifier("", "tok"))
+}

ingestion/internal/audit/ntfy.go

@@ -0,0 +1,55 @@
+package audit
+
+import (
+	"context"
+	"fmt"
+	"net/http"
+	"strings"
+	"time"
+)
+
+// NtfyNotifier posts alerts to an ntfy topic URL. Used to surface a
+// degraded audit state (records buffered locally during a loki outage).
+type NtfyNotifier struct {
+	topicURL string
+	token    string
+	http     *http.Client
+}
+
+// NewNtfyNotifier constructs a notifier for the given ntfy topic URL
+// (e.g. https://ntfy.sh/my-topic). token is an optional bearer for
+// protected ntfy instances; it is held here and only sent in the
+// Authorization header, never logged. Returns nil when topicURL is empty.
+func NewNtfyNotifier(topicURL, token string) *NtfyNotifier {
+	if topicURL == "" {
+		return nil
+	}
+	return &NtfyNotifier{
+		topicURL: strings.TrimRight(topicURL, "/"),
+		token:    token,
+		http:     &http.Client{Timeout: 10 * time.Second},
+	}
+}
+
+// Notify posts a message to the ntfy topic.
+func (n *NtfyNotifier) Notify(ctx context.Context, msg string) error {
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, n.topicURL, strings.NewReader(msg))
+	if err != nil {
+		return err
+	}
+	req.Header.Set("Title", "brain-capture audit degraded")
+	req.Header.Set("Priority", "high")
+	req.Header.Set("Tags", "warning,brain")
+	if n.token != "" {
+		req.Header.Set("Authorization", "Bearer "+n.token)
+	}
+	resp, err := n.http.Do(req)
+	if err != nil {
+		return fmt.Errorf("ntfy notify: %w", err)
+	}
+	defer func() { _ = resp.Body.Close() }()
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		return fmt.Errorf("ntfy notify: status %d", resp.StatusCode)
+	}
+	return nil
+}

ingestion/internal/audit/reconcile.go

@@ -0,0 +1,65 @@
+package audit
+
+import (
+	"context"
+	"fmt"
+	"log/slog"
+	"time"
+)
+
+// Reconcile replays locally-buffered audit records to the central sink
+// when it is reachable again. A record is removed from the buffer ONLY
+// after its central write is confirmed, so a crash mid-reconcile re-plays
+// rather than loses. Returns the number of records reconciled.
+//
+// A no-op (0, nil) when the central sink is still unreachable or the
+// buffer is empty.
+func Reconcile(ctx context.Context, central Central, buffer Buffer, notifier Notifier) (int, error) {
+	if err := central.Ready(ctx); err != nil {
+		return 0, nil // still down; try again next tick
+	}
+	pending, err := buffer.Pending()
+	if err != nil {
+		return 0, fmt.Errorf("read buffer: %w", err)
+	}
+	reconciled := 0
+	for _, rec := range pending {
+		if err := central.Push(ctx, rec.Entry); err != nil {
+			// Central went away mid-drain; stop and keep the rest buffered.
+			break
+		}
+		if err := buffer.Confirm(rec.ID); err != nil {
+			return reconciled, fmt.Errorf("confirm buffered record %s: %w", rec.ID, err)
+		}
+		reconciled++
+	}
+	if reconciled > 0 && notifier != nil {
+		_ = notifier.Notify(ctx, fmt.Sprintf("reconciled %d buffered capture audit record(s) to loki", reconciled))
+	}
+	return reconciled, nil
+}
+
+// StartReconcile runs Reconcile on a ticker until ctx is cancelled. It is
+// the recovery half of the degrade-and-buffer path; pair it with a
+// DegradingSink sharing the same buffer + central.
+func StartReconcile(ctx context.Context, central Central, buffer Buffer, notifier Notifier, interval time.Duration) {
+	if interval <= 0 {
+		interval = time.Minute
+	}
+	go func() {
+		t := time.NewTicker(interval)
+		defer t.Stop()
+		for {
+			select {
+			case <-ctx.Done():
+				return
+			case <-t.C:
+				if n, err := Reconcile(ctx, central, buffer, notifier); err != nil {
+					slog.Warn("audit reconcile failed", "err", err)
+				} else if n > 0 {
+					slog.Info("audit reconcile", "reconciled", n)
+				}
+			}
+		}
+	}()
+}

ingestion/internal/audit/slog.go

@@ -11,11 +11,14 @@ import (
 	"log/slog"
 
 	"github.com/mathiasbq/hyperguild/ingestion/internal/capture"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/classification"
 )
 
-// SlogSink records audit entries to an slog.Logger. It never fails, so it
+// SlogSink records audit entries to an slog.Logger. It never fails and is
-// does not exercise the I5 floor (refuse-if-unauditable) — that is #54's
+// always centrally available, so its Reserve always grants AuditCentral —
-// loki+buffer sink. A nil logger falls back to slog.Default().
+// it does not exercise the I5 degradation/floor. That is DegradingSink's
+// job (loki + durable buffer). SlogSink is the default for deployments
+// without a loki endpoint configured. A nil logger ⇒ slog.Default().
 type SlogSink struct {
 	logger *slog.Logger
 }
@@ -28,10 +31,15 @@ func NewSlogSink(logger *slog.Logger) *SlogSink {
 	return &SlogSink{logger: logger}
 }
 
+// Reserve always grants central recording — slog is always available.
+func (s *SlogSink) Reserve(_ context.Context, _ classification.Level) (capture.AuditOutcome, error) {
+	return capture.AuditCentral, nil
+}
+
 // Record emits the audit entry at info level. Security events, when
 // present, are logged at warn level so they surface independently of the
 // routine audit stream.
-func (s *SlogSink) Record(_ context.Context, e capture.AuditEntry) error {
+func (s *SlogSink) Record(_ context.Context, e capture.AuditEntry, _ capture.AuditOutcome) error {
 	s.logger.Info("capture audit",
 		"principal", e.Principal,
 		"actor", e.Actor,

ingestion/internal/audit/slog_test.go

@@ -22,7 +22,7 @@ func TestSlogSinkRecordsEntryAndSecurityEvents(t *testing.T) {
 		EffectiveClassification: "confidential",
 		Items:                   []string{"insight:wiki/a/facts/x.md"},
 		SecurityEvents:          []string{"asserted-vs-derived origin mismatch"},
-	})
+	}, capture.AuditCentral)
 	require.NoError(t, err)
 
 	out := buf.String()
@@ -36,6 +36,6 @@ func TestSlogSinkRecordsEntryAndSecurityEvents(t *testing.T) {
 func TestSlogSinkNilLoggerDefaults(t *testing.T) {
 	// nil logger must not panic.
 	require.NotPanics(t, func() {
-		_ = audit.NewSlogSink(nil).Record(context.Background(), capture.AuditEntry{})
+		_ = audit.NewSlogSink(nil).Record(context.Background(), capture.AuditEntry{}, capture.AuditCentral)
 	})
 }

ingestion/internal/capture/entities.go

@@ -140,4 +140,9 @@ type CaptureReceipt struct {
 	Errors                  []ItemError     `json:"errors"`
 	EffectiveClassification string          `json:"effective_classification,omitempty"`
 	DryRun                  bool            `json:"dry_run"`
+	// AuditBuffered is true when the central audit sink was unreachable and
+	// this capture's audit record was written to the durable local buffer
+	// instead (internal/public tier). Surfaces the degraded state to the
+	// caller per §4.4.
+	AuditBuffered bool `json:"audit_buffered,omitempty"`
 }

ingestion/internal/capture/ports.go

@@ -96,9 +96,31 @@ type AuditEntry struct {
 	SecurityEvents          []string
 }
 
-// AuditSink records the audit entry. The classification-aware
+// AuditOutcome is how a capture's audit record was (or will be) persisted.
-// degradation/refusal policy (confidential fails closed, internal
+type AuditOutcome int
-// degrades) is the caller's concern in #54; this port just records.
+
+const (
+	// AuditCentral means the record goes to the central sink (loki).
+	AuditCentral AuditOutcome = iota
+	// AuditBuffered means the central sink was unreachable and the record
+	// is written to a durable local buffer for later reconciliation
+	// (internal/public tier only).
+	AuditBuffered
+)
+
+// AuditSink is the two-phase, classification-aware audit port (I5, §4.4).
+//
+// Reserve runs BEFORE any write and decides whether the capture can be
+// audited at its effective classification: it returns the outcome to use,
+// or an error to refuse the capture before anything is written
+// (confidential + central sink down → refuse; the all-tiers floor when
+// nothing can record → refuse). Record runs AFTER the writes and persists
+// the final entry per the reserved outcome.
+//
+// Splitting reserve from record is what lets "confidential + sink-down →
+// refuse before any write" be literally true while the record itself
+// (which lists what landed) is necessarily written afterwards.
 type AuditSink interface {
-	Record(ctx context.Context, e AuditEntry) error
+	Reserve(ctx context.Context, level classification.Level) (AuditOutcome, error)
+	Record(ctx context.Context, e AuditEntry, outcome AuditOutcome) error
 }

ingestion/internal/capture/service.go

@@ -39,6 +39,12 @@ var validActions = map[string]bool{"create": true, "close": true, "comment": tru
 // REST adapter maps it to HTTP 403. Callers test with errors.Is.
 var ErrSovereigntyRefused = fmt.Errorf("capture refused by I1 sovereignty gate")
 
+// ErrAuditUnavailable is returned when the I5 audit gate refuses a capture
+// before any write: a confidential capture whose central audit sink is
+// unreachable, or the all-tiers floor where nothing can record the audit.
+// The REST adapter maps it to HTTP 503. Callers test with errors.Is.
+var ErrAuditUnavailable = fmt.Errorf("capture refused: audit substrate unavailable")
+
 // assertedZoneMismatch returns a security-event string when the caller's
 // harness label asserts a trust zone that contradicts the server-derived
 // origin. A harness label that names no zone (the normal case, e.g.
@@ -105,7 +111,7 @@ func (s *Service) Capture(ctx context.Context, in CaptureInput) (CaptureReceipt,
 			EffectiveClassification: effective.String(),
 			Items:                   nil, // refused before any write
 			SecurityEvents:          append(securityEvents, "I1 refusal: confidential capture via us-nexus origin"),
-		})
+		}, AuditCentral)
 		return CaptureReceipt{}, fmt.Errorf("%w: effective classification confidential through %s origin",
 			ErrSovereigntyRefused, in.Context.Origin)
 	}
@@ -131,6 +137,16 @@ func (s *Service) Capture(ctx context.Context, in CaptureInput) (CaptureReceipt,
 		return receipt, nil
 	}
 
+	// I5 audit gate: decide BEFORE any write whether this capture can be
+	// audited at its effective classification. Confidential + central sink
+	// down → refuse here, before writing anything; the all-tiers floor
+	// (nothing can record) likewise refuses. Internal/public degrade to the
+	// durable local buffer (signalled by AuditBuffered).
+	outcome, err := s.audit.Reserve(ctx, effective)
+	if err != nil {
+		return CaptureReceipt{}, fmt.Errorf("%w: %v", ErrAuditUnavailable, err)
+	}
+
 	var landed []string
 
 	for i, ins := range in.Insights {
@@ -163,9 +179,9 @@ func (s *Service) Capture(ctx context.Context, in CaptureInput) (CaptureReceipt,
 		}
 	}
 
-	// I5: emit a request-level audit record of exactly what landed.
+	// I5: persist the request-level audit record of exactly what landed,
-	// Best-effort here; the classification-aware refusal/degradation
+	// using the outcome reserved before the writes. AuditBuffered surfaces
-	// policy is #54.
+	// the degraded (locally-buffered) state on the receipt.
 	if err := s.audit.Record(ctx, AuditEntry{
 		Timestamp:               s.now().UTC(),
 		Principal:               in.Context.Principal,
@@ -175,9 +191,12 @@ func (s *Service) Capture(ctx context.Context, in CaptureInput) (CaptureReceipt,
 		EffectiveClassification: effective.String(),
 		Items:                   landed,
 		SecurityEvents:          securityEvents,
-	}); err != nil {
+	}, outcome); err != nil {
 		receipt.Errors = append(receipt.Errors, ItemError{Item: "audit", Error: err.Error()})
 	}
+	if outcome == AuditBuffered {
+		receipt.AuditBuffered = true
+	}
 
 	return receipt, nil
 }

ingestion/internal/capture/service_test.go

@@ -113,10 +113,19 @@ func (p fakePolicy) Derive(t classification.Target) classification.Level {
 
 type fakeAudit struct {
 	entries     []AuditEntry
-	err     error
+	err         error // Record error
+	reserveErr  error // Reserve error (refuse before write)
+	reserveMode AuditOutcome
 }
 
-func (f *fakeAudit) Record(_ context.Context, e AuditEntry) error {
+func (f *fakeAudit) Reserve(_ context.Context, _ classification.Level) (AuditOutcome, error) {
+	if f.reserveErr != nil {
+		return 0, f.reserveErr
+	}
+	return f.reserveMode, nil
+}
+
+func (f *fakeAudit) Record(_ context.Context, e AuditEntry, _ AuditOutcome) error {
 	if f.err != nil {
 		return f.err
 	}
@@ -408,3 +417,55 @@ func TestCaptureInternalViaUSNexusAllowed(t *testing.T) {
 	require.NoError(t, err)
 	assert.True(t, rec.Insights[0].OK)
 }
+
+// --- I5 audit gate (#54) ---
+
+func TestCaptureRefusesWhenAuditReserveFails(t *testing.T) {
+	// Reserve refusing (e.g. confidential + central sink down, or the floor)
+	// aborts the capture before any write.
+	b := &fakeBrain{}
+	tr := &fakeTracker{}
+	au := &fakeAudit{reserveErr: errors.New("central sink unreachable")}
+	svc := newSvc(b, tr, nil, fakePolicy{}, au)
+
+	_, err := svc.Capture(context.Background(), CaptureInput{
+		Context:  baseCtx(),
+		Insights: []Insight{{Text: "x", Wing: "hyperguild", Hall: "facts"}},
+	})
+	require.Error(t, err)
+	assert.ErrorIs(t, err, ErrAuditUnavailable)
+	assert.Empty(t, b.writes, "nothing written when audit unavailable")
+	assert.Empty(t, tr.created)
+}
+
+func TestCaptureFlagsLocallyBufferedAudit(t *testing.T) {
+	// Reserve returns AuditBuffered (internal/public, central down) → capture
+	// proceeds and the receipt flags the degraded audit state.
+	b := &fakeBrain{}
+	au := &fakeAudit{reserveMode: AuditBuffered}
+	svc := newSvc(b, &fakeTracker{}, nil, fakePolicy{}, au)
+
+	rec, err := svc.Capture(context.Background(), CaptureInput{
+		Context:  baseCtx(),
+		Insights: []Insight{{Text: "x", Wing: "hyperguild", Hall: "facts"}},
+	})
+	require.NoError(t, err)
+	assert.True(t, rec.Insights[0].OK, "capture proceeds on degraded audit")
+	assert.True(t, rec.AuditBuffered, "receipt flags locally-buffered audit")
+	require.Len(t, au.entries, 1)
+}
+
+func TestCaptureDryRunSkipsAuditGate(t *testing.T) {
+	// dry_run must not even probe the audit sink (writes nothing anywhere).
+	au := &fakeAudit{reserveErr: errors.New("would refuse")}
+	svc := newSvc(&fakeBrain{}, &fakeTracker{}, nil, fakePolicy{}, au)
+
+	rec, err := svc.Capture(context.Background(), CaptureInput{
+		Context:  baseCtx(),
+		DryRun:   true,
+		Insights: []Insight{{Text: "x", Wing: "hyperguild", Hall: "facts"}},
+	})
+	require.NoError(t, err, "dry-run does not hit the audit gate")
+	assert.True(t, rec.DryRun)
+	assert.Empty(t, au.entries)
+}

ingestion/internal/capturehttp/handler.go

@@ -11,6 +11,7 @@ import (
 	"crypto/subtle"
 	"encoding/json"
 	"errors"
+	"io"
 	"net/http"
 	"strings"
 
@@ -90,19 +91,22 @@ type summaryBody struct {
 // ServeHTTP authenticates, derives origin, runs the use-case, and maps the
 // result to an HTTP status.
 func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
-	principal, viaStatic, ok := h.authenticate(r)
+	principal, viaStatic, ok := Authenticate(r, h.staticToken, h.staticPrincipal, h.validator)
 	if !ok {
 		http.Error(w, "unauthorized", http.StatusUnauthorized)
 		return
 	}
 
-	var req request
+	body, err := io.ReadAll(r.Body)
-	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+	if err != nil {
+		writeJSON(w, http.StatusBadRequest, map[string]string{"error": "read body"})
+		return
+	}
+	in, err := DecodeRequest(body)
+	if err != nil {
 		writeJSON(w, http.StatusBadRequest, map[string]string{"error": "invalid JSON"})
 		return
 	}
-
-	in := req.toInput()
 	// Principal and origin are server-derived — overwrite anything the
 	// caller may have tried to put in the body.
 	in.Context.Principal = principal
@@ -113,6 +117,10 @@ func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 	case errors.Is(err, capture.ErrSovereigntyRefused):
 		writeJSON(w, http.StatusForbidden, map[string]string{"error": err.Error()})
 		return
+	case errors.Is(err, capture.ErrAuditUnavailable):
+		// I5 refusal: confidential + audit sink down, or the all-tiers floor.
+		writeJSON(w, http.StatusServiceUnavailable, map[string]string{"error": err.Error()})
+		return
 	case err != nil:
 		// Pre-write validation failure (fail-closed).
 		writeJSON(w, http.StatusBadRequest, map[string]string{"error": err.Error()})
@@ -121,26 +129,39 @@ func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 	writeJSON(w, statusFor(rec), rec)
 }
 
-// authenticate mirrors the chassis Bearer precedence (static wins, then
+// Authenticate mirrors the chassis Bearer precedence (static token wins,
-// JWT) but returns the resolved principal and whether the static path was
+// then Dex JWT) and returns the resolved principal plus whether the static
-// taken — the chassis middleware hides both, and capture needs them to
+// path was taken — the chassis middleware hides both, and capture (REST or
-// derive the origin.
+// MCP) needs them to derive the trust-zone origin. ok is false when no
-func (h *Handler) authenticate(r *http.Request) (principal string, viaStatic, ok bool) {
+// credential matched.
+func Authenticate(r *http.Request, staticToken, staticPrincipal string, validator Validator) (principal string, viaStatic, ok bool) {
 	raw, found := strings.CutPrefix(r.Header.Get("Authorization"), "Bearer ")
 	if !found || raw == "" {
 		return "", false, false
 	}
-	if h.staticToken != "" && subtle.ConstantTimeCompare([]byte(raw), []byte(h.staticToken)) == 1 {
+	if staticToken != "" && subtle.ConstantTimeCompare([]byte(raw), []byte(staticToken)) == 1 {
-		return h.staticPrincipal, true, true
+		return staticPrincipal, true, true
 	}
-	if h.validator != nil {
+	if validator != nil {
-		if sub, err := h.validator.Validate(r.Context(), raw); err == nil && sub != "" {
+		if sub, err := validator.Validate(r.Context(), raw); err == nil && sub != "" {
 			return sub, false, true
 		}
 	}
 	return "", false, false
 }
 
+// DecodeRequest parses a capture request body into a CaptureInput. Shared
+// by the REST adapter and the MCP capture tool so the wire shape has one
+// definition. Principal and Origin are NOT set here — the caller sets them
+// from the authenticated identity.
+func DecodeRequest(data []byte) (capture.CaptureInput, error) {
+	var b request
+	if err := json.Unmarshal(data, &b); err != nil {
+		return capture.CaptureInput{}, err
+	}
+	return b.toInput(), nil
+}
+
 func (b request) toInput() capture.CaptureInput {
 	in := capture.CaptureInput{
 		Context: capture.CaptureContext{

ingestion/internal/capturehttp/handler_test.go

@@ -176,3 +176,23 @@ func TestCallerCannotForgeOrigin(t *testing.T) {
 	})
 	assert.Equal(t, http.StatusForbidden, rr.Code)
 }
+
+// refusingAudit refuses at Reserve (e.g. confidential + loki down, or floor).
+type refusingAudit struct{}
+
+func (refusingAudit) Reserve(context.Context, classification.Level) (capture.AuditOutcome, error) {
+	return 0, errors.New("central audit sink unreachable")
+}
+func (refusingAudit) Record(context.Context, capture.AuditEntry, capture.AuditOutcome) error {
+	return nil
+}
+
+func TestAuditUnavailableIs503(t *testing.T) {
+	cfg, err := classification.Load(t.TempDir())
+	require.NoError(t, err)
+	svc := capture.NewService(brainstore.New(t.TempDir()), fakeTracker{}, nil, cfg, refusingAudit{})
+	h := capturehttp.New(svc, nil, staticTok, "local-cli", capturehttp.NewOriginResolver(nil))
+
+	rr := do(t, h, "Bearer "+staticTok, internalReq())
+	assert.Equal(t, http.StatusServiceUnavailable, rr.Code)
+}

ingestion/internal/gitea/gitea.go

@@ -12,6 +12,7 @@ package gitea
 import (
 	"bytes"
 	"context"
+	"encoding/base64"
 	"encoding/json"
 	"fmt"
 	"io"
@@ -93,37 +94,105 @@ func (c *Client) CloseIssue(ctx context.Context, repo string, number int, commen
 	return capture.IssueRef{Repo: repo, Number: number, URL: out.HTMLURL}, nil
 }
 
-// do performs a JSON request against the Gitea API and decodes the
+// WriteFile creates or updates a file in repo at path via the Gitea
-// response into out. Errors carry the status and a truncated body for
+// contents API — the SummaryWriter port (#66). It upserts: a GET resolves
-// diagnosis but never the token.
+// the current blob sha (if any) so an existing file is updated rather than
-func (c *Client) do(ctx context.Context, method, path string, payload any, out *issueResponse) error {
+// rejected (the richer-fidelity-supersedes rule for re-captured sessions).
-	reqBody, err := json.Marshal(payload)
+// Owner is the fixed const, like every other call.
-	if err != nil {
+func (c *Client) WriteFile(ctx context.Context, repo, path, content string) error {
-		return fmt.Errorf("marshal request: %w", err)
+	cpath := fmt.Sprintf("/api/v1/repos/%s/%s/contents/%s", owner, repo, path)
-	}
+	sha, err := c.fileSHA(ctx, cpath)
-	req, err := http.NewRequestWithContext(ctx, method, c.baseURL+path, bytes.NewReader(reqBody))
 	if err != nil {
 		return err
 	}
-	req.Header.Set("Content-Type", "application/json")
+	payload := map[string]any{
-	req.Header.Set("Accept", "application/json")
+		"message": "capture: " + path,
-	// Gitea's token scheme. Held here only; never logged.
+		"content": base64.StdEncoding.EncodeToString([]byte(content)),
-	req.Header.Set("Authorization", "token "+c.token)
+	}
-
+	// Gitea contents API: POST creates a new file, PUT updates an existing
-	resp, err := c.http.Do(req)
+	// one (PUT requires the current sha). Pick by whether the file exists.
+	method := http.MethodPost
+	if sha != "" {
+		method = http.MethodPut
+		payload["sha"] = sha
+	}
+	status, body, err := c.request(ctx, method, cpath, payload)
 	if err != nil {
-		return fmt.Errorf("gitea %s %s: %w", method, path, err)
+		return err
+	}
+	if status < 200 || status >= 300 {
+		return fmt.Errorf("gitea %s %s: status %d: %s", method, cpath, status, strings.TrimSpace(string(body)))
+	}
+	return nil
 }
-	defer func() { _ = resp.Body.Close() }()
 
-	respBody, _ := io.ReadAll(io.LimitReader(resp.Body, 4096))
+// fileSHA returns the current blob sha for a contents path, or "" when the
-	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+// file does not exist (404). Any other non-2xx is an error.
-		return fmt.Errorf("gitea %s %s: status %d: %s", method, path, resp.StatusCode, strings.TrimSpace(string(respBody)))
+func (c *Client) fileSHA(ctx context.Context, cpath string) (string, error) {
+	status, body, err := c.request(ctx, http.MethodGet, cpath, nil)
+	if err != nil {
+		return "", err
 	}
-	if out != nil && len(respBody) > 0 {
+	if status == http.StatusNotFound {
-		if err := json.Unmarshal(respBody, out); err != nil {
+		return "", nil
+	}
+	if status < 200 || status >= 300 {
+		return "", fmt.Errorf("gitea GET %s: status %d: %s", cpath, status, strings.TrimSpace(string(body)))
+	}
+	var meta struct {
+		SHA string `json:"sha"`
+	}
+	if err := json.Unmarshal(body, &meta); err != nil {
+		return "", fmt.Errorf("gitea GET %s: decode: %w", cpath, err)
+	}
+	return meta.SHA, nil
+}
+
+// do performs a JSON request against the Gitea API and decodes a 2xx
+// response into out. Errors carry the status and a truncated body for
+// diagnosis but never the token.
+func (c *Client) do(ctx context.Context, method, path string, payload any, out *issueResponse) error {
+	status, body, err := c.request(ctx, method, path, payload)
+	if err != nil {
+		return err
+	}
+	if status < 200 || status >= 300 {
+		return fmt.Errorf("gitea %s %s: status %d: %s", method, path, status, strings.TrimSpace(string(body)))
+	}
+	if out != nil && len(body) > 0 {
+		if err := json.Unmarshal(body, out); err != nil {
 			return fmt.Errorf("gitea %s %s: decode response: %w", method, path, err)
 		}
 	}
 	return nil
 }
+
+// request is the shared HTTP path: marshals an optional JSON payload,
+// attaches auth (token only ever in the header), and returns the status +
+// body so callers can branch on status (e.g. 404) without it being an
+// error. Never logs the token.
+func (c *Client) request(ctx context.Context, method, path string, payload any) (int, []byte, error) {
+	var reader io.Reader
+	if payload != nil {
+		reqBody, err := json.Marshal(payload)
+		if err != nil {
+			return 0, nil, fmt.Errorf("marshal request: %w", err)
+		}
+		reader = bytes.NewReader(reqBody)
+	}
+	req, err := http.NewRequestWithContext(ctx, method, c.baseURL+path, reader)
+	if err != nil {
+		return 0, nil, err
+	}
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("Accept", "application/json")
+	req.Header.Set("Authorization", "token "+c.token)
+
+	resp, err := c.http.Do(req)
+	if err != nil {
+		return 0, nil, fmt.Errorf("gitea %s %s: %w", method, path, err)
+	}
+	defer func() { _ = resp.Body.Close() }()
+	body, _ := io.ReadAll(io.LimitReader(resp.Body, 8192))
+	return resp.StatusCode, body, nil
+}

ingestion/internal/gitea/gitea_test.go

@@ -115,3 +115,69 @@ func TestErrorPathDoesNotLeakToken(t *testing.T) {
 	assert.NotContains(t, err.Error(), testToken, "token must never appear in an error message")
 	assert.Contains(t, err.Error(), "500")
 }
+
+func TestWriteFileCreatesNewFile(t *testing.T) {
+	var getPath, postPath, postBody string
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		switch r.Method {
+		case http.MethodGet:
+			getPath = r.URL.Path
+			w.WriteHeader(http.StatusNotFound) // file does not exist yet
+		case http.MethodPost: // gitea contents API: POST = create
+			postPath = r.URL.Path
+			b, _ := io.ReadAll(r.Body)
+			postBody = string(b)
+			w.WriteHeader(http.StatusCreated)
+			_ = json.NewEncoder(w).Encode(map[string]any{"content": map[string]any{"html_url": "https://git/x"}})
+		default:
+			t.Errorf("create must POST, got %s", r.Method)
+		}
+	}))
+	defer srv.Close()
+
+	err := gitea.New(srv.URL, testToken).WriteFile(context.Background(),
+		"ai-sessions", "summaries/claude-code/2026-06/2026-06-23-x-abcd1234.md", "# Summary\n\nbody\n")
+	require.NoError(t, err)
+	assert.Equal(t, "/api/v1/repos/mathias/ai-sessions/contents/summaries/claude-code/2026-06/2026-06-23-x-abcd1234.md", getPath)
+	assert.Equal(t, getPath, postPath)
+	// base64 of the content, no sha on create.
+	assert.Contains(t, postBody, "IyBTdW1tYXJ5") // base64("# Summary")
+	assert.NotContains(t, postBody, `"sha"`)
+}
+
+func TestWriteFileUpdatesExisting(t *testing.T) {
+	var putBody string
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		switch r.Method {
+		case http.MethodGet:
+			w.WriteHeader(http.StatusOK)
+			_ = json.NewEncoder(w).Encode(map[string]any{"sha": "deadbeef"})
+		case http.MethodPut:
+			b, _ := io.ReadAll(r.Body)
+			putBody = string(b)
+			w.WriteHeader(http.StatusOK)
+			_ = json.NewEncoder(w).Encode(map[string]any{"content": map[string]any{"html_url": "https://git/x"}})
+		}
+	}))
+	defer srv.Close()
+
+	err := gitea.New(srv.URL, testToken).WriteFile(context.Background(), "ai-sessions", "p/x.md", "new")
+	require.NoError(t, err)
+	assert.Contains(t, putBody, `"sha":"deadbeef"`, "existing file → update with sha")
+}
+
+func TestWriteFileErrorNoTokenLeak(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Method == http.MethodGet {
+			w.WriteHeader(http.StatusNotFound)
+			return
+		}
+		w.WriteHeader(http.StatusUnprocessableEntity)
+		_, _ = w.Write([]byte("bad"))
+	}))
+	defer srv.Close()
+	err := gitea.New(srv.URL, testToken).WriteFile(context.Background(), "ai-sessions", "p/x.md", "x")
+	require.Error(t, err)
+	assert.NotContains(t, err.Error(), testToken)
+	assert.Contains(t, err.Error(), "422")
+}

ingestion/internal/mcp/handlers.go

@@ -9,6 +9,7 @@ import (
 	"strings"
 	"time"
 
+	"github.com/mathiasbq/hyperguild/ingestion/internal/api"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/brain"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/capture"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/extract"
@@ -38,7 +39,7 @@ func (s *Server) tools() []map[string]any {
 		return b
 	}
 
-	return []map[string]any{
+	tools := []map[string]any{
 		{
 			"name":        "brain_query",
 			"description": "BM25 full-text search across brain/knowledge/ and brain/wiki/ markdown files. Optionally scope by wing (topic domain) and hall (memory type).",
@@ -81,6 +82,21 @@ func (s *Server) tools() []map[string]any {
 				"path": str("brain-relative path to the note; equivalent to id"),
 			}),
 		},
+		{
+			"name":        "brain_pending",
+			"description": "List notes in brain/raw/ awaiting human promotion to the wiki, oldest-first. Returns filename, created_at, size_bytes, excerpt. The human-review queue complement to brain_promote.",
+			"inputSchema": schema([]string{}, map[string]any{}),
+		},
+		{
+			"name":        "brain_promote",
+			"description": "Promote a brain/raw/ note into brain/wiki/<wing>/<hall>/: rewrites frontmatter (sets wing/hall/promoted_at, preserves created_at + custom fields), deletes the source, rebuilds the wing index, runs auto-tunnel. Errors (without touching the fs) on invalid hall or a slug collision. Returns {path}.",
+			"inputSchema": schema([]string{"filename", "wing", "hall"}, map[string]any{
+				"filename": str("basename in brain/raw/, e.g. 2026-06-01-lejpa-decision.md"),
+				"wing":     str("target wing, e.g. jepa-fx"),
+				"hall":     enum("target hall", halls...),
+				"slug":     str("optional target slug; defaults to filename minus date prefix"),
+			}),
+		},
 		{
 			"name":        "brain_tunnel",
 			"description": "Create an explicit bidirectional [[wikilink]] between two notes in different wings. Idempotent.",
@@ -171,6 +187,13 @@ func (s *Server) tools() []map[string]any {
 			}),
 		},
 	}
+	// The capture relay tool (#55) is advertised only when wired via
+	// WithCapture — MCP-native harnesses (claude.ai, Crush, Pi, LLM Council)
+	// reach capture through it.
+	if s.capture != nil {
+		tools = append(tools, captureToolDescriptor())
+	}
+	return tools
 }
 
 type brainQueryArgs struct {
@@ -314,6 +337,40 @@ func (s *Server) brainGet(ctx context.Context, args json.RawMessage) (json.RawMe
 	})
 }
 
+// brainPending lists the raw/ review queue (oldest-first).
+func (s *Server) brainPending(_ context.Context, _ json.RawMessage) (json.RawMessage, error) {
+	pending, err := api.ListPending(s.brainDir)
+	if err != nil {
+		return nil, err
+	}
+	return json.Marshal(map[string]any{"pending": pending})
+}
+
+type brainPromoteArgs struct {
+	Filename string `json:"filename"`
+	Wing     string `json:"wing"`
+	Hall     string `json:"hall"`
+	Slug     string `json:"slug,omitempty"`
+}
+
+// brainPromote moves a raw/ note into the structured wiki (frontmatter
+// rewrite + index + auto-tunnel, all owned by api.PromoteNote) and then
+// re-indexes it into the graph. The human-facing complement to brain_write.
+func (s *Server) brainPromote(ctx context.Context, args json.RawMessage) (json.RawMessage, error) {
+	var a brainPromoteArgs
+	if err := json.Unmarshal(args, &a); err != nil {
+		return nil, fmt.Errorf("parse args: %w", err)
+	}
+	relPath, err := api.PromoteNote(s.brainDir, api.PromoteOptions{
+		Filename: a.Filename, Wing: a.Wing, Hall: a.Hall, Slug: a.Slug,
+	})
+	if err != nil {
+		return nil, err
+	}
+	s.indexInGraph(ctx, "brain_promote", relPath)
+	return json.Marshal(map[string]string{"path": relPath})
+}
+
 // indexInGraph is a best-effort wrapper around graphsync.IndexDoc that
 // logs failures but never propagates them — the underlying write/ingest
 // has already succeeded and the graph is an augmentation, not a

ingestion/internal/mcp/handlers_test.go

@@ -332,3 +332,61 @@ func TestSessionLogRequiresSessionID(t *testing.T) {
 	resp := toolCall(t, srv, "session_log", map[string]any{"skill": "tdd"})
 	require.NotNil(t, resp["error"])
 }
+
+func TestBrainPendingListsRaw(t *testing.T) {
+	brainDir := t.TempDir()
+	raw := filepath.Join(brainDir, "raw")
+	require.NoError(t, os.MkdirAll(raw, 0o755))
+	require.NoError(t, os.WriteFile(filepath.Join(raw, "2026-06-01-x.md"),
+		[]byte("---\ncreated_at: 2026-06-01T00:00:00Z\n---\npending body\n"), 0o644))
+	srv := mcp.NewServer(brainDir, nil, nil, nil)
+
+	resp := toolCall(t, srv, "brain_pending", map[string]any{})
+	require.Nil(t, resp["error"])
+	text := resp["result"].(map[string]any)["content"].([]any)[0].(map[string]any)["text"].(string)
+	assert.Contains(t, text, "2026-06-01-x.md")
+	assert.Contains(t, text, "pending body")
+}
+
+func TestBrainPendingEmpty(t *testing.T) {
+	srv := mcp.NewServer(t.TempDir(), nil, nil, nil)
+	resp := toolCall(t, srv, "brain_pending", map[string]any{})
+	require.Nil(t, resp["error"])
+	text := resp["result"].(map[string]any)["content"].([]any)[0].(map[string]any)["text"].(string)
+	assert.Contains(t, text, `"pending":[]`)
+}
+
+func TestBrainPromoteMovesToWiki(t *testing.T) {
+	brainDir := t.TempDir()
+	raw := filepath.Join(brainDir, "raw")
+	require.NoError(t, os.MkdirAll(raw, 0o755))
+	require.NoError(t, os.WriteFile(filepath.Join(raw, "2026-06-01-decision.md"),
+		[]byte("---\ncreated_at: 2026-06-01T00:00:00Z\n---\n# D\n\nbody\n"), 0o644))
+	srv := mcp.NewServer(brainDir, nil, nil, nil)
+
+	resp := toolCall(t, srv, "brain_promote", map[string]any{
+		"filename": "2026-06-01-decision.md", "wing": "jepa-fx", "hall": "decisions",
+	})
+	require.Nil(t, resp["error"], "got: %v", resp["error"])
+	text := resp["result"].(map[string]any)["content"].([]any)[0].(map[string]any)["text"].(string)
+	assert.Contains(t, text, "wiki/jepa-fx/decisions/decision.md")
+
+	_, err := os.Stat(filepath.Join(brainDir, "wiki/jepa-fx/decisions/decision.md"))
+	require.NoError(t, err)
+	_, srcErr := os.Stat(filepath.Join(raw, "2026-06-01-decision.md"))
+	assert.True(t, os.IsNotExist(srcErr), "source removed")
+}
+
+func TestBrainPromoteInvalidHallErrors(t *testing.T) {
+	brainDir := t.TempDir()
+	raw := filepath.Join(brainDir, "raw")
+	require.NoError(t, os.MkdirAll(raw, 0o755))
+	require.NoError(t, os.WriteFile(filepath.Join(raw, "x.md"), []byte("body\n"), 0o644))
+	srv := mcp.NewServer(brainDir, nil, nil, nil)
+	resp := toolCall(t, srv, "brain_promote", map[string]any{
+		"filename": "x.md", "wing": "a", "hall": "garbage",
+	})
+	require.NotNil(t, resp["error"])
+	_, srcErr := os.Stat(filepath.Join(raw, "x.md"))
+	assert.NoError(t, srcErr, "source untouched on validation error")
+}

ingestion/internal/mcp/server.go

@@ -1,7 +1,9 @@
 // Package mcp implements an MCP HTTP handler for the ingestion service.
 // Exposed tools: brain_query, brain_write, brain_update, brain_get,
-// brain_index, brain_tunnel, brain_ingest, brain_ingest_raw,
+// brain_pending, brain_promote, brain_index, brain_tunnel, brain_ingest,
-// brain_answer, brain_classify, brain_graph, brain_context, session_log.
+// brain_ingest_raw, brain_answer, brain_classify, brain_graph,
+// brain_context, session_log, and capture (the #55 relay tool, registered
+// only when WithCapture is set).
 package mcp
 
 import (
@@ -12,6 +14,7 @@ import (
 
 	"github.com/mathiasbq/hyperguild/ingestion/internal/brainstore"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/capture"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/capturehttp"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/graphstore"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/graphsync"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/pipeline"
@@ -50,6 +53,19 @@ type Server struct {
 	graph     graphsync.Store       // nil = brain_graph and GraphRAG augmentation disabled
 	store     *brainstore.Store     // shared brain write/update/get impl (also used by capture)
 	tracker   capture.IssueTracker  // nil = no Gitea ticket integration; wired for capture (#53)
+	capture   *captureDeps          // nil = capture MCP tool disabled (#55 relay)
+}
+
+// captureDeps holds what the MCP `capture` tool (the #55 relay door for
+// MCP-native harnesses like claude.ai) needs: the use-case, the auth bits
+// to re-derive the caller's principal from the Bearer header (the chassis
+// middleware gates but discards the principal), and the origin resolver.
+type captureDeps struct {
+	svc             *capture.Service
+	validator       capturehttp.Validator
+	staticToken     string
+	staticPrincipal string
+	resolver        capturehttp.OriginResolver
 }
 
 // NewServer constructs a Server bound to brainDir. pipelineCfg supplies the
@@ -123,6 +139,29 @@ func (s *Server) BrainStore() *brainstore.Store {
 	return s.store
 }
 
+// WithCapture enables the MCP `capture` tool (#55) — the relay door for
+// MCP-native harnesses (claude.ai, Crush, Pi, LLM Council) that cannot run
+// the use-case in-process. It forwards to the same CaptureService as
+// POST /capture, deriving the caller's principal + origin from the same
+// auth credentials that gate /mcp. nil svc leaves the tool unregistered.
+func (s *Server) WithCapture(svc *capture.Service, validator capturehttp.Validator, staticToken, staticPrincipal string, resolver capturehttp.OriginResolver) *Server {
+	if svc == nil {
+		s.capture = nil
+		return s
+	}
+	if staticPrincipal == "" {
+		staticPrincipal = "local-cli"
+	}
+	s.capture = &captureDeps{
+		svc:             svc,
+		validator:       validator,
+		staticToken:     staticToken,
+		staticPrincipal: staticPrincipal,
+		resolver:        resolver,
+	}
+	return s
+}
+
 func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 	// MCP streamable HTTP: GET establishes the SSE stream for server-to-client events.
 	if r.Method == http.MethodGet {
@@ -172,7 +211,18 @@ func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 			rpcErr = &rpcError{Code: -32602, Message: "invalid params"}
 			break
 		}
-		out, err := s.handleCall(r.Context(), p.Name, p.Arguments)
+		// Re-derive the authenticated principal from the Bearer header so
+		// the capture tool can compute the trust-zone origin. The request
+		// is already gated by BearerMiddleware; this only recovers the
+		// identity that middleware discards.
+		ctx := r.Context()
+		if s.capture != nil {
+			if principal, viaStatic, ok := capturehttp.Authenticate(
+				r, s.capture.staticToken, s.capture.staticPrincipal, s.capture.validator); ok {
+				ctx = withPrincipal(ctx, principal, viaStatic)
+			}
+		}
+		out, err := s.handleCall(ctx, p.Name, p.Arguments)
 		if err != nil {
 			rpcErr = &rpcError{Code: -32000, Message: err.Error()}
 			break
@@ -214,6 +264,12 @@ func (s *Server) handleCall(ctx context.Context, name string, args json.RawMessa
 		return s.brainUpdate(ctx, args)
 	case "brain_get":
 		return s.brainGet(ctx, args)
+	case "brain_pending":
+		return s.brainPending(ctx, args)
+	case "brain_promote":
+		return s.brainPromote(ctx, args)
+	case "capture":
+		return s.brainCapture(ctx, args)
 	case "brain_index":
 		return s.brainIndex(ctx, args)
 	case "brain_tunnel":

ingestion/internal/mcp/server_test.go

@@ -58,6 +58,7 @@ func TestServerToolsList(t *testing.T) {
 	}
 	assert.ElementsMatch(t, []string{
 		"brain_query", "brain_write", "brain_update", "brain_get",
+		"brain_pending", "brain_promote",
 		"brain_index", "brain_tunnel",
 		"brain_ingest_raw", "brain_ingest",
 		"brain_answer", "brain_classify", "brain_graph", "brain_context",

ingestion/internal/mcp/tools_capture.go

@@ -0,0 +1,105 @@
+package mcp
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/capturehttp"
+)
+
+// principalKey is the context key under which the authenticated principal
+// (re-derived in ServeHTTP) is stashed for the capture tool.
+type principalKeyT struct{}
+
+var principalKey principalKeyT
+
+type principalInfo struct {
+	principal string
+	viaStatic bool
+}
+
+func withPrincipal(ctx context.Context, principal string, viaStatic bool) context.Context {
+	return context.WithValue(ctx, principalKey, principalInfo{principal: principal, viaStatic: viaStatic})
+}
+
+// captureToolDescriptor is the tools/list entry for the capture relay.
+// Appended only when WithCapture has wired the tool.
+func captureToolDescriptor() map[string]any {
+	str := func(d string) map[string]any { return map[string]any{"type": "string", "description": d} }
+	insightItem := map[string]any{
+		"type": "object",
+		"properties": map[string]any{
+			"text": str("the insight body"), "wing": str("brain wing"),
+			"hall": str("brain hall (facts/decisions/failures/hypotheses/sources)"),
+			"supersede_slug": str("optional: slug of a prior note to revise in place instead of creating"),
+		},
+		"required": []string{"text", "wing", "hall"},
+	}
+	ticketItem := map[string]any{
+		"type": "object",
+		"properties": map[string]any{
+			"repo": str("gitea repo (owner is always mathias)"), "action": str("create|close|comment"),
+			"number": map[string]any{"type": "integer", "description": "issue number (close/comment)"},
+			"title": str("issue title (create)"), "body": str("issue/comment body"),
+		},
+		"required": []string{"repo", "action"},
+	}
+	schema := map[string]any{
+		"type": "object",
+		"properties": map[string]any{
+			"context": map[string]any{
+				"type": "object",
+				"properties": map[string]any{
+					"harness": str("descriptive harness label (telemetry only, never a gate input)"),
+					"session_ref": str("optional session reference"), "fidelity": str("live-capture|transcript-parse|agent-runlog"),
+					"actor": str("acting user/agent"), "classification": str("caller-declared sensitivity: public|internal|confidential"),
+				},
+			},
+			"insights": map[string]any{"type": "array", "items": insightItem},
+			"tickets":  map[string]any{"type": "array", "items": ticketItem},
+			"summary": map[string]any{"type": "object", "properties": map[string]any{
+				"title": str("summary title"), "body": str("summary body"),
+				"repos_touched": map[string]any{"type": "array", "items": map[string]any{"type": "string"}},
+			}},
+			"dry_run": map[string]any{"type": "boolean", "description": "validate + return the would-be receipt, write nothing"},
+		},
+	}
+	b, _ := json.Marshal(schema)
+	return map[string]any{
+		"name":        "capture",
+		"description": "Persist a session's value uniformly: insights → brain (write or supersede), action items → Gitea tickets, optional summary → ai-sessions. The relay door for MCP-native harnesses. Origin is server-derived from your authenticated identity; confidential captures through a us-nexus surface are refused (I1). Returns a partial-aware receipt.",
+		"inputSchema": json.RawMessage(b),
+	}
+}
+
+// brainCapture is the MCP capture tool: the #55 relay for MCP-native
+// harnesses. It re-uses the same CaptureService, principal-derivation, and
+// origin resolver as POST /capture — only the transport differs. It holds
+// no state and retains nothing beyond the I5 audit record.
+func (s *Server) brainCapture(ctx context.Context, args json.RawMessage) (json.RawMessage, error) {
+	if s.capture == nil {
+		return nil, fmt.Errorf("capture tool not configured")
+	}
+	info, ok := ctx.Value(principalKey).(principalInfo)
+	if !ok || info.principal == "" {
+		// No authenticated principal ⇒ cannot derive origin ⇒ cannot gate.
+		return nil, fmt.Errorf("capture requires an authenticated principal")
+	}
+
+	in, err := capturehttp.DecodeRequest(args)
+	if err != nil {
+		return nil, fmt.Errorf("invalid capture request: %w", err)
+	}
+	// Principal and origin are server-derived — never taken from the body.
+	in.Context.Principal = info.principal
+	in.Context.Origin = s.capture.resolver.Resolve(info.principal, info.viaStatic)
+
+	rec, err := s.capture.svc.Capture(ctx, in)
+	if err != nil {
+		// Surface I1/I5 refusals and validation failures verbatim; errors.Is
+		// markers (ErrSovereigntyRefused / ErrAuditUnavailable) ride in the message.
+		return nil, err
+	}
+	return json.Marshal(rec)
+}

ingestion/internal/mcp/tools_capture_test.go

@@ -0,0 +1,150 @@
+package mcp_test
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/audit"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brainstore"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/capture"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/capturehttp"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/classification"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/mcp"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+const capStaticTok = "cap-static-tok"
+
+type capFakeTracker struct{}
+
+func (capFakeTracker) CreateIssue(context.Context, string, string, string) (capture.IssueRef, error) {
+	return capture.IssueRef{Repo: "hyperguild", Number: 1, URL: "https://git/1"}, nil
+}
+func (capFakeTracker) CloseIssue(context.Context, string, int, string) (capture.IssueRef, error) {
+	return capture.IssueRef{}, nil
+}
+func (capFakeTracker) CommentIssue(context.Context, string, int, string) (capture.IssueRef, error) {
+	return capture.IssueRef{}, nil
+}
+
+type capFakeValidator struct {
+	subject string
+	err     error
+}
+
+func (v capFakeValidator) Validate(context.Context, string) (string, error) {
+	return v.subject, v.err
+}
+
+func captureServer(t *testing.T, validator capturehttp.Validator, sovereign []string) (*mcp.Server, string) {
+	t.Helper()
+	brainDir := t.TempDir()
+	cfg, err := classification.Load(brainDir)
+	require.NoError(t, err)
+	svc := capture.NewService(brainstore.New(brainDir), capFakeTracker{}, nil, cfg, audit.NewSlogSink(nil))
+	srv := mcp.NewServer(brainDir, nil, nil, nil)
+	srv.WithCapture(svc, validator, capStaticTok, "local-cli", capturehttp.NewOriginResolver(sovereign))
+	return srv, brainDir
+}
+
+func captureCall(t *testing.T, srv http.Handler, authz string, args map[string]any) map[string]any {
+	t.Helper()
+	body, _ := json.Marshal(map[string]any{
+		"jsonrpc": "2.0", "id": 1, "method": "tools/call",
+		"params": map[string]any{"name": "capture", "arguments": args},
+	})
+	req := httptest.NewRequest(http.MethodPost, "/mcp", bytes.NewReader(body))
+	if authz != "" {
+		req.Header.Set("Authorization", authz)
+	}
+	rr := httptest.NewRecorder()
+	srv.ServeHTTP(rr, req)
+	var resp map[string]any
+	require.NoError(t, json.Unmarshal(rr.Body.Bytes(), &resp))
+	return resp
+}
+
+func TestCaptureToolListedWhenWired(t *testing.T) {
+	srv, _ := captureServer(t, nil, nil)
+	body, _ := json.Marshal(map[string]any{"jsonrpc": "2.0", "id": 1, "method": "tools/list"})
+	req := httptest.NewRequest(http.MethodPost, "/mcp", bytes.NewReader(body))
+	rr := httptest.NewRecorder()
+	srv.ServeHTTP(rr, req)
+	assert.Contains(t, rr.Body.String(), `"capture"`)
+}
+
+func TestCaptureToolNotListedByDefault(t *testing.T) {
+	srv := mcp.NewServer(t.TempDir(), nil, nil, nil) // no WithCapture
+	body, _ := json.Marshal(map[string]any{"jsonrpc": "2.0", "id": 1, "method": "tools/list"})
+	req := httptest.NewRequest(http.MethodPost, "/mcp", bytes.NewReader(body))
+	rr := httptest.NewRecorder()
+	srv.ServeHTTP(rr, req)
+	assert.NotContains(t, rr.Body.String(), `"capture"`)
+}
+
+func TestCaptureToolForwardsViaStaticPrincipal(t *testing.T) {
+	srv, brainDir := captureServer(t, nil, nil)
+	resp := captureCall(t, srv, "Bearer "+capStaticTok, map[string]any{
+		"context":  map[string]any{"harness": "claude-code", "actor": "mathias", "classification": "internal"},
+		"insights": []map[string]any{{"text": "a fact", "wing": "hyperguild", "hall": "facts"}},
+		"tickets":  []map[string]any{{"repo": "hyperguild", "action": "create", "title": "t"}},
+	})
+	require.Nil(t, resp["error"], "got error: %v", resp["error"])
+	text := resp["result"].(map[string]any)["content"].([]any)[0].(map[string]any)["text"].(string)
+	var rec capture.CaptureReceipt
+	require.NoError(t, json.Unmarshal([]byte(text), &rec))
+	assert.True(t, rec.Insights[0].OK)
+	assert.True(t, rec.Tickets[0].OK)
+	// Forwarded to the real brain store.
+	_, statErr := os.Stat(filepath.Join(brainDir, "wiki/hyperguild/facts"))
+	require.NoError(t, statErr)
+}
+
+func TestCaptureToolRefusesConfidentialViaUSNexus(t *testing.T) {
+	// JWT principal not in the sovereign allowlist ⇒ us-nexus origin.
+	srv, _ := captureServer(t, capFakeValidator{subject: "claudeai-oauth"}, nil)
+	resp := captureCall(t, srv, "Bearer jwt-token", map[string]any{
+		"context":  map[string]any{"harness": "claudeai-chat", "actor": "mathias", "classification": "confidential"},
+		"insights": []map[string]any{{"text": "secret", "wing": "client-seb", "hall": "facts"}},
+	})
+	require.NotNil(t, resp["error"])
+	assert.Contains(t, resp["error"].(map[string]any)["message"].(string), "sovereignty")
+}
+
+func TestCaptureToolAllowsConfidentialViaSovereignJWT(t *testing.T) {
+	srv, _ := captureServer(t, capFakeValidator{subject: "koala-cli"}, []string{"koala-cli"})
+	resp := captureCall(t, srv, "Bearer jwt-token", map[string]any{
+		"context":  map[string]any{"harness": "claude-code", "actor": "mathias", "classification": "confidential"},
+		"insights": []map[string]any{{"text": "secret", "wing": "client-seb", "hall": "facts"}},
+	})
+	assert.Nil(t, resp["error"], "sovereign JWT principal should be allowed: %v", resp["error"])
+}
+
+func TestCaptureToolRejectsUnauthenticated(t *testing.T) {
+	srv, _ := captureServer(t, capFakeValidator{err: errors.New("no jwt")}, nil)
+	resp := captureCall(t, srv, "", map[string]any{ // no Authorization
+		"context":  map[string]any{"harness": "x", "classification": "internal"},
+		"insights": []map[string]any{{"text": "a", "wing": "hyperguild", "hall": "facts"}},
+	})
+	require.NotNil(t, resp["error"])
+	assert.Contains(t, resp["error"].(map[string]any)["message"].(string), "authenticated principal")
+}
+
+func TestCaptureToolCallerCannotForgeOrigin(t *testing.T) {
+	// Body asserts sovereign harness, but the us-nexus JWT principal governs.
+	srv, _ := captureServer(t, capFakeValidator{subject: "claudeai-oauth"}, nil)
+	resp := captureCall(t, srv, "Bearer jwt", map[string]any{
+		"context":  map[string]any{"harness": "sovereign-soil", "classification": "confidential"},
+		"insights": []map[string]any{{"text": "secret", "wing": "client-seb", "hall": "facts"}},
+	})
+	require.NotNil(t, resp["error"])
+	assert.Contains(t, resp["error"].(map[string]any)["message"].(string), "sovereignty")
+}

internal/config/routing.go

@@ -14,6 +14,7 @@ type RoutingConfig struct {
 	LiteLLMBaseURL     string  // LITELLM_BASE_URL, default https://llm-api.d-ma.be
 	LiteLLMAPIKey      string  // LITELLM_API_KEY
 	BrainURL           string  // BRAIN_URL, default http://ingestion.supervisor:3300
+	BrainMCPToken      string  // BRAIN_MCP_TOKEN, bearer for the auth-gated ingestion /mcp (session_log)
 	FastModel          string  // HYPERGUILD_FAST_MODEL, default koala/qwen35-9b-fast
 	ThinkingModel      string  // HYPERGUILD_THINKING_MODEL, default iguana/gemma4-26b
 	// RouteLocalFloor and RouteLocalCeil intentionally invert the usual
@@ -44,6 +45,7 @@ func LoadRouting() (RoutingConfig, error) {
 		LiteLLMBaseURL: envOr("LITELLM_BASE_URL", "https://llm-api.d-ma.be"),
 		LiteLLMAPIKey:  os.Getenv("LITELLM_API_KEY"),
 		BrainURL:       envOr("BRAIN_URL", "http://ingestion.supervisor:3300"),
+		BrainMCPToken:  os.Getenv("BRAIN_MCP_TOKEN"),
 		FastModel:      envOr("HYPERGUILD_FAST_MODEL", "koala/qwen35-9b-fast"),
 		ThinkingModel:  envOr("HYPERGUILD_THINKING_MODEL", "iguana/gemma4-26b"),
 	}

internal/routing/hash.go

@@ -1,21 +0,0 @@
-package routing
-
-import (
-	"crypto/sha256"
-	"encoding/binary"
-)
-
-// CanonicalHash returns a deterministic 64-bit hash of (system, user).
-// Used to make sample-band routing decisions reproducible: identical input
-// strings produce the same hash on every call, independent of process state.
-//
-// Inputs are joined with a 0x00 byte separator before hashing — distinguishes
-// (system="ab", user="cd") from (system="abcd", user="").
-func CanonicalHash(system, user string) uint64 {
-	h := sha256.New()
-	h.Write([]byte(system))
-	h.Write([]byte{0})
-	h.Write([]byte(user))
-	sum := h.Sum(nil)
-	return binary.BigEndian.Uint64(sum[:8])
-}

internal/routing/hash_test.go

@@ -1,46 +0,0 @@
-package routing_test
-
-import (
-	"testing"
-
-	"github.com/mathiasbq/supervisor/internal/routing"
-	"github.com/stretchr/testify/assert"
-)
-
-func TestCanonicalHashDeterministic(t *testing.T) {
-	a := routing.CanonicalHash("system one", "user one")
-	b := routing.CanonicalHash("system one", "user one")
-	assert.Equal(t, a, b, "same inputs must produce same hash")
-}
-
-func TestCanonicalHashDistinguishesInputs(t *testing.T) {
-	cases := [][2]string{
-		{"sys", "user"},
-		{"sys", "user2"},
-		{"sys2", "user"},
-		{"", "system\x00user"}, // separator collision attempt
-		{"system\x00user", ""},
-	}
-	seen := make(map[uint64]bool)
-	for _, c := range cases {
-		h := routing.CanonicalHash(c[0], c[1])
-		assert.False(t, seen[h], "collision on %v", c)
-		seen[h] = true
-	}
-}
-
-func TestCanonicalHashLowBitDistribution(t *testing.T) {
-	// Sanity check: across 1000 distinct inputs, low-bit split is roughly even.
-	zeros, ones := 0, 0
-	for i := 0; i < 1000; i++ {
-		h := routing.CanonicalHash("sys", string(rune('a'+(i%26)))+string(rune(i)))
-		if h&1 == 0 {
-			zeros++
-		} else {
-			ones++
-		}
-	}
-	// Allow ±15% deviation from 500/500. Tighter would be flaky on real data.
-	assert.InDelta(t, 500, zeros, 150)
-	assert.InDelta(t, 500, ones, 150)
-}

internal/routing/log.go

@@ -1,79 +0,0 @@
-package routing
-
-import (
-	"bytes"
-	"context"
-	"encoding/json"
-	"fmt"
-	"net/http"
-	"time"
-)
-
-// LogEntry describes a single routing decision to log via the brain MCP.
-type LogEntry struct {
-	SessionID   string
-	Skill       string // the original skill the call routed (e.g., "review")
-	Decision    string // "local" or "thinking" or "thinking_fallback"
-	Message     string // free-form, e.g. "model=qwen35, pass_rate=0.94"
-	ProjectRoot string
-	DurationMs  int64
-	Failed      bool // true → final_status: "fail"; false → "skip"
-}
-
-// Logger posts session_log entries to a brain MCP at BrainURL + /mcp.
-type Logger struct {
-	BrainURL string
-	HTTP     *http.Client
-}
-
-// NewLogger creates a Logger with a 2-second HTTP timeout.
-func NewLogger(brainURL string) *Logger {
-	return &Logger{
-		BrainURL: brainURL,
-		HTTP:     &http.Client{Timeout: 2 * time.Second},
-	}
-}
-
-// LogDecision posts a session_log MCP call. Errors are returned but the caller
-// MUST NOT block real work on them — logging is best-effort.
-func (l *Logger) LogDecision(ctx context.Context, e LogEntry) error {
-	status := "skip"
-	if e.Failed {
-		status = "fail"
-	}
-	payload := map[string]any{
-		"jsonrpc": "2.0",
-		"id":      1,
-		"method":  "tools/call",
-		"params": map[string]any{
-			"name": "session_log",
-			"arguments": map[string]any{
-				"session_id":   e.SessionID,
-				"skill":        "_routing",
-				"phase":        "decide",
-				"final_status": status,
-				"message":      fmt.Sprintf("%s: %s — %s", e.Skill, e.Decision, e.Message),
-				"duration_ms":  e.DurationMs,
-				"project_root": e.ProjectRoot,
-			},
-		},
-	}
-	body, err := json.Marshal(payload)
-	if err != nil {
-		return fmt.Errorf("log: marshal: %w", err)
-	}
-	req, err := http.NewRequestWithContext(ctx, http.MethodPost, l.BrainURL+"/mcp", bytes.NewReader(body))
-	if err != nil {
-		return fmt.Errorf("log: build request: %w", err)
-	}
-	req.Header.Set("Content-Type", "application/json")
-	resp, err := l.HTTP.Do(req)
-	if err != nil {
-		return fmt.Errorf("log: request: %w", err)
-	}
-	defer func() { _ = resp.Body.Close() }()
-	if resp.StatusCode != http.StatusOK {
-		return fmt.Errorf("log: server returned status %d", resp.StatusCode)
-	}
-	return nil
-}

internal/routing/log_test.go

@@ -1,81 +0,0 @@
-package routing_test
-
-import (
-	"context"
-	"encoding/json"
-	"io"
-	"net/http"
-	"net/http/httptest"
-	"testing"
-
-	"github.com/mathiasbq/supervisor/internal/routing"
-	"github.com/stretchr/testify/assert"
-	"github.com/stretchr/testify/require"
-)
-
-func TestLoggerLogDecision(t *testing.T) {
-	var captured map[string]any
-	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		assert.Equal(t, http.MethodPost, r.Method)
-		assert.Equal(t, "/mcp", r.URL.Path)
-		body, _ := io.ReadAll(r.Body)
-		require.NoError(t, json.Unmarshal(body, &captured))
-		_ = json.NewEncoder(w).Encode(map[string]any{"jsonrpc": "2.0", "id": 1, "result": map[string]any{"content": []map[string]any{{"type": "text", "text": "ok"}}}})
-	}))
-	defer srv.Close()
-
-	l := routing.NewLogger(srv.URL)
-	err := l.LogDecision(context.Background(), routing.LogEntry{
-		SessionID:   "sess-1",
-		Skill:       "review",
-		Decision:    "local",
-		Message:     "model=qwen35, pass_rate=0.94",
-		ProjectRoot: "/home/x/proj",
-		DurationMs:  1234,
-		Failed:      false,
-	})
-	require.NoError(t, err)
-
-	params := captured["params"].(map[string]any)
-	assert.Equal(t, "tools/call", captured["method"])
-	assert.Equal(t, "session_log", params["name"])
-
-	args := params["arguments"].(map[string]any)
-	assert.Equal(t, "_routing", args["skill"])
-	assert.Equal(t, "decide", args["phase"])
-	assert.Equal(t, "skip", args["final_status"])
-	assert.Contains(t, args["message"].(string), "review: local")
-	assert.Equal(t, "sess-1", args["session_id"])
-	assert.Equal(t, "/home/x/proj", args["project_root"])
-	assert.Equal(t, float64(1234), args["duration_ms"])
-}
-
-func TestLoggerLogFailure(t *testing.T) {
-	var captured map[string]any
-	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		body, _ := io.ReadAll(r.Body)
-		_ = json.Unmarshal(body, &captured)
-		_ = json.NewEncoder(w).Encode(map[string]any{"jsonrpc": "2.0", "id": 1, "result": map[string]any{}})
-	}))
-	defer srv.Close()
-
-	l := routing.NewLogger(srv.URL)
-	err := l.LogDecision(context.Background(), routing.LogEntry{
-		SessionID: "s", Skill: "debug", Decision: "local", Message: "litellm down", Failed: true,
-	})
-	require.NoError(t, err)
-
-	args := captured["params"].(map[string]any)["arguments"].(map[string]any)
-	assert.Equal(t, "fail", args["final_status"])
-}
-
-func TestLoggerSurfacesUpstreamError(t *testing.T) {
-	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
-		http.Error(w, "down", http.StatusBadGateway)
-	}))
-	defer srv.Close()
-
-	l := routing.NewLogger(srv.URL)
-	err := l.LogDecision(context.Background(), routing.LogEntry{Skill: "x", SessionID: "y", Decision: "local"})
-	require.Error(t, err)
-}

internal/routing/passrate.go

@@ -1,85 +0,0 @@
-package routing
-
-import (
-	"context"
-	"encoding/json"
-	"fmt"
-	"net/http"
-	"net/url"
-	"sync"
-	"time"
-)
-
-// Fetcher reads /pass-rate from the brain pod with a per-skill TTL cache.
-type Fetcher struct {
-	BaseURL string
-	Window  string
-	TTL     time.Duration
-	HTTP    *http.Client
-
-	mu    sync.Mutex
-	cache map[string]cachedRate
-}
-
-type cachedRate struct {
-	value *float64
-	at    time.Time
-}
-
-type passRateResponse struct {
-	PassRate *float64 `json:"pass_rate"`
-}
-
-// NewFetcher returns a Fetcher that calls baseURL + /pass-rate with the
-// given window string. If ttl is zero, defaults to 60 seconds. The HTTP
-// client uses a 1-second total timeout.
-func NewFetcher(baseURL, window string, ttl time.Duration) *Fetcher {
-	if ttl == 0 {
-		ttl = 60 * time.Second
-	}
-	return &Fetcher{
-		BaseURL: baseURL,
-		Window:  window,
-		TTL:     ttl,
-		HTTP:    &http.Client{Timeout: time.Second},
-		cache:   make(map[string]cachedRate),
-	}
-}
-
-// Get returns the pass rate for the named skill, or nil if no data exists,
-// or an error if the brain is unreachable. Caches successful results.
-func (f *Fetcher) Get(ctx context.Context, skill string) (*float64, error) {
-	f.mu.Lock()
-	if c, ok := f.cache[skill]; ok && time.Since(c.at) < f.TTL {
-		v := c.value
-		f.mu.Unlock()
-		return v, nil
-	}
-	f.mu.Unlock()
-
-	u := fmt.Sprintf("%s/pass-rate?skill=%s&window=%s",
-		f.BaseURL, url.QueryEscape(skill), url.QueryEscape(f.Window))
-	req, err := http.NewRequestWithContext(ctx, http.MethodGet, u, nil)
-	if err != nil {
-		return nil, fmt.Errorf("passrate: build request: %w", err)
-	}
-	resp, err := f.HTTP.Do(req)
-	if err != nil {
-		return nil, fmt.Errorf("passrate: request: %w", err)
-	}
-	defer func() { _ = resp.Body.Close() }()
-	if resp.StatusCode != http.StatusOK {
-		return nil, fmt.Errorf("passrate: server returned status %d", resp.StatusCode)
-	}
-
-	var body passRateResponse
-	if err := json.NewDecoder(resp.Body).Decode(&body); err != nil {
-		return nil, fmt.Errorf("passrate: decode: %w", err)
-	}
-
-	f.mu.Lock()
-	f.cache[skill] = cachedRate{value: body.PassRate, at: time.Now()}
-	f.mu.Unlock()
-
-	return body.PassRate, nil
-}

internal/routing/passrate_test.go

@@ -1,94 +0,0 @@
-package routing_test
-
-import (
-	"context"
-	"encoding/json"
-	"net/http"
-	"net/http/httptest"
-	"sync/atomic"
-	"testing"
-	"time"
-
-	"github.com/mathiasbq/supervisor/internal/routing"
-	"github.com/stretchr/testify/assert"
-	"github.com/stretchr/testify/require"
-)
-
-func TestFetcherGetReturnsPassRate(t *testing.T) {
-	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		assert.Equal(t, http.MethodGet, r.Method)
-		assert.Equal(t, "/pass-rate", r.URL.Path)
-		assert.Equal(t, "tdd", r.URL.Query().Get("skill"))
-		assert.Equal(t, "7d", r.URL.Query().Get("window"))
-		w.Header().Set("Content-Type", "application/json")
-		_ = json.NewEncoder(w).Encode(map[string]any{"skill": "tdd", "pass_rate": 0.94})
-	}))
-	defer srv.Close()
-
-	f := routing.NewFetcher(srv.URL, "7d", time.Minute)
-	pr, err := f.Get(context.Background(), "tdd")
-	require.NoError(t, err)
-	require.NotNil(t, pr)
-	assert.InDelta(t, 0.94, *pr, 1e-9)
-}
-
-func TestFetcherGetReturnsNilWhenNoData(t *testing.T) {
-	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		_ = json.NewEncoder(w).Encode(map[string]any{"skill": "novel", "pass_rate": nil})
-	}))
-	defer srv.Close()
-
-	f := routing.NewFetcher(srv.URL, "7d", time.Minute)
-	pr, err := f.Get(context.Background(), "novel")
-	require.NoError(t, err)
-	assert.Nil(t, pr)
-}
-
-func TestFetcherCachesWithinTTL(t *testing.T) {
-	var calls int32
-	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
-		atomic.AddInt32(&calls, 1)
-		_ = json.NewEncoder(w).Encode(map[string]any{"pass_rate": 0.5})
-	}))
-	defer srv.Close()
-
-	f := routing.NewFetcher(srv.URL, "7d", time.Minute)
-	for i := 0; i < 5; i++ {
-		_, err := f.Get(context.Background(), "tdd")
-		require.NoError(t, err)
-	}
-	assert.Equal(t, int32(1), atomic.LoadInt32(&calls), "should hit upstream once and serve four times from cache")
-}
-
-func TestFetcherFetchesAgainAfterTTLExpires(t *testing.T) {
-	var calls int32
-	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
-		atomic.AddInt32(&calls, 1)
-		_ = json.NewEncoder(w).Encode(map[string]any{"pass_rate": 0.5})
-	}))
-	defer srv.Close()
-
-	// Tight TTL so the test stays fast.
-	f := routing.NewFetcher(srv.URL, "7d", 5*time.Millisecond)
-	_, err := f.Get(context.Background(), "tdd")
-	require.NoError(t, err)
-	assert.Equal(t, int32(1), atomic.LoadInt32(&calls))
-
-	// Sleep past TTL, then a second Get should hit upstream again.
-	time.Sleep(15 * time.Millisecond)
-	_, err = f.Get(context.Background(), "tdd")
-	require.NoError(t, err)
-	assert.Equal(t, int32(2), atomic.LoadInt32(&calls), "expected fresh upstream call after TTL expiry")
-}
-
-func TestFetcherSurfacesUpstreamError(t *testing.T) {
-	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
-		http.Error(w, "boom", http.StatusInternalServerError)
-	}))
-	defer srv.Close()
-
-	f := routing.NewFetcher(srv.URL, "7d", time.Minute)
-	pr, err := f.Get(context.Background(), "tdd")
-	require.Error(t, err)
-	assert.Nil(t, pr)
-}

internal/routing/policy.go

@@ -1,47 +0,0 @@
-package routing
-
-// Decision is the route picked for a single skill call.
-type Decision int
-
-const (
-	DecideLocal Decision = iota
-	DecideClaude
-)
-
-func (d Decision) String() string {
-	if d == DecideLocal {
-		return "local"
-	}
-	return "claude"
-}
-
-// Policy holds the floor/ceil thresholds for routing decisions.
-//
-// Rules (in order):
-//
-//  1. passRate == nil           → DecideLocal (default-to-local for cost-routable skills)
-//  2. *passRate >= Floor        → DecideLocal (trust local)
-//  3. *passRate <  Ceil         → DecideClaude (don't trust local)
-//  4. otherwise (sample band)   → requestHash low bit picks: 0=local, 1=claude
-type Policy struct {
-	Floor float64
-	Ceil  float64
-}
-
-// Decide returns the routing decision for a single call.
-// requestHash is consulted only when passRate is in the sample band [Ceil, Floor).
-func (p Policy) Decide(passRate *float64, requestHash uint64) Decision {
-	if passRate == nil {
-		return DecideLocal
-	}
-	if *passRate >= p.Floor {
-		return DecideLocal
-	}
-	if *passRate < p.Ceil {
-		return DecideClaude
-	}
-	if requestHash&1 == 0 {
-		return DecideLocal
-	}
-	return DecideClaude
-}

internal/routing/policy_test.go

@@ -1,36 +0,0 @@
-package routing_test
-
-import (
-	"testing"
-
-	"github.com/mathiasbq/supervisor/internal/routing"
-	"github.com/stretchr/testify/assert"
-)
-
-func ptr(f float64) *float64 { return &f }
-
-func TestPolicyDecide(t *testing.T) {
-	p := routing.Policy{Floor: 0.9, Ceil: 0.7}
-
-	cases := []struct {
-		name     string
-		passRate *float64
-		hash     uint64
-		want     routing.Decision
-	}{
-		{"null pass rate → local", nil, 0, routing.DecideLocal},
-		{"null pass rate, hash irrelevant → local", nil, 0xDEADBEEF, routing.DecideLocal},
-		{"at floor → local", ptr(0.9), 0, routing.DecideLocal},
-		{"above floor → local", ptr(0.95), 0, routing.DecideLocal},
-		{"below ceil → claude", ptr(0.5), 0, routing.DecideClaude},
-		{"at ceil → sample-band even-hash → local", ptr(0.7), 0, routing.DecideLocal},
-		{"sample band, even hash → local", ptr(0.8), 2, routing.DecideLocal},
-		{"sample band, odd hash → claude", ptr(0.8), 3, routing.DecideClaude},
-	}
-
-	for _, tc := range cases {
-		t.Run(tc.name, func(t *testing.T) {
-			assert.Equal(t, tc.want, p.Decide(tc.passRate, tc.hash))
-		})
-	}
-}

internal/routing/router.go

@@ -1,84 +0,0 @@
-package routing
-
-import (
-	"context"
-	"fmt"
-	"log/slog"
-)
-
-// CompleteFunc matches the signature used by every skill package's Config.
-type CompleteFunc func(ctx context.Context, model, system, user string) (string, int64, error)
-
-// RunInput captures the per-call inputs the dispatch wrapper needs.
-type RunInput struct {
-	Skill       string
-	System      string
-	User        string
-	SessionID   string
-	ProjectRoot string
-}
-
-// Router composes a pass-rate fetcher, a decision policy, a session logger,
-// and a LiteLLM client. Skill packages receive Router.Run as their CompleteFunc.
-type Router struct {
-	Fetcher     *Fetcher
-	Logger      *Logger
-	Policy      Policy
-	FastModel     string
-	ThinkingModel string
-	Complete    CompleteFunc
-}
-
-// Run executes one skill call: decides local vs claude, calls LiteLLM, logs the
-// decision. On local-side error, falls open by retrying once on the Claude model.
-func (r *Router) Run(ctx context.Context, in RunInput) (string, int64, error) {
-	pr, ferr := r.Fetcher.Get(ctx, in.Skill)
-	if ferr != nil {
-		slog.Warn("router: pass-rate unreachable, defaulting to local", "skill", in.Skill, "err", ferr)
-		pr = nil
-	}
-	hash := CanonicalHash(in.System, in.User)
-	decision := r.Policy.Decide(pr, hash)
-
-	model := r.ThinkingModel
-	if decision == DecideLocal {
-		model = r.FastModel
-	}
-
-	out, ms, err := r.Complete(ctx, model, in.System, in.User)
-	if lerr := r.Logger.LogDecision(ctx, LogEntry{
-		SessionID:   in.SessionID,
-		Skill:       in.Skill,
-		Decision:    decision.String(),
-		Message:     fmt.Sprintf("model=%s, pass_rate=%s", model, formatPassRate(pr)),
-		ProjectRoot: in.ProjectRoot,
-		DurationMs:  ms,
-		Failed:      err != nil,
-	}); lerr != nil {
-		slog.Warn("router: log decision failed", "skill", in.Skill, "err", lerr)
-	}
-
-	if err != nil && decision == DecideLocal {
-		slog.Warn("router: fast failed, falling open to thinking model", "skill", in.Skill, "err", err)
-		out, ms, err = r.Complete(ctx, r.ThinkingModel, in.System, in.User)
-		if lerr := r.Logger.LogDecision(ctx, LogEntry{
-			SessionID:   in.SessionID,
-			Skill:       in.Skill,
-			Decision:    "thinking_fallback",
-			Message:     fmt.Sprintf("model=%s, after-fast-error", r.ThinkingModel),
-			ProjectRoot: in.ProjectRoot,
-			DurationMs:  ms,
-			Failed:      err != nil,
-		}); lerr != nil {
-			slog.Warn("router: log decision failed", "skill", in.Skill, "err", lerr)
-		}
-	}
-	return out, ms, err
-}
-
-func formatPassRate(pr *float64) string {
-	if pr == nil {
-		return "null"
-	}
-	return fmt.Sprintf("%.2f", *pr)
-}

internal/routing/router_test.go

@@ -1,136 +0,0 @@
-package routing_test
-
-import (
-	"context"
-	"encoding/json"
-	"errors"
-	"net/http"
-	"net/http/httptest"
-	"sync"
-	"testing"
-	"time"
-
-	"github.com/mathiasbq/supervisor/internal/routing"
-	"github.com/stretchr/testify/assert"
-	"github.com/stretchr/testify/require"
-)
-
-type fakeLLM struct {
-	mu    sync.Mutex
-	calls []struct{ Model, System, User string }
-	resp  string
-	err   error
-	errOn string // if non-empty, only the named model errors
-}
-
-func (f *fakeLLM) Complete(_ context.Context, model, system, user string) (string, int64, error) {
-	f.mu.Lock()
-	defer f.mu.Unlock()
-	f.calls = append(f.calls, struct{ Model, System, User string }{model, system, user})
-	if f.errOn == model {
-		return "", 0, f.err
-	}
-	if f.err != nil && f.errOn == "" {
-		return "", 0, f.err
-	}
-	return f.resp, 100, nil
-}
-
-func newRouter(t *testing.T, llm *fakeLLM, passRate float64) (*routing.Router, *httptest.Server, *httptest.Server) {
-	t.Helper()
-	brain := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		switch r.URL.Path {
-		case "/pass-rate":
-			_ = json.NewEncoder(w).Encode(map[string]any{"pass_rate": passRate})
-		case "/mcp":
-			_ = json.NewEncoder(w).Encode(map[string]any{"jsonrpc": "2.0", "id": 1, "result": map[string]any{}})
-		}
-	}))
-	t.Cleanup(brain.Close)
-
-	r := &routing.Router{
-		Fetcher:       routing.NewFetcher(brain.URL, "7d", time.Minute),
-		Logger:        routing.NewLogger(brain.URL),
-		Policy:        routing.Policy{Floor: 0.9, Ceil: 0.7},
-		FastModel:     "koala/qwen35-9b-fast",
-		ThinkingModel: "iguana/gemma4-26b",
-		Complete:      llm.Complete,
-	}
-	return r, brain, brain
-}
-
-func TestRouterRoutesLocalAtHighPassRate(t *testing.T) {
-	llm := &fakeLLM{resp: "ok"}
-	r, _, _ := newRouter(t, llm, 0.95)
-
-	out, _, err := r.Run(context.Background(), routing.RunInput{
-		Skill: "review", System: "sys", User: "user", SessionID: "s1", ProjectRoot: "/p",
-	})
-	require.NoError(t, err)
-	assert.Equal(t, "ok", out)
-
-	llm.mu.Lock()
-	defer llm.mu.Unlock()
-	require.Len(t, llm.calls, 1)
-	assert.Equal(t, "koala/qwen35-9b-fast", llm.calls[0].Model)
-}
-
-func TestRouterRoutesThinkingAtLowPassRate(t *testing.T) {
-	llm := &fakeLLM{resp: "ok"}
-	r, _, _ := newRouter(t, llm, 0.3)
-
-	_, _, err := r.Run(context.Background(), routing.RunInput{
-		Skill: "review", System: "sys", User: "user", SessionID: "s2",
-	})
-	require.NoError(t, err)
-
-	llm.mu.Lock()
-	defer llm.mu.Unlock()
-	require.Len(t, llm.calls, 1)
-	assert.Equal(t, "iguana/gemma4-26b", llm.calls[0].Model)
-}
-
-func TestRouterFailsOpenFastErrorToThinking(t *testing.T) {
-	llm := &fakeLLM{resp: "ok-after-fallback", err: errors.New("fast boom"), errOn: "koala/qwen35-9b-fast"}
-	r, _, _ := newRouter(t, llm, 0.95) // would route fast
-
-	out, _, err := r.Run(context.Background(), routing.RunInput{
-		Skill: "review", System: "sys", User: "user", SessionID: "s3",
-	})
-	require.NoError(t, err)
-	assert.Equal(t, "ok-after-fallback", out)
-
-	llm.mu.Lock()
-	defer llm.mu.Unlock()
-	require.Len(t, llm.calls, 2)
-	assert.Equal(t, "koala/qwen35-9b-fast", llm.calls[0].Model)
-	assert.Equal(t, "iguana/gemma4-26b", llm.calls[1].Model)
-}
-
-func TestRouterDefaultsToFastWhenBrainUnreachable(t *testing.T) {
-	// Brain returns 500 → fetcher errors → router treats pass rate as nil → fast.
-	brain := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
-		http.Error(w, "down", http.StatusInternalServerError)
-	}))
-	defer brain.Close()
-
-	llm := &fakeLLM{resp: "ok"}
-	r := &routing.Router{
-		Fetcher:       routing.NewFetcher(brain.URL, "7d", time.Minute),
-		Logger:        routing.NewLogger(brain.URL),
-		Policy:        routing.Policy{Floor: 0.9, Ceil: 0.7},
-		FastModel:     "koala/qwen35-9b-fast",
-		ThinkingModel: "iguana/gemma4-26b",
-		Complete:      llm.Complete,
-	}
-
-	_, _, err := r.Run(context.Background(), routing.RunInput{
-		Skill: "review", System: "sys", User: "user", SessionID: "s4",
-	})
-	require.NoError(t, err)
-
-	llm.mu.Lock()
-	defer llm.mu.Unlock()
-	require.Len(t, llm.calls, 1)
-	assert.Equal(t, "koala/qwen35-9b-fast", llm.calls[0].Model)
-}

internal/routing/snapshot_test.go

@@ -1,80 +0,0 @@
-package routing_test
-
-import (
-	"context"
-	"encoding/json"
-	"os"
-	"sort"
-	"testing"
-
-	"github.com/mathiasbq/supervisor/internal/registry"
-	"github.com/mathiasbq/supervisor/internal/skills/debug"
-	"github.com/mathiasbq/supervisor/internal/skills/retrospective"
-	"github.com/mathiasbq/supervisor/internal/skills/review"
-	"github.com/mathiasbq/supervisor/internal/skills/trainer"
-	"github.com/stretchr/testify/assert"
-	"github.com/stretchr/testify/require"
-)
-
-// TestToolsListMatchesSupervisorSnapshot pins the four routed skills' tool
-// definitions to the supervisor's current advertisement. A deliberate schema
-// change must be reflected here by updating testdata/tools_list.snapshot.json.
-func TestToolsListMatchesSupervisorSnapshot(t *testing.T) {
-	complete := func(_ context.Context, _, _, _ string) (string, int64, error) {
-		return "", 0, nil
-	}
-
-	reg := registry.New()
-	reg.Register(review.New(review.Config{
-		SkillPrompt:  "stub",
-		DefaultModel: "stub",
-		CompleteFunc: complete,
-	}))
-	reg.Register(debug.New(debug.Config{
-		SkillPrompt:  "stub",
-		DefaultModel: "stub",
-		CompleteFunc: complete,
-	}))
-	reg.Register(retrospective.New(retrospective.Config{
-		SkillPrompt:  "stub",
-		DefaultModel: "stub",
-		CompleteFunc: complete,
-	}))
-	reg.Register(trainer.New(trainer.Config{
-		ReaderPrompt: "stub",
-		WriterPrompt: "stub",
-		DefaultModel: "stub",
-		CompleteFunc: complete,
-	}))
-
-	wanted := map[string]bool{
-		"review":        true,
-		"debug":         true,
-		"retrospective": true,
-		"trainer":       true,
-	}
-	var routed []registry.ToolDef
-	for _, td := range reg.Tools() {
-		if wanted[td.Name] {
-			routed = append(routed, td)
-		}
-	}
-	sort.Slice(routed, func(i, j int) bool { return routed[i].Name < routed[j].Name })
-
-	got, err := json.MarshalIndent(routed, "", "  ")
-	require.NoError(t, err)
-
-	want, err := os.ReadFile("testdata/tools_list.snapshot.json")
-	require.NoError(t, err)
-
-	// Normalize both via re-encode so whitespace differences don't dominate.
-	var gotV, wantV any
-	require.NoError(t, json.Unmarshal(got, &gotV))
-	require.NoError(t, json.Unmarshal(want, &wantV))
-
-	gotN, _ := json.MarshalIndent(gotV, "", "  ")
-	wantN, _ := json.MarshalIndent(wantV, "", "  ")
-
-	assert.Equal(t, string(wantN), string(gotN),
-		"tool advertisement drifted from supervisor snapshot — update testdata/tools_list.snapshot.json deliberately if the schema change is intentional")
-}

internal/routing/testdata/tools_list.snapshot.json

@@ -1,97 +0,0 @@
-[
-  {
-    "name": "debug",
-    "description": "Consult a local model to analyse an error and return hypotheses ordered by likelihood, each with a concrete verification step.",
-    "inputSchema": {
-      "properties": {
-        "context": {
-          "type": "string"
-        },
-        "error": {
-          "type": "string"
-        },
-        "model": {
-          "type": "string"
-        },
-        "project_root": {
-          "type": "string"
-        },
-        "session_id": {
-          "type": "string"
-        }
-      },
-      "required": [
-        "project_root",
-        "error"
-      ],
-      "type": "object"
-    }
-  },
-  {
-    "name": "retrospective",
-    "description": "Consult a local model to analyse a completed session and identify what is novel or worth preserving as organizational knowledge.",
-    "inputSchema": {
-      "type": "object",
-      "required": [
-        "session_id"
-      ],
-      "properties": {
-        "session_id": {
-          "type": "string"
-        },
-        "model": {
-          "type": "string"
-        }
-      }
-    }
-  },
-  {
-    "name": "review",
-    "description": "Consult a local model for a structured code review of the specified files. Returns findings with severity levels.",
-    "inputSchema": {
-      "properties": {
-        "context": {
-          "type": "string"
-        },
-        "files": {
-          "items": {
-            "type": "string"
-          },
-          "type": "array"
-        },
-        "model": {
-          "type": "string"
-        },
-        "project_root": {
-          "type": "string"
-        },
-        "session_id": {
-          "type": "string"
-        }
-      },
-      "required": [
-        "project_root",
-        "files"
-      ],
-      "type": "object"
-    }
-  },
-  {
-    "name": "trainer",
-    "description": "Consult a local model to identify learning moments from a session log and suggest knowledge to preserve in the brain.",
-    "inputSchema": {
-      "properties": {
-        "model": {
-          "type": "string"
-        },
-        "session_id": {
-          "type": "string"
-        }
-      },
-      "required": [
-        "session_id"
-      ],
-      "type": "object"
-    }
-  }
-]

internal/skills/debug/handlers.go

@@ -1,82 +0,0 @@
-// internal/skills/debug/handlers.go
-package debug
-
-import (
-	"context"
-	"encoding/json"
-	"fmt"
-	"time"
-
-	"github.com/mathiasbq/supervisor/internal/brain"
-	"github.com/mathiasbq/supervisor/internal/session"
-)
-
-type debugArgs struct {
-	ProjectRoot string `json:"project_root"`
-	Error       string `json:"error"`
-	Context     string `json:"context"`
-	Model       string `json:"model"`
-	SessionID   string `json:"session_id"`
-}
-
-// Handle dispatches the MCP tool call to the appropriate handler.
-func (s *Skill) Handle(ctx context.Context, tool string, args json.RawMessage) (json.RawMessage, error) {
-	if tool != "debug" {
-		return nil, fmt.Errorf("unknown tool: %s", tool)
-	}
-	var a debugArgs
-	if err := json.Unmarshal(args, &a); err != nil {
-		return nil, fmt.Errorf("parse args: %w", err)
-	}
-	if a.ProjectRoot == "" {
-		return nil, fmt.Errorf("project_root is required")
-	}
-	if a.Error == "" {
-		return nil, fmt.Errorf("error is required")
-	}
-
-	model := a.Model
-	if model == "" {
-		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 = session.PrependHistory(s.cfg.SessionsDir, a.SessionID, "debug", task)
-	if brainCtx != "" {
-		task = brainCtx + "\n---\n\n" + task
-	}
-
-	if s.cfg.CompleteFunc == nil {
-		return nil, fmt.Errorf("no executor configured")
-	}
-	t0 := time.Now()
-	text, dur, err := s.cfg.CompleteFunc(ctx, model, s.cfg.SkillPrompt, task)
-	if err != nil {
-		return nil, err
-	}
-
-	if a.SessionID != "" && s.cfg.SessionsDir != "" {
-		msg := text
-		if len(msg) > 200 {
-			msg = msg[:200]
-		}
-		_ = session.Append(s.cfg.SessionsDir, a.SessionID, session.Entry{
-			SessionID:   a.SessionID,
-			Timestamp:   time.Now(),
-			Skill:       "debug",
-			Phase:       "debug",
-			ProjectRoot: a.ProjectRoot,
-			FinalStatus: "ok",
-			ModelUsed:   model,
-			DurationMs:  time.Since(t0).Milliseconds(),
-			Message:     msg,
-		})
-	}
-
-	return json.Marshal(map[string]any{"text": text, "model": model, "duration_ms": dur})
-}

internal/skills/debug/handlers_test.go

@@ -1,53 +0,0 @@
-// internal/skills/debug/handlers_test.go
-package debug_test
-
-import (
-	"context"
-	"encoding/json"
-	"testing"
-
-	"github.com/mathiasbq/supervisor/internal/skills/debug"
-	"github.com/stretchr/testify/assert"
-	"github.com/stretchr/testify/require"
-)
-
-func TestDebugToolRegistered(t *testing.T) {
-	sk := debug.New(debug.Config{SkillPrompt: "debug rules"})
-	names := make([]string, 0)
-	for _, tool := range sk.Tools() {
-		names = append(names, tool.Name)
-	}
-	assert.Contains(t, names, "debug")
-}
-
-func TestDebugRequiresProjectRoot(t *testing.T) {
-	sk := debug.New(debug.Config{SkillPrompt: "d"})
-	_, err := sk.Handle(context.Background(), "debug", json.RawMessage(`{"error":"panic: nil pointer"}`))
-	assert.ErrorContains(t, err, "project_root")
-}
-
-func TestDebugRequiresError(t *testing.T) {
-	sk := debug.New(debug.Config{SkillPrompt: "d"})
-	_, err := sk.Handle(context.Background(), "debug", json.RawMessage(`{"project_root":"/tmp"}`))
-	assert.ErrorContains(t, err, "error")
-}
-
-func TestDebugCallsCompleteFunc(t *testing.T) {
-	var capturedTask string
-	fakeFn := func(_ context.Context, _, _, user string) (string, int64, error) {
-		capturedTask = user
-		return "HYPOTHESIS 1 (high): nil map access. Verify: go test ./...", 90, nil
-	}
-
-	sk := debug.New(debug.Config{SkillPrompt: "debug rules", CompleteFunc: fakeFn, SessionsDir: t.TempDir()})
-	out, err := sk.Handle(context.Background(), "debug", json.RawMessage(
-		`{"project_root":"/tmp/proj","error":"panic: nil pointer dereference at foo.go:42","context":"occurs on startup"}`,
-	))
-	require.NoError(t, err)
-	assert.Contains(t, capturedTask, "panic: nil pointer dereference")
-	assert.Contains(t, capturedTask, "occurs on startup")
-
-	var result map[string]any
-	require.NoError(t, json.Unmarshal(out, &result))
-	assert.Contains(t, result["text"], "nil map access")
-}

internal/skills/debug/skill.go

@@ -1,55 +0,0 @@
-// internal/skills/debug/skill.go
-package debug
-
-import (
-	"context"
-	"encoding/json"
-
-	"github.com/mathiasbq/supervisor/internal/registry"
-)
-
-// CompleteFunc is the function used to call a local model.
-type CompleteFunc func(ctx context.Context, model, system, user string) (string, int64, error)
-
-// Config holds dependencies for the debug skill.
-type Config struct {
-	SkillPrompt   string
-	DefaultModel  string
-	CompleteFunc  CompleteFunc
-	SessionsDir   string
-	IngestBaseURL string
-}
-
-// Skill implements the debug MCP tool.
-type Skill struct{ cfg Config }
-
-// New creates a new debug Skill.
-func New(cfg Config) *Skill { return &Skill{cfg: cfg} }
-
-// Name returns the skill identifier.
-func (s *Skill) Name() string { return "debug" }
-
-// Tools returns the MCP tool definitions for this skill.
-func (s *Skill) Tools() []registry.ToolDef {
-	schema := func(required []string, props map[string]any) json.RawMessage {
-		b, _ := json.Marshal(map[string]any{"type": "object", "required": required, "properties": props})
-		return b
-	}
-	str := map[string]any{"type": "string"}
-	return []registry.ToolDef{
-		{
-			Name:        "debug",
-			Description: "Consult a local model to analyse an error and return hypotheses ordered by likelihood, each with a concrete verification step.",
-			InputSchema: schema(
-				[]string{"project_root", "error"},
-				map[string]any{
-					"project_root": str,
-					"error":        str,
-					"context":      str,
-					"model":        str,
-					"session_id":   str,
-				},
-			),
-		},
-	}
-}

internal/skills/project/handlers.go

@@ -1,297 +0,0 @@
-package project
-
-import (
-	"context"
-	"encoding/json"
-	"errors"
-	"fmt"
-	"strings"
-	"time"
-
-	"github.com/mathiasbq/supervisor/internal/githubclient"
-	"github.com/mathiasbq/supervisor/internal/mcpclient"
-)
-
-type createArgs struct {
-	Name           string `json:"name"`
-	Description    string `json:"description"`
-	Hypothesis     string `json:"hypothesis"`
-	Folder         string `json:"folder"`
-	Stack          string `json:"stack"`
-	Private        bool   `json:"private"`
-	MirrorToGitHub bool   `json:"mirror_to_github,omitempty"`
-}
-
-type createResult struct {
-	GiteaURL  string `json:"gitea_url"`
-	GitHubURL string `json:"github_url"`
-	IssueURL  string `json:"issue_url"`
-	NextSteps string `json:"next_steps"`
-
-	// Reached records the steps that completed. Populated on partial failure
-	// so callers can resume manually instead of guessing what already ran.
-	Reached []string `json:"reached,omitempty"`
-
-	// FailedStep is non-empty when a downstream gitea-mcp call returned an
-	// error; the error itself is surfaced via the JSON-RPC error response,
-	// this field tells the operator which step it happened in.
-	FailedStep string `json:"failed_step,omitempty"`
-}
-
-func errUnknownTool(name string) error { return fmt.Errorf("unknown tool: %s", name) }
-
-// step names — must match what we surface in failed_step / reached.
-const (
-	stepCreateRepo   = "create_repo"
-	stepCreateGitHub = "create_github_repo"
-	stepMirror       = "mirror"
-	stepInfraCommit  = "infra_commit"
-	stepIssue        = "issue"
-)
-
-func (s *Skill) handleCreate(ctx context.Context, raw json.RawMessage) (json.RawMessage, error) {
-	var args createArgs
-	if err := json.Unmarshal(raw, &args); err != nil {
-		return nil, fmt.Errorf("parse args: %w", err)
-	}
-	if err := validate(args); err != nil {
-		return nil, err
-	}
-
-	tmpl := templateFor(args.Stack)
-	giteaURL := fmt.Sprintf("http://gitea.d-ma.be/%s/%s", s.cfg.GiteaOwner, args.Name)
-
-	res := createResult{
-		GiteaURL: giteaURL,
-	}
-	if args.MirrorToGitHub {
-		res.GitHubURL = fmt.Sprintf("https://github.com/%s/%s", s.cfg.GitHubOwner, args.Name)
-	}
-
-	// Step 1: create_project_from_template. If the repo already exists,
-	// gitea-mcp returns -32003 Conflict; we treat that as idempotent success
-	// and continue to the next steps so re-running self-heals partial runs.
-	existed, err := s.callCreateRepo(ctx, args, tmpl)
-	if err != nil {
-		return marshalPartial(res, stepCreateRepo, err)
-	}
-	res.Reached = append(res.Reached, stepCreateRepo)
-
-	// Steps 2+3 are skipped when MirrorToGitHub is false. Default per
-	// infra ADR (Gitea as true master, GitHub as optional opt-in): keep
-	// client / business-logic / personal repos Gitea-only. Set
-	// `mirror_to_github: true` for open-source projects that want a
-	// public GitHub mirror (hyperguild, gitea-mcp, template-*).
-	if args.MirrorToGitHub {
-		// Step 2: create empty GitHub repo. Gitea's push-mirror cannot push
-		// to a non-existent remote, so the destination must exist before
-		// step 3 configures the mirror. Skipped when GitHub client is unset
-		// (degraded mode — see Config.GitHub doc).
-		if s.cfg.GitHub != nil {
-			if err := s.callCreateGitHubRepo(ctx, args); err != nil && !errors.Is(err, githubclient.ErrAlreadyExists) {
-				return marshalPartial(res, stepCreateGitHub, err)
-			}
-			res.Reached = append(res.Reached, stepCreateGitHub)
-		}
-
-		// Step 3: configure push mirror to GitHub. Idempotent: if a mirror with
-		// the same remote already exists, gitea-mcp returns Conflict; we swallow it.
-		if err := s.callMirror(ctx, args.Name); err != nil {
-			if !isConflict(err) {
-				return marshalPartial(res, stepMirror, err)
-			}
-		}
-		res.Reached = append(res.Reached, stepMirror)
-	}
-
-	// Step 3: commit staging namespace manifest to infra repo. Done before
-	// the issue so the staging env is reconciling by the time the issue lands.
-	if err := s.callInfraCommit(ctx, args.Name); err != nil {
-		if !isConflict(err) {
-			return marshalPartial(res, stepInfraCommit, err)
-		}
-	}
-	res.Reached = append(res.Reached, stepInfraCommit)
-
-	// Step 4: open the experiment-brief issue on the new repo.
-	issueURL, err := s.callIssue(ctx, args, existed)
-	if err != nil {
-		return marshalPartial(res, stepIssue, err)
-	}
-	res.IssueURL = issueURL
-	res.Reached = append(res.Reached, stepIssue)
-
-	folder := args.Folder
-	if folder == "" {
-		folder = "."
-	}
-	res.NextSteps = fmt.Sprintf(
-		"cd ~/dev/%s/%s && task new-project -- %s personal %s %s && git remote add origin http://gitea.d-ma.be/%s/%s.git && git push -u origin main",
-		folder, args.Name, args.Name, folder, args.Stack, s.cfg.GiteaOwner, args.Name,
-	)
-
-	return marshalResult(res)
-}
-
-// callCreateRepo invokes create_project_from_template. Returns (existed, err)
-// where existed=true means the destination was already present and we should
-// treat it as a no-op success (idempotency).
-func (s *Skill) callCreateRepo(ctx context.Context, args createArgs, template string) (bool, error) {
-	var out struct {
-		HTMLURL string `json:"html_url"`
-	}
-	err := s.cfg.Client.CallTool(ctx, "create_project_from_template", map[string]any{
-		"owner":         s.cfg.GiteaOwner,
-		"name":          args.Name,
-		"description":   args.Description,
-		"private":       args.Private,
-		"template_name": template,
-	}, &out)
-	if err == nil {
-		return false, nil
-	}
-	if isConflict(err) {
-		return true, nil
-	}
-	return false, err
-}
-
-// callCreateGitHubRepo creates the empty destination repo on GitHub.
-// auto_init=false in githubclient so first push from gitea doesn't conflict
-// with an auto-generated README.
-func (s *Skill) callCreateGitHubRepo(ctx context.Context, args createArgs) error {
-	_, err := s.cfg.GitHub.CreateRepo(ctx, args.Name, args.Description, args.Private)
-	return err
-}
-
-// callMirror configures the push mirror to GitHub.
-func (s *Skill) callMirror(ctx context.Context, name string) error {
-	remote := fmt.Sprintf("https://github.com/%s/%s.git", s.cfg.GitHubOwner, name)
-	return s.cfg.Client.CallTool(ctx, "repo_mirror_push", map[string]any{
-		"owner":           s.cfg.GiteaOwner,
-		"name":            name,
-		"action":          "add",
-		"remote_address":  remote,
-		"remote_username": s.cfg.GitHubOwner,
-		"remote_password": s.cfg.GitHubPAT,
-		"interval":        "8h0m0s",
-		"sync_on_commit":  true,
-	}, nil)
-}
-
-// callInfraCommit writes the staging namespace manifest directly to infra
-// main. Flux reconciles within ~60s. See DECISIONS.md 2026-05-18.
-func (s *Skill) callInfraCommit(ctx context.Context, name string) error {
-	manifest := stagingNamespaceManifest(name, time.Now().UTC().Format(time.RFC3339))
-	return s.cfg.Client.CallTool(ctx, "file_write_branch", map[string]any{
-		"owner":   s.cfg.GiteaOwner,
-		"name":    s.cfg.InfraRepo,
-		"path":    fmt.Sprintf("k3s/staging/%s/namespace.yaml", name),
-		"content": manifest,
-		"branch":  "main",
-		"message": fmt.Sprintf("feat(staging): add namespace for %s\n\nGenerated by hyperguild project_create.", name),
-	}, nil)
-}
-
-// callIssue opens the experiment-brief issue on the newly-created repo.
-// existed=true (repo pre-existed) still posts a new brief — repeated runs
-// can intentionally restate intent without colliding.
-func (s *Skill) callIssue(ctx context.Context, args createArgs, existed bool) (string, error) {
-	body := experimentBrief(args, existed)
-	var out struct {
-		HTMLURL string `json:"html_url"`
-	}
-	err := s.cfg.Client.CallTool(ctx, "issue_create", map[string]any{
-		"owner": s.cfg.GiteaOwner,
-		"name":  args.Name,
-		"title": "experiment brief: " + args.Description,
-		"body":  body,
-	}, &out)
-	if err != nil {
-		return "", err
-	}
-	return out.HTMLURL, nil
-}
-
-func stagingNamespaceManifest(name, createdAt string) string {
-	return fmt.Sprintf(`apiVersion: v1
-kind: Namespace
-metadata:
-  name: staging-%s
-  labels:
-    managed-by: hyperguild
-    project: %s
-    created-at: "%s"
-`, name, name, createdAt)
-}
-
-func experimentBrief(args createArgs, existed bool) string {
-	var b strings.Builder
-	b.WriteString("## Hypothesis\n\n")
-	b.WriteString(args.Hypothesis)
-	b.WriteString("\n\n## Description\n\n")
-	b.WriteString(args.Description)
-	b.WriteString("\n\n## Stack\n\n`")
-	b.WriteString(args.Stack)
-	b.WriteString("`\n\n## Provisioning\n\n")
-	b.WriteString("- Repo created from `template-")
-	b.WriteString(args.Stack)
-	b.WriteString("` on Gitea.\n")
-	if args.MirrorToGitHub {
-		b.WriteString("- Push-mirror configured to GitHub.\n")
-	} else {
-		b.WriteString("- Gitea-only (no GitHub mirror — set `mirror_to_github: true` to opt in).\n")
-	}
-	b.WriteString("- Staging namespace manifest committed to infra repo.\n\n")
-	if existed {
-		b.WriteString("> Note: this repo already existed when `project_create` ran — provisioning steps were re-applied idempotently.\n")
-	}
-	return b.String()
-}
-
-func validate(args createArgs) error {
-	if args.Name == "" {
-		return errors.New("name is required")
-	}
-	if args.Description == "" {
-		return errors.New("description is required")
-	}
-	if args.Hypothesis == "" {
-		return errors.New("hypothesis is required")
-	}
-	if args.Stack != "go-agent" && args.Stack != "go-web" {
-		return fmt.Errorf("stack must be go-agent or go-web, got %q", args.Stack)
-	}
-	return nil
-}
-
-func templateFor(stack string) string {
-	switch stack {
-	case "go-agent":
-		return "template-go-agent"
-	default:
-		return "template-go-web"
-	}
-}
-
-func isConflict(err error) bool {
-	var me *mcpclient.Error
-	if errors.As(err, &me) && me.Code == -32003 {
-		return true
-	}
-	return false
-}
-
-func marshalResult(r createResult) (json.RawMessage, error) {
-	b, err := json.Marshal(r)
-	if err != nil {
-		return nil, fmt.Errorf("marshal result: %w", err)
-	}
-	return b, nil
-}
-
-func marshalPartial(r createResult, step string, inner error) (json.RawMessage, error) {
-	r.FailedStep = step
-	b, _ := json.Marshal(r)
-	return b, fmt.Errorf("project_create step %q failed: %w", step, inner)
-}

internal/skills/project/handlers_test.go

@@ -1,419 +0,0 @@
-package project_test
-
-import (
-	"context"
-	"encoding/json"
-	"net/http"
-	"net/http/httptest"
-	"strings"
-	"sync"
-	"testing"
-
-	"github.com/mathiasbq/supervisor/internal/githubclient"
-	"github.com/mathiasbq/supervisor/internal/mcpclient"
-	"github.com/mathiasbq/supervisor/internal/skills/project"
-	"github.com/stretchr/testify/assert"
-	"github.com/stretchr/testify/require"
-)
-
-// fakeGitHub captures POST /user/repos calls.
-type fakeGitHub struct {
-	mu          sync.Mutex
-	Calls       []map[string]any
-	ReturnError int // 0 = 201 Created, 422 = already exists, etc.
-}
-
-func (g *fakeGitHub) handler() http.Handler {
-	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		var args map[string]any
-		_ = json.NewDecoder(r.Body).Decode(&args)
-		g.mu.Lock()
-		g.Calls = append(g.Calls, args)
-		code := g.ReturnError
-		g.mu.Unlock()
-		switch code {
-		case 0:
-			w.WriteHeader(http.StatusCreated)
-			_, _ = w.Write([]byte(`{"full_name":"mathiasb/x","html_url":"https://github.com/mathiasb/x","clone_url":"https://github.com/mathiasb/x.git"}`))
-		case 422:
-			w.WriteHeader(http.StatusUnprocessableEntity)
-			_, _ = w.Write([]byte(`{"errors":[{"message":"name already exists on this account"}]}`))
-		default:
-			w.WriteHeader(code)
-			_, _ = w.Write([]byte(`{"message":"boom"}`))
-		}
-	})
-}
-
-// fakeGiteaMCP implements just enough of the JSON-RPC tools/call surface
-// to drive project_create end-to-end without an actual gitea-mcp server.
-type fakeGiteaMCP struct {
-	mu sync.Mutex
-	// Recorded calls in order.
-	Calls []recordedCall
-	// Per-tool response. Default is a generic success object.
-	Responses map[string]any
-	// Per-tool error response, takes precedence over Responses.
-	Errors map[string]rpcErr
-}
-
-type rpcErr struct {
-	Code    int
-	Message string
-}
-
-type recordedCall struct {
-	Tool string
-	Args map[string]any
-}
-
-func (f *fakeGiteaMCP) handler() http.Handler {
-	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		var req struct {
-			ID     int             `json:"id"`
-			Params json.RawMessage `json:"params"`
-		}
-		_ = json.NewDecoder(r.Body).Decode(&req)
-		var p struct {
-			Name      string          `json:"name"`
-			Arguments json.RawMessage `json:"arguments"`
-		}
-		_ = json.Unmarshal(req.Params, &p)
-		var args map[string]any
-		_ = json.Unmarshal(p.Arguments, &args)
-
-		f.mu.Lock()
-		f.Calls = append(f.Calls, recordedCall{Tool: p.Name, Args: args})
-		errResp, hasErr := f.Errors[p.Name]
-		var resp any
-		if r, ok := f.Responses[p.Name]; ok {
-			resp = r
-		} else {
-			resp = map[string]any{"html_url": "http://gitea.example/" + p.Name}
-		}
-		f.mu.Unlock()
-
-		w.Header().Set("Content-Type", "application/json")
-		if hasErr {
-			body, _ := json.Marshal(map[string]any{
-				"jsonrpc": "2.0",
-				"id":      req.ID,
-				"error":   map[string]any{"code": errResp.Code, "message": errResp.Message},
-			})
-			_, _ = w.Write(body)
-			return
-		}
-		respText, _ := json.Marshal(resp)
-		body, _ := json.Marshal(map[string]any{
-			"jsonrpc": "2.0",
-			"id":      req.ID,
-			"result": map[string]any{
-				"content": []map[string]any{{"type": "text", "text": string(respText)}},
-			},
-		})
-		_, _ = w.Write(body)
-	})
-}
-
-func newSkill(t *testing.T, f *fakeGiteaMCP) (*project.Skill, *fakeGitHub) {
-	t.Helper()
-	srv := httptest.NewServer(f.handler())
-	t.Cleanup(srv.Close)
-
-	gh := &fakeGitHub{}
-	ghSrv := httptest.NewServer(gh.handler())
-	t.Cleanup(ghSrv.Close)
-
-	return project.New(project.Config{
-		Client:      mustClient(t, srv.URL),
-		GitHub:      githubclient.New("ghp_test").WithBaseURL(ghSrv.URL),
-		GiteaOwner:  "mathias",
-		GitHubOwner: "mathiasb",
-		GitHubPAT:   "ghp_test",
-		InfraRepo:   "infra",
-	}), gh
-}
-
-// newSkillNoGitHub builds a skill with the GitHub client unset — degraded
-// mode where the github-repo-creation step is skipped.
-func newSkillNoGitHub(t *testing.T, f *fakeGiteaMCP) *project.Skill {
-	t.Helper()
-	srv := httptest.NewServer(f.handler())
-	t.Cleanup(srv.Close)
-	return project.New(project.Config{
-		Client:      mustClient(t, srv.URL),
-		GiteaOwner:  "mathias",
-		GitHubOwner: "mathiasb",
-		InfraRepo:   "infra",
-	})
-}
-
-// mustClient builds an mcpclient against an httptest server. Uses a
-// non-empty dummy token because httptest servers don't enforce bearer
-// auth, but mcpclient.New now requires non-empty token (see #13).
-func mustClient(t *testing.T, url string) *mcpclient.Client {
-	t.Helper()
-	c, err := mcpclient.New(url, "test-token")
-	require.NoError(t, err)
-	return c
-}
-
-// happyArgs returns the minimal valid request. With the Gitea-as-true-master
-// ADR shipped, this defaults to Gitea-only (mirror_to_github omitted = false).
-// Tests that need the full Gitea + GitHub mirror flow use mirroredArgs().
-func happyArgs() json.RawMessage {
-	return json.RawMessage(`{
-		"name":"my-experiment",
-		"description":"One-line desc",
-		"hypothesis":"We believe X produces Y",
-		"folder":"AGENTS",
-		"stack":"go-agent",
-		"private":true
-	}`)
-}
-
-// mirroredArgs is happyArgs + mirror_to_github=true — the explicit opt-in
-// path. Equivalent to the pre-ADR default.
-func mirroredArgs() json.RawMessage {
-	return json.RawMessage(`{
-		"name":"my-experiment",
-		"description":"One-line desc",
-		"hypothesis":"We believe X produces Y",
-		"folder":"AGENTS",
-		"stack":"go-agent",
-		"private":true,
-		"mirror_to_github":true
-	}`)
-}
-
-func TestProjectCreate_HappyPath(t *testing.T) {
-	f := &fakeGiteaMCP{
-		Responses: map[string]any{
-			"issue_create": map[string]any{"html_url": "http://gitea.d-ma.be/mathias/my-experiment/issues/1"},
-		},
-	}
-	skill, gh := newSkill(t, f)
-
-	out, err := skill.Handle(context.Background(), "project_create", mirroredArgs())
-	require.NoError(t, err)
-
-	var res map[string]any
-	require.NoError(t, json.Unmarshal(out, &res))
-	assert.Equal(t, "http://gitea.d-ma.be/mathias/my-experiment", res["gitea_url"])
-	assert.Equal(t, "https://github.com/mathiasb/my-experiment", res["github_url"])
-	assert.Equal(t, "http://gitea.d-ma.be/mathias/my-experiment/issues/1", res["issue_url"])
-	assert.Contains(t, res["next_steps"], "cd ~/dev/AGENTS/my-experiment")
-	assert.Contains(t, res["next_steps"], "git remote add origin")
-
-	// All 4 gitea-mcp calls in order.
-	require.Len(t, f.Calls, 4)
-	assert.Equal(t, "create_project_from_template", f.Calls[0].Tool)
-	assert.Equal(t, "repo_mirror_push", f.Calls[1].Tool)
-	assert.Equal(t, "file_write_branch", f.Calls[2].Tool)
-	assert.Equal(t, "issue_create", f.Calls[3].Tool)
-
-	// GitHub repo created between create_project_from_template and mirror.
-	require.Len(t, gh.Calls, 1)
-	assert.Equal(t, "my-experiment", gh.Calls[0]["name"])
-	assert.Equal(t, true, gh.Calls[0]["private"])
-	assert.Equal(t, false, gh.Calls[0]["auto_init"])
-
-	// template selection wired from stack
-	assert.Equal(t, "template-go-agent", f.Calls[0].Args["template_name"])
-	// mirror config
-	assert.Equal(t, "add", f.Calls[1].Args["action"])
-	assert.Equal(t, "https://github.com/mathiasb/my-experiment.git", f.Calls[1].Args["remote_address"])
-	assert.Equal(t, "ghp_test", f.Calls[1].Args["remote_password"])
-	// infra commit path
-	assert.Equal(t, "k3s/staging/my-experiment/namespace.yaml", f.Calls[2].Args["path"])
-	assert.Contains(t, f.Calls[2].Args["content"], "name: staging-my-experiment")
-	assert.Contains(t, f.Calls[2].Args["content"], "managed-by: hyperguild")
-	// PAT must NOT appear in the response
-	assert.NotContains(t, string(out), "ghp_test")
-
-	// reached records the github step too.
-	reached := res["reached"].([]any)
-	assert.Equal(t, []any{"create_repo", "create_github_repo", "mirror", "infra_commit", "issue"}, reached)
-}
-
-func TestProjectCreate_GitHubExists_Idempotent(t *testing.T) {
-	f := &fakeGiteaMCP{
-		Responses: map[string]any{
-			"issue_create": map[string]any{"html_url": "http://gitea.d-ma.be/mathias/my-experiment/issues/1"},
-		},
-	}
-	skill, gh := newSkill(t, f)
-	gh.ReturnError = 422 // already exists
-
-	_, err := skill.Handle(context.Background(), "project_create", mirroredArgs())
-	require.NoError(t, err, "422 already-exists should be idempotent")
-	require.Len(t, f.Calls, 4, "all gitea steps still run despite github 422")
-}
-
-func TestProjectCreate_GitHubFails(t *testing.T) {
-	f := &fakeGiteaMCP{}
-	skill, gh := newSkill(t, f)
-	gh.ReturnError = 401 // bad PAT
-
-	out, err := skill.Handle(context.Background(), "project_create", mirroredArgs())
-	require.Error(t, err)
-	var res map[string]any
-	require.NoError(t, json.Unmarshal(out, &res))
-	assert.Equal(t, "create_github_repo", res["failed_step"])
-	assert.Equal(t, []any{"create_repo"}, res["reached"])
-	require.Len(t, f.Calls, 1, "mirror + later steps must not run when github creation fails")
-}
-
-func TestProjectCreate_NoGitHubClient_DegradedMode(t *testing.T) {
-	f := &fakeGiteaMCP{
-		Responses: map[string]any{
-			"issue_create": map[string]any{"html_url": "http://gitea.d-ma.be/mathias/my-experiment/issues/1"},
-		},
-	}
-	skill := newSkillNoGitHub(t, f)
-
-	// Use mirroredArgs so we exercise the GitHub-mirror path. With the
-	// GitHub client nil, the create_github_repo step is skipped but the
-	// mirror step still attempts to configure the push-mirror remote
-	// (degraded mode preserves the prior contract for opted-in projects).
-	out, err := skill.Handle(context.Background(), "project_create", mirroredArgs())
-	require.NoError(t, err)
-	var res map[string]any
-	require.NoError(t, json.Unmarshal(out, &res))
-	// reached does NOT include create_github_repo when client is nil.
-	reached := res["reached"].([]any)
-	assert.Equal(t, []any{"create_repo", "mirror", "infra_commit", "issue"}, reached)
-}
-
-func TestProjectCreate_Idempotent_RepoExists(t *testing.T) {
-	f := &fakeGiteaMCP{
-		Errors: map[string]rpcErr{
-			"create_project_from_template": {Code: -32003, Message: "already exists"},
-		},
-		Responses: map[string]any{
-			"issue_create": map[string]any{"html_url": "http://gitea.d-ma.be/mathias/my-experiment/issues/1"},
-		},
-	}
-	skill, _ := newSkill(t, f)
-
-	out, err := skill.Handle(context.Background(), "project_create", mirroredArgs())
-	require.NoError(t, err)
-
-	var res map[string]any
-	require.NoError(t, json.Unmarshal(out, &res))
-	assert.Equal(t, "http://gitea.d-ma.be/mathias/my-experiment", res["gitea_url"])
-	assert.Equal(t, "http://gitea.d-ma.be/mathias/my-experiment/issues/1", res["issue_url"])
-
-	// Still ran all 4 gitea-mcp steps; idempotent flow falls through.
-	require.Len(t, f.Calls, 4)
-}
-
-func TestProjectCreate_MirrorFails(t *testing.T) {
-	f := &fakeGiteaMCP{
-		Errors: map[string]rpcErr{
-			"repo_mirror_push": {Code: -32000, Message: "github unreachable"},
-		},
-	}
-	skill, _ := newSkill(t, f)
-
-	out, err := skill.Handle(context.Background(), "project_create", mirroredArgs())
-	require.Error(t, err)
-	assert.Contains(t, err.Error(), `"mirror" failed`)
-
-	var res map[string]any
-	require.NoError(t, json.Unmarshal(out, &res))
-	assert.Equal(t, "mirror", res["failed_step"])
-	reached := res["reached"].([]any)
-	assert.Equal(t, []any{"create_repo", "create_github_repo"}, reached)
-
-	// Steps 1 (create) + 2 (mirror attempt) reached gitea; github made 1 call.
-	require.Len(t, f.Calls, 2)
-}
-
-func TestProjectCreate_InfraCommitFails(t *testing.T) {
-	f := &fakeGiteaMCP{
-		Errors: map[string]rpcErr{
-			"file_write_branch": {Code: -32000, Message: "write rejected"},
-		},
-	}
-	skill, _ := newSkill(t, f)
-
-	out, err := skill.Handle(context.Background(), "project_create", mirroredArgs())
-	require.Error(t, err)
-
-	var res map[string]any
-	require.NoError(t, json.Unmarshal(out, &res))
-	assert.Equal(t, "infra_commit", res["failed_step"])
-	reached := res["reached"].([]any)
-	assert.Equal(t, []any{"create_repo", "create_github_repo", "mirror"}, reached)
-	require.Len(t, f.Calls, 3)
-}
-
-func TestProjectCreate_ValidationErrors(t *testing.T) {
-	f := &fakeGiteaMCP{}
-	skill, _ := newSkill(t, f)
-	cases := []struct {
-		name string
-		body string
-		want string
-	}{
-		{"missing name", `{"description":"d","hypothesis":"h","stack":"go-agent"}`, "name"},
-		{"missing description", `{"name":"x","hypothesis":"h","stack":"go-agent"}`, "description"},
-		{"missing hypothesis", `{"name":"x","description":"d","stack":"go-agent"}`, "hypothesis"},
-		{"bad stack", `{"name":"x","description":"d","hypothesis":"h","stack":"python"}`, "stack"},
-	}
-	for _, tc := range cases {
-		t.Run(tc.name, func(t *testing.T) {
-			_, err := skill.Handle(context.Background(), "project_create", json.RawMessage(tc.body))
-			require.Error(t, err)
-			assert.True(t, strings.Contains(err.Error(), tc.want), "want %q in %v", tc.want, err)
-		})
-	}
-	assert.Empty(t, f.Calls, "no upstream calls should occur on validation failure")
-}
-
-func TestProjectCreate_DefaultSkipsGitHubMirror(t *testing.T) {
-	// Default (mirror_to_github omitted) skips create_github_repo + mirror
-	// per the Gitea-as-true-master ADR. Gitea repo + staging namespace
-	// + issue still run; github_url is empty in the response.
-	f := &fakeGiteaMCP{
-		Responses: map[string]any{
-			"issue_create": map[string]any{"html_url": "http://gitea.d-ma.be/mathias/my-experiment/issues/1"},
-		},
-	}
-	skill, gh := newSkill(t, f)
-
-	out, err := skill.Handle(context.Background(), "project_create", happyArgs())
-	require.NoError(t, err)
-
-	var res map[string]any
-	require.NoError(t, json.Unmarshal(out, &res))
-
-	assert.Equal(t, "http://gitea.d-ma.be/mathias/my-experiment", res["gitea_url"])
-	assert.Equal(t, "", res["github_url"], "github_url must be empty when mirror not opted in")
-	assert.Equal(t, "http://gitea.d-ma.be/mathias/my-experiment/issues/1", res["issue_url"])
-
-	// 3 gitea-mcp calls: template create, staging file write, issue. NO mirror call.
-	require.Len(t, f.Calls, 3)
-	assert.Equal(t, "create_project_from_template", f.Calls[0].Tool)
-	assert.Equal(t, "file_write_branch", f.Calls[1].Tool)
-	assert.Equal(t, "issue_create", f.Calls[2].Tool)
-
-	// Zero GitHub API calls.
-	assert.Empty(t, gh.Calls, "no GitHub repo created when mirror_to_github is false")
-
-	// reached lists the Gitea-only path.
-	reached := res["reached"].([]any)
-	assert.Equal(t, []any{"create_repo", "infra_commit", "issue"}, reached)
-
-	// experiment-brief body reflects Gitea-only provisioning.
-	require.Contains(t, f.Calls[2].Args["body"], "Gitea-only")
-	require.NotContains(t, f.Calls[2].Args["body"], "Push-mirror configured")
-}
-
-func TestProjectCreate_UnknownTool(t *testing.T) {
-	f := &fakeGiteaMCP{}
-	skill, _ := newSkill(t, f)
-	_, err := skill.Handle(context.Background(), "nope", happyArgs())
-	require.Error(t, err)
-}

internal/skills/project/skill.go

@@ -1,109 +0,0 @@
-// Package project implements the `project_create` MCP tool: a single-call
-// pipeline that creates a Gitea repo from a template, configures push-mirror
-// to GitHub, commits a staging namespace manifest to the infra repo, and
-// opens an experiment-brief issue on the new repo. See hyperguild gitea
-// issue #10 for the design.
-package project
-
-import (
-	"context"
-	"encoding/json"
-
-	"github.com/mathiasbq/supervisor/internal/githubclient"
-	"github.com/mathiasbq/supervisor/internal/mcpclient"
-	"github.com/mathiasbq/supervisor/internal/registry"
-)
-
-// Config holds the orchestration dependencies for the project skill.
-type Config struct {
-	// Client talks to the gitea-mcp server. project_create makes
-	// sequential calls (create_project_from_template, repo_mirror_push,
-	// file_write_branch, issue_create) through this client.
-	Client *mcpclient.Client
-
-	// GitHub is the client used to create the empty destination repo on
-	// GitHub before the push-mirror is configured. Gitea's push-mirror
-	// cannot push to a non-existent remote, so this step is mandatory
-	// when GitHubPAT is set. Pass nil to skip github repo creation
-	// entirely (degraded mode — mirror config will land but the actual
-	// sync to github will fail until the repo exists).
-	GitHub *githubclient.Client
-
-	// GiteaOwner is the org/user that owns the new repo and the infra repo
-	// the namespace manifest is committed to (typically "mathias").
-	GiteaOwner string
-
-	// GitHubOwner is the GitHub org/user the push-mirror targets
-	// (typically "mathiasb").
-	GitHubOwner string
-
-	// GitHubPAT is the personal access token used as the push-mirror
-	// password and to create the destination repo on GitHub. Must have
-	// `repo` scope. Never logged.
-	GitHubPAT string
-
-	// InfraRepo is the name of the infra repo on Gitea where the
-	// k3s/staging/<name>/namespace.yaml manifest gets committed
-	// (typically "infra").
-	InfraRepo string
-}
-
-// Skill exposes project_create as an MCP tool.
-type Skill struct{ cfg Config }
-
-// New constructs the project Skill.
-func New(cfg Config) *Skill { return &Skill{cfg: cfg} }
-
-// Name returns the skill identifier.
-func (s *Skill) Name() string { return "project" }
-
-// Tools returns the MCP tool definitions for this skill.
-func (s *Skill) Tools() []registry.ToolDef {
-	schema, _ := json.Marshal(map[string]any{
-		"type": "object",
-		"properties": map[string]any{
-			"name": map[string]any{
-				"type":        "string",
-				"pattern":     `^[a-z][a-z0-9-]{1,38}[a-z0-9]$`,
-				"description": "Lowercase repo name. 3-40 chars, must start with a letter.",
-			},
-			"description": map[string]any{"type": "string"},
-			"hypothesis":  map[string]any{"type": "string"},
-			"folder": map[string]any{
-				"type":        "string",
-				"description": "Informational only — appears in next_steps. Example: AGENTS, AI, QKX.",
-			},
-			"stack": map[string]any{
-				"type":        "string",
-				"enum":        []string{"go-agent", "go-web"},
-				"description": "Selects template-go-agent or template-go-web.",
-			},
-			"private": map[string]any{"type": "boolean"},
-			"mirror_to_github": map[string]any{
-				"type": "boolean",
-				"description": "Default false. When true, also create an empty GitHub repo " +
-					"and configure a push-mirror from Gitea. Opt-in per the Gitea-as-true-master " +
-					"ADR — only set true for open-source projects (hyperguild, gitea-mcp, template-*). " +
-					"Never set true for client projects, business logic, or personal experiments.",
-			},
-		},
-		"required": []string{"name", "description", "hypothesis", "stack"},
-	})
-	return []registry.ToolDef{
-		{
-			Name: "project_create",
-			Description: "Bootstrap a new project: Gitea repo from template, staging namespace manifest, " +
-				"experiment-brief issue. Optionally mirrors to GitHub when `mirror_to_github: true` " +
-				"(default false). Idempotent — re-running with an existing repo returns the existing URLs.",
-			InputSchema: schema,
-		},
-	}
-}
-
-// Handle dispatches the tool call.
-func (s *Skill) Handle(ctx context.Context, tool string, args json.RawMessage) (json.RawMessage, error) {
-	if tool != "project_create" {
-		return nil, errUnknownTool(tool)
-	}
-	return s.handleCreate(ctx, args)
-}

internal/skills/retrospective/handlers.go

@@ -1,76 +0,0 @@
-// internal/skills/retrospective/handlers.go
-package retrospective
-
-import (
-	"context"
-	"encoding/json"
-	"fmt"
-	"time"
-
-	"github.com/mathiasbq/supervisor/internal/session"
-)
-
-type retroArgs struct {
-	SessionID string `json:"session_id"`
-	Model     string `json:"model,omitempty"`
-}
-
-// Handle dispatches the retrospective tool call.
-func (s *Skill) Handle(ctx context.Context, tool string, args json.RawMessage) (json.RawMessage, error) {
-	if tool != "retrospective" {
-		return nil, fmt.Errorf("unknown retrospective tool: %s", tool)
-	}
-	var a retroArgs
-	if err := json.Unmarshal(args, &a); err != nil {
-		return nil, fmt.Errorf("parse args: %w", err)
-	}
-	if a.SessionID == "" {
-		return nil, fmt.Errorf("session_id is required")
-	}
-
-	model := a.Model
-	if model == "" {
-		model = s.cfg.DefaultModel
-	}
-
-	entries, err := session.Read(s.cfg.SessionsDir, a.SessionID)
-	if err != nil {
-		return nil, fmt.Errorf("read session log: %w", err)
-	}
-
-	logJSON, err := json.MarshalIndent(entries, "", "  ")
-	if err != nil {
-		return nil, fmt.Errorf("marshal session log: %w", err)
-	}
-
-	taskPrompt := fmt.Sprintf(
-		"SESSION_ID: %s\n\nSESSION_LOG:\n%s\n\nReview this session log. Identify what is novel or worth preserving as organizational knowledge. Provide structured insights.",
-		a.SessionID, string(logJSON),
-	)
-
-	if s.cfg.CompleteFunc == nil {
-		return nil, fmt.Errorf("no executor configured")
-	}
-	t0 := time.Now()
-	text, dur, err := s.cfg.CompleteFunc(ctx, model, s.cfg.SkillPrompt, taskPrompt)
-	if err != nil {
-		return nil, fmt.Errorf("retrospective model: %w", err)
-	}
-
-	msg := text
-	if len(msg) > 200 {
-		msg = msg[:200]
-	}
-	_ = session.Append(s.cfg.SessionsDir, a.SessionID, session.Entry{
-		SessionID:   a.SessionID,
-		Timestamp:   time.Now(),
-		Skill:       "retrospective",
-		Phase:       "retrospective",
-		FinalStatus: "ok",
-		ModelUsed:   model,
-		DurationMs:  time.Since(t0).Milliseconds(),
-		Message:     msg,
-	})
-
-	return json.Marshal(map[string]any{"text": text, "model": model, "duration_ms": dur})
-}

internal/skills/retrospective/handlers_test.go

@@ -1,41 +0,0 @@
-// internal/skills/retrospective/handlers_test.go
-package retrospective_test
-
-import (
-	"context"
-	"encoding/json"
-	"testing"
-
-	"github.com/mathiasbq/supervisor/internal/skills/retrospective"
-	"github.com/stretchr/testify/assert"
-	"github.com/stretchr/testify/require"
-)
-
-func TestHandle_Retrospective_RequiresSessionID(t *testing.T) {
-	s := retrospective.New(retrospective.Config{})
-	_, err := s.Handle(context.Background(), "retrospective", json.RawMessage(`{}`))
-	assert.Error(t, err)
-	assert.Contains(t, err.Error(), "session_id")
-}
-
-func TestHandle_Retrospective_BuildsPromptWithSessionLog(t *testing.T) {
-	var capturedTask string
-	s := retrospective.New(retrospective.Config{
-		SkillPrompt:  "retrospective discipline",
-		DefaultModel: "ollama/test",
-		SessionsDir:  t.TempDir(),
-		CompleteFunc: func(_ context.Context, _, _, user string) (string, int64, error) {
-			capturedTask = user
-			return "Key insight: the team resolved a tricky nil pointer issue via careful logging.", 75, nil
-		},
-	})
-
-	args, _ := json.Marshal(map[string]string{"session_id": "empty-session"})
-	out, err := s.Handle(context.Background(), "retrospective", args)
-	require.NoError(t, err)
-
-	var result map[string]any
-	require.NoError(t, json.Unmarshal(out, &result))
-	assert.Contains(t, result["text"], "nil pointer")
-	assert.Contains(t, capturedTask, "empty-session")
-}

internal/skills/retrospective/skill.go

@@ -1,49 +0,0 @@
-// internal/skills/retrospective/skill.go
-package retrospective
-
-import (
-	"context"
-	"encoding/json"
-
-	"github.com/mathiasbq/supervisor/internal/registry"
-)
-
-// CompleteFunc is the function used to call a local model.
-type CompleteFunc func(ctx context.Context, model, system, user string) (string, int64, error)
-
-// Config holds retrospective skill configuration.
-type Config struct {
-	SkillPrompt  string
-	DefaultModel string
-	SessionsDir  string
-	CompleteFunc CompleteFunc
-}
-
-// Skill implements registry.Skill for the retrospective tool.
-type Skill struct {
-	cfg Config
-}
-
-// New constructs a retrospective Skill.
-func New(cfg Config) *Skill { return &Skill{cfg: cfg} }
-
-// Name returns the skill name.
-func (s *Skill) Name() string { return "retrospective" }
-
-// Tools returns the MCP tool definitions.
-func (s *Skill) Tools() []registry.ToolDef {
-	return []registry.ToolDef{
-		{
-			Name:        "retrospective",
-			Description: "Consult a local model to analyse a completed session and identify what is novel or worth preserving as organizational knowledge.",
-			InputSchema: json.RawMessage(`{
-				"type": "object",
-				"required": ["session_id"],
-				"properties": {
-					"session_id": {"type": "string"},
-					"model":      {"type": "string"}
-				}
-			}`),
-		},
-	}
-}

internal/skills/review/handlers.go

@@ -1,83 +0,0 @@
-// internal/skills/review/handlers.go
-package review
-
-import (
-	"context"
-	"encoding/json"
-	"fmt"
-	"strings"
-	"time"
-
-	"github.com/mathiasbq/supervisor/internal/brain"
-	"github.com/mathiasbq/supervisor/internal/session"
-)
-
-type reviewArgs struct {
-	ProjectRoot string   `json:"project_root"`
-	Files       []string `json:"files"`
-	Context     string   `json:"context"`
-	Model       string   `json:"model"`
-	SessionID   string   `json:"session_id"`
-}
-
-// Handle dispatches the MCP tool call to the appropriate handler.
-func (s *Skill) Handle(ctx context.Context, tool string, args json.RawMessage) (json.RawMessage, error) {
-	if tool != "review" {
-		return nil, fmt.Errorf("unknown tool: %s", tool)
-	}
-	var a reviewArgs
-	if err := json.Unmarshal(args, &a); err != nil {
-		return nil, fmt.Errorf("parse args: %w", err)
-	}
-	if a.ProjectRoot == "" {
-		return nil, fmt.Errorf("project_root is required")
-	}
-	if len(a.Files) == 0 {
-		return nil, fmt.Errorf("files is required")
-	}
-
-	model := a.Model
-	if model == "" {
-		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 = session.PrependHistory(s.cfg.SessionsDir, a.SessionID, "review", task)
-	if brainCtx != "" {
-		task = brainCtx + "\n---\n\n" + task
-	}
-
-	if s.cfg.CompleteFunc == nil {
-		return nil, fmt.Errorf("no executor configured")
-	}
-	t0 := time.Now()
-	text, dur, err := s.cfg.CompleteFunc(ctx, model, s.cfg.SkillPrompt, task)
-	if err != nil {
-		return nil, err
-	}
-
-	if a.SessionID != "" && s.cfg.SessionsDir != "" {
-		msg := text
-		if len(msg) > 200 {
-			msg = msg[:200]
-		}
-		_ = session.Append(s.cfg.SessionsDir, a.SessionID, session.Entry{
-			SessionID:   a.SessionID,
-			Timestamp:   time.Now(),
-			Skill:       "review",
-			Phase:       "review",
-			ProjectRoot: a.ProjectRoot,
-			FinalStatus: "ok",
-			ModelUsed:   model,
-			DurationMs:  time.Since(t0).Milliseconds(),
-			Message:     msg,
-		})
-	}
-
-	return json.Marshal(map[string]any{"text": text, "model": model, "duration_ms": dur})
-}

internal/skills/review/handlers_test.go

@@ -1,53 +0,0 @@
-// internal/skills/review/handlers_test.go
-package review_test
-
-import (
-	"context"
-	"encoding/json"
-	"testing"
-
-	"github.com/mathiasbq/supervisor/internal/skills/review"
-	"github.com/stretchr/testify/assert"
-	"github.com/stretchr/testify/require"
-)
-
-func TestReviewToolRegistered(t *testing.T) {
-	sk := review.New(review.Config{SkillPrompt: "review rules"})
-	names := make([]string, 0)
-	for _, tool := range sk.Tools() {
-		names = append(names, tool.Name)
-	}
-	assert.Contains(t, names, "review")
-}
-
-func TestReviewRequiresProjectRoot(t *testing.T) {
-	sk := review.New(review.Config{SkillPrompt: "r"})
-	_, err := sk.Handle(context.Background(), "review", json.RawMessage(`{"files":["main.go"]}`))
-	assert.ErrorContains(t, err, "project_root")
-}
-
-func TestReviewRequiresFiles(t *testing.T) {
-	sk := review.New(review.Config{SkillPrompt: "r"})
-	_, err := sk.Handle(context.Background(), "review", json.RawMessage(`{"project_root":"/tmp"}`))
-	assert.ErrorContains(t, err, "files")
-}
-
-func TestReviewCallsCompleteFunc(t *testing.T) {
-	var capturedTask string
-	fakeFn := func(_ context.Context, _, _, user string) (string, int64, error) {
-		capturedTask = user
-		return "2 warnings found: missing error handling at line 42", 80, nil
-	}
-
-	sk := review.New(review.Config{SkillPrompt: "review rules", CompleteFunc: fakeFn, SessionsDir: t.TempDir()})
-	out, err := sk.Handle(context.Background(), "review", json.RawMessage(
-		`{"project_root":"/tmp/proj","files":["internal/foo/foo.go"],"context":"PR: add Foo helper"}`,
-	))
-	require.NoError(t, err)
-	assert.Contains(t, capturedTask, "internal/foo/foo.go")
-	assert.Contains(t, capturedTask, "PR: add Foo helper")
-
-	var result map[string]any
-	require.NoError(t, json.Unmarshal(out, &result))
-	assert.Contains(t, result["text"], "2 warnings found")
-}

internal/skills/review/skill.go

@@ -1,55 +0,0 @@
-// internal/skills/review/skill.go
-package review
-
-import (
-	"context"
-	"encoding/json"
-
-	"github.com/mathiasbq/supervisor/internal/registry"
-)
-
-// CompleteFunc is the function used to call a local model.
-type CompleteFunc func(ctx context.Context, model, system, user string) (string, int64, error)
-
-// Config holds dependencies for the review skill.
-type Config struct {
-	SkillPrompt   string
-	DefaultModel  string
-	CompleteFunc  CompleteFunc
-	SessionsDir   string
-	IngestBaseURL string
-}
-
-// Skill implements the review MCP tool.
-type Skill struct{ cfg Config }
-
-// New creates a new review Skill.
-func New(cfg Config) *Skill { return &Skill{cfg: cfg} }
-
-// Name returns the skill identifier.
-func (s *Skill) Name() string { return "review" }
-
-// Tools returns the MCP tool definitions for this skill.
-func (s *Skill) Tools() []registry.ToolDef {
-	schema := func(required []string, props map[string]any) json.RawMessage {
-		b, _ := json.Marshal(map[string]any{"type": "object", "required": required, "properties": props})
-		return b
-	}
-	str := map[string]any{"type": "string"}
-	return []registry.ToolDef{
-		{
-			Name:        "review",
-			Description: "Consult a local model for a structured code review of the specified files. Returns findings with severity levels.",
-			InputSchema: schema(
-				[]string{"project_root", "files"},
-				map[string]any{
-					"project_root": str,
-					"files":        map[string]any{"type": "array", "items": map[string]any{"type": "string"}},
-					"context":      str,
-					"model":        str,
-					"session_id":   str,
-				},
-			),
-		},
-	}
-}

internal/skills/trainer/handlers.go

@@ -1,87 +0,0 @@
-// internal/skills/trainer/handlers.go
-package trainer
-
-import (
-	"context"
-	"encoding/json"
-	"fmt"
-	"time"
-
-	"github.com/mathiasbq/supervisor/internal/session"
-)
-
-type trainArgs struct {
-	SessionID string `json:"session_id"`
-	Model     string `json:"model"`
-}
-
-// Handle dispatches the MCP tool call to the trainer handler.
-func (s *Skill) Handle(ctx context.Context, tool string, args json.RawMessage) (json.RawMessage, error) {
-	if tool != "trainer" {
-		return nil, fmt.Errorf("unknown tool: %s", tool)
-	}
-	var a trainArgs
-	if err := json.Unmarshal(args, &a); err != nil {
-		return nil, fmt.Errorf("parse args: %w", err)
-	}
-	if a.SessionID == "" {
-		return nil, fmt.Errorf("session_id is required")
-	}
-	if s.cfg.CompleteFunc == nil {
-		return nil, fmt.Errorf("no executor configured")
-	}
-
-	model := a.Model
-	if model == "" {
-		model = s.cfg.DefaultModel
-	}
-
-	entries, err := session.Read(s.cfg.SessionsDir, a.SessionID)
-	if err != nil {
-		return nil, fmt.Errorf("read session log: %w", err)
-	}
-
-	// ── Step 1: Reader ────────────────────────────────────────────────────────
-	history := session.FormatHistory(entries, "")
-	readerTask := fmt.Sprintf(
-		"role: reader\nsession_id: %s\nbrain_dir: %s\n\n%s",
-		a.SessionID, s.cfg.BrainDir, history,
-	)
-	readerText, _, err := s.cfg.CompleteFunc(ctx, model, s.cfg.ReaderPrompt, readerTask)
-	if err != nil {
-		return nil, fmt.Errorf("reader: %w", err)
-	}
-
-	// ── Step 2: Writer (receives reader output) ───────────────────────────────
-	t0 := time.Now()
-	writerTask := fmt.Sprintf(
-		"role: writer\nsession_id: %s\nbrain_dir: %s\n\nreader_analysis:\n%s",
-		a.SessionID, s.cfg.BrainDir, readerText,
-	)
-	writerText, dur, err := s.cfg.CompleteFunc(ctx, model, s.cfg.WriterPrompt, writerTask)
-	if err != nil {
-		return nil, fmt.Errorf("writer: %w", err)
-	}
-
-	msg := writerText
-	if len(msg) > 200 {
-		msg = msg[:200]
-	}
-	_ = session.Append(s.cfg.SessionsDir, a.SessionID, session.Entry{
-		SessionID:   a.SessionID,
-		Timestamp:   time.Now(),
-		Skill:       "trainer",
-		Phase:       "trainer",
-		FinalStatus: "ok",
-		ModelUsed:   model,
-		DurationMs:  time.Since(t0).Milliseconds(),
-		Message:     msg,
-	})
-
-	return json.Marshal(map[string]any{
-		"reader_analysis": readerText,
-		"writer_output":   writerText,
-		"model":           model,
-		"duration_ms":     dur,
-	})
-}

internal/skills/trainer/handlers_test.go

@@ -1,73 +0,0 @@
-// internal/skills/trainer/handlers_test.go
-package trainer_test
-
-import (
-	"context"
-	"encoding/json"
-	"testing"
-
-	"github.com/mathiasbq/supervisor/internal/session"
-	"github.com/mathiasbq/supervisor/internal/skills/trainer"
-	"github.com/stretchr/testify/assert"
-	"github.com/stretchr/testify/require"
-)
-
-func TestTrainerToolRegistered(t *testing.T) {
-	sk := trainer.New(trainer.Config{ReaderPrompt: "r", WriterPrompt: "w"})
-	names := make([]string, 0)
-	for _, tool := range sk.Tools() {
-		names = append(names, tool.Name)
-	}
-	assert.Contains(t, names, "trainer")
-}
-
-func TestTrainerRequiresSessionID(t *testing.T) {
-	sk := trainer.New(trainer.Config{ReaderPrompt: "r", WriterPrompt: "w"})
-	_, err := sk.Handle(context.Background(), "trainer", json.RawMessage(`{}`))
-	assert.ErrorContains(t, err, "session_id")
-}
-
-func TestTrainerCallsReaderThenWriter(t *testing.T) {
-	sessDir := t.TempDir()
-	require.NoError(t, session.Append(sessDir, "sess-1", session.Entry{
-		SessionID: "sess-1", Skill: "tdd", Phase: "red", FinalStatus: "ok",
-		Message: "wrote failing test", FilePath: "internal/foo/foo_test.go",
-	}))
-
-	callCount := 0
-	var readerTask, writerTask string
-
-	fakeFn := func(_ context.Context, _, sys, user string) (string, int64, error) {
-		callCount++
-		if callCount == 1 {
-			// reader call
-			readerTask = user
-			return "1 sft candidate found: first-pass clean TDD", 60, nil
-		}
-		// writer call
-		writerTask = user
-		return "written 1 knowledge entry to brain/knowledge/tdd-patterns.md", 70, nil
-	}
-
-	sk := trainer.New(trainer.Config{
-		ReaderPrompt: "reader rules",
-		WriterPrompt: "writer rules",
-		CompleteFunc: fakeFn,
-		SessionsDir:  sessDir,
-		BrainDir:     t.TempDir(),
-	})
-	out, err := sk.Handle(context.Background(), "trainer", json.RawMessage(`{"session_id":"sess-1"}`))
-	require.NoError(t, err)
-
-	assert.Equal(t, 2, callCount, "complete must be called exactly twice: reader then writer")
-	assert.Contains(t, readerTask, "role: reader")
-	assert.Contains(t, readerTask, "sess-1")
-	assert.Contains(t, readerTask, "wrote failing test")
-	assert.Contains(t, writerTask, "role: writer")
-	assert.Contains(t, writerTask, "sft candidate")
-
-	var result map[string]any
-	require.NoError(t, json.Unmarshal(out, &result))
-	assert.Contains(t, result["reader_analysis"], "sft candidate")
-	assert.Contains(t, result["writer_output"], "knowledge entry")
-}

internal/skills/trainer/skill.go

@@ -1,52 +0,0 @@
-// internal/skills/trainer/skill.go
-package trainer
-
-import (
-	"context"
-	"encoding/json"
-
-	"github.com/mathiasbq/supervisor/internal/registry"
-)
-
-// CompleteFunc is the function used to call a local model.
-type CompleteFunc func(ctx context.Context, model, system, user string) (string, int64, error)
-
-// Config holds dependencies for the trainer skill.
-type Config struct {
-	ReaderPrompt string
-	WriterPrompt string
-	DefaultModel string
-	CompleteFunc CompleteFunc
-	SessionsDir  string
-	BrainDir     string // root of brain/ directory
-}
-
-// Skill implements the trainer MCP tool.
-type Skill struct{ cfg Config }
-
-// New creates a new trainer Skill.
-func New(cfg Config) *Skill { return &Skill{cfg: cfg} }
-
-// Name returns the skill identifier.
-func (s *Skill) Name() string { return "trainer" }
-
-// Tools returns the MCP tool definitions for this skill.
-func (s *Skill) Tools() []registry.ToolDef {
-	schema := func(required []string, props map[string]any) json.RawMessage {
-		b, _ := json.Marshal(map[string]any{"type": "object", "required": required, "properties": props})
-		return b
-	}
-	return []registry.ToolDef{
-		{
-			Name:        "trainer",
-			Description: "Consult a local model to identify learning moments from a session log and suggest knowledge to preserve in the brain.",
-			InputSchema: schema(
-				[]string{"session_id"},
-				map[string]any{
-					"session_id": map[string]any{"type": "string"},
-					"model":      map[string]any{"type": "string"},
-				},
-			),
-		},
-	}
-}

skills/close-session/SKILL.md

@@ -7,14 +7,14 @@ description: Disciplined end-of-session closeout for a Claude.ai chat before arc
 
 Capture a finishing Claude.ai work session into durable storage before the chat is archived and its context is lost. The goal is simple and load-bearing: **after this runs, a fresh session (or another agent) can reconstruct what was decided, what was shipped, and what is still open — without the original chat.**
 
-This skill is **batch**: one session in, findings out, done. It does not loop or re-read its own fresh output semantically (see Phase 5). Run the phases in order. Stop at any confirmation gate that says STOP.
+This skill is **batch**: one session in, findings out, done. Run the phases in order. Stop at any confirmation gate that says STOP.
 
 ## Operating constraints (read first)
 
 - **Gitea owner is always `mathias`.** Never guess another owner.
 - **Ground-truth at HEAD before acting.** Issue bodies and doc references rot — stale hostnames, retired services, moved endpoints. Before closing/commenting on any issue, `gitea:issue_get` it fresh. Before asserting an infra fact, verify it; do not copy it from memory or from a stale issue body.
 - **Current infra truths** (verify rather than trust, but these are the known-good baseline): Gitea is `git.d-ma.be` (not `gitea.d-ma.be`). LiteLLM is `http://koala:30401/v1/` (public `https://llm-api.d-ma.be`); piguard runs NGINX Proxy Manager only — never reference `piguard:4000` or `koala:4000`. Identity provider is Authentik (Dex migration complete).
-- **Side-effects need a confirmation gate.** Closing issues, committing files, and writing to the brain are all real writes. Surface exactly what will happen and get a clear yes before doing it. Reads are free; writes are gated.
+- **Side-effects need a confirmation gate.** Closing issues and capturing to brain/Gitea/ai-sessions are real writes. Surface exactly what will happen and get a clear yes before doing it. Reads are free; writes are gated.
 - **Never fabricate.** If the session didn't produce a decision worth persisting, say so and skip that write. An empty-but-honest closeout beats an invented one.
 
 ## Phase 1 — Harvest
@@ -34,76 +34,46 @@ For every repo touched this session, get its true current state before proposing
 
 Do not write anything in this phase. This is the read pass.
 
-## Phase 3 — Confirm and act on issue changes
+## Phase 3 — Plan the issue changes
 
-Present a single consolidated plan of issue actions: which to close (with closing comment), which to file (discovered-but-deferred work — token-budget gaps, recorded limitations, v2 follow-ups), which to comment on. Include the exact title/body for any new issue and the closing rationale for any close.
+Decide the issue actions: which to close (with closing comment), which to file (discovered-but-deferred work — token-budget gaps, recorded limitations, v2 follow-ups), which to comment on. Include the exact title/body for any new issue and the closing rationale for any close.
 
-**GATE — STOP and get explicit confirmation before any issue write.** Issue closes and new issues are side-effects. Once confirmed, execute them (`gitea:issue_close`, `gitea:issue_create`, `gitea:issue_comment`, all owner `mathias`), correcting any rotted references you found in Phase 2 as you go.
+These actions are **carried into the Phase 4 capture call** as `tickets[]` rather than executed here with direct `gitea:issue_*` calls — routing them through capture puts each one into the I5 audit record. (Closing an issue that needs a separate explanatory comment first is the one case to do directly; otherwise prefer the capture path.)
 
-## Phase 4 — Commit the canonical session summary
+## Phase 4 — Capture (one uniform call)
 
-Write one summary file to `mathias/ai-sessions`, committed directly to `main` via `gitea:file_write_branch` (no PR — this repo is solo and unprotected; if branch protection is ever added, fall back to a branch + PR).
+Persist the session via a **single `capture` call** (the `brain:capture` MCP tool, live on the Claude.ai connector). Capture owns the writes server-side — insights → brain, action items → Gitea tickets, summary → ai-sessions — plus the I1 sovereignty gate, the I5 audit record, and the supersession/read-after-write discipline. The skill's job is to *assemble the payload*, not to write each store itself. Do NOT fall back to separate `gitea:file_write_branch` + `brain_write` steps unless `capture` is unreachable (see fallback below).
 
-**Path:** `summaries/claudeai/<YYYY-MM>/<YYYY-MM-DD>-<topic-slug>-<chatid8>.md`
+**Assemble one payload:**
-where `<chatid8>` is the first 8 chars of the chat's UUID if known, else a short stable slug. `claudeai` has no host segment — Claude.ai is Anthropic-side, not a homelab host.
 
-**Frontmatter — the REDUCED live-capture schema.** A live close-session capture cannot populate the batch-export telemetry (token counts, message counts, duration_ms, permission_mode) — those only exist in the account export pipeline. Write only what's truthfully known, and mark fidelity so a reader (or the batch pipeline) can tell a live capture from an export:
+- **`insights[]`** — the generalizable learnings from Phase 1 (decisions/failures worth re-reading). Each: `{text, wing, hall}`; add `supersede_slug` to revise a prior note in place instead of creating a duplicate. `hall` ∈ facts/decisions/failures/hypotheses/sources.
+- **`tickets[]`** — the issue actions from Phase 3: `{repo, action, ...}` where action ∈ create/close/comment. Owner is always `mathias` (server-forced).
+- **`summary`** — `{title, body, repos_touched}`. Capture writes it to `ai-sessions` and stamps `fidelity` in frontmatter. Body stays reconstructable: one-paragraph summary, decisions, key artifacts, open threads.
+- **`context`** — `{harness: "claudeai-chat", session_ref: <chatid8-or-slug>, fidelity: "live-capture", actor: "mathias", classification: <see gate below>}`.
 
-```yaml
+**THE CLASSIFICATION GATE (read before calling — this is where capture refuses).**
----
+Capture computes an **effective classification = the strictest across EVERY target it touches** (each insight's `wing`, each ticket's `repo`, and every entry in `summary.repos_touched`), then refuses if that effective level is `confidential` and the origin is us-nexus (claude.ai is us-nexus). Levels come from `classification.yaml` at the brain root (source of truth, #67), with the code defaults as the floor: `hyperguild`/`homelab` → internal; `client-*` → confidential; **anything untagged → confidential (fail-safe)**.
-title: "<concise session title>"
+- **Tagged `internal` today** (safe through claude.ai): wings `hyperguild`, `homelab`; repos `brain`, `ai-sessions`, `infra`, `hyperguild`, `homelab`, `tapir`, `agentsquad`, `jepa-fx-risk`, `swedsl`. Treat `classification.yaml` as authoritative — this list is a hint, not gospel.
-client: "claudeai"
+- Declare `context.classification: "internal"` for normal homelab work.
-interface: "claudeai-chat"
+- `summary.repos_touched`, insight `wing`s, and ticket `repo`s are classification INPUTS, not free-form metadata — every target must resolve `internal` or the whole capture escalates to `confidential` and the gate refuses via claude.ai. Listing the central homelab repos (incl. `brain`/`ai-sessions`) is now fine; they're tagged. The summary always lands in `ai-sessions` (internal), so the summary path itself never escalates.
-date: "<YYYY-MM-DD>"
+- If a session genuinely touched **`client-*` or otherwise-untagged** material, it cannot be captured through claude.ai — note that in the verdict rather than trying to force it.
-repos_touched: [<repo slugs>]
-topic_tags: [<tags>]
-outcome: "<shipped|in-progress|abandoned>"
-fidelity: "live-capture"   # NOT an export; reconstructed live from chat
-captured_by: "close-session-skill"
----
-```
 
-Do not invent the export-only fields. `fidelity: live-capture` is the honest signal; if the batch export later produces a richer summary for the same session, the export is source of truth and supersedes this.
+**GATE — dry-run first, then execute.**
+1. Call `capture` with `dry_run: true`. It validates the whole payload and returns the would-be receipt + `effective_classification`, writing nothing.
+2. **STOP. Show the dry-run receipt** (effective classification, the insights/tickets/summary that would land) and get explicit confirmation.
+3. On confirmation, call `capture` again with `dry_run: false`. Read the returned receipt: it is partial-aware (`errors[]`, per-item `ok`). Report exactly what landed.
 
-**Body** (keep it reconstructable, not exhaustive):
+If `capture` is **unreachable** (tool not on the connector — e.g. a session that started before a deploy; a tool-list refresh usually fixes it): say so. Only then fall back to the legacy inline path (`gitea:file_write_branch` summary + `brain_write`/`brain_update` + `brain_get` confirm), and note in the verdict that the I5 audit record was NOT produced.
-```markdown
-## One-paragraph summary
-## Decisions
-## Key artifacts
-## Open threads
-```
 
-**GATE — STOP, show the full file (path + frontmatter + body), get explicit confirmation before committing.**
+## Phase 5 — Verdict
-
-## Phase 5 — Brain orientation note (the durable "where we are" record)
-
-Write one brain note so a fresh session can orient without the chat. This uses the `brain_update`/`brain_get` verbs (live since 2026-06).
-
-**Target:** `wing: <domain>` (the project/topic domain, e.g. `hyperguild`, `jepa-fx`), `hall: decisions`. The note is a knowledge-type record (a decision/orientation), grouped by knowledge-type, not by interface surface.
-
-**Batch read-after-write discipline (important — do these in order, do not interleave):**
-
-1. **Read first, before any write.** Check whether an orientation note already exists for this wing/topic. Do your "does this already exist / what should I supersede" reads NOW, up front. BM25/keyword search and `brain_get` are immediate; semantic/vector search may lag up to ~5 min after a write, so never rely on a semantic query to find something you wrote earlier in this same run.
-2. **Write or supersede:**
-   - **New note** → `brain_write` (wing, hall: decisions). Returns `{id, path, content_hash}`.
-   - **Superseding a prior orientation note** → `brain_update` (slug or path, wing, hall, content, reason). Whole-note replace; stamps `supersedes`/`updated_at`; returns `{id, path, content_hash, superseded}`. Use this instead of a second `brain_write` to the same slug — blind re-write creates duplicates/contradictions, which is the exact failure brain_update exists to prevent.
-3. **Confirm it landed** via `brain_get(id)` and check the returned `content_hash` matches what the write returned. This is the read-after-write confirmation — do it with `brain_get`, never a semantic query.
-
-**RULE: no semantic/vector brain query after the first `brain_update` in this run.** The batch shape makes this natural — read up front, write, confirm by id. If you ever find the skill wanting to semantic-search a just-superseded note, stop and flag it (that's the signal the staleness window matters and needs the synchronous-reembed follow-up).
-
-**GATE — STOP, show the note (target wing/hall, new-vs-supersede, full content), get explicit confirmation before the brain write.**
-
-After the note lands, if it relates to a note in another wing, create the cross-link inline with `brain_tunnel(source, target)` (idempotent; both paths brain-relative, must be in different wings). Optionally append a `session_log` entry (`session_id`, `skill: close-session`, `phase`, `final_status`) for telemetry. Both are now callable directly from Claude.ai — no Claude Code/Crush handoff needed.
-
-## Phase 6 — Verdict
 
 Deliver a final "safe to archive" verdict in the chat. Either:
 
-- **SAFE TO ARCHIVE** — list what landed (issues closed/filed with numbers, summary path, brain note id, any tunnels) so the trail is auditable. Then list anything still in the user's queue (e.g. a PR awaiting their merge, a decision owed next session).
+- **SAFE TO ARCHIVE** — list what landed from the capture receipt (issues closed/filed with numbers, summary path, brain note ids/paths) so the trail is auditable. Then list anything still in the user's queue (e.g. a PR awaiting their merge, a decision owed next session).
-- **NOT YET** — name the specific gate that wasn't passed or the write that failed, and what to do about it.
+- **NOT YET** — name the specific gate that wasn't passed, the capture refusal reason, or the per-item error from the receipt, and what to do about it.
 
-Never claim safe-to-archive if any gated write was declined or errored. The verdict is the skill's contract: if it says safe, the session can be lost without losing the work.
+Never claim safe-to-archive if the capture refused, any receipt item errored, or a gated confirmation was declined. The verdict is the skill's contract: if it says safe, the session can be lost without losing the work.
 
-## Why the gates and the batch discipline matter
+## Why the gate and the single-call shape matter
 
-The whole point is durability across a context reset. Every gate is a place where a wrong write would silently corrupt the record (close the wrong issue, overwrite a good brain note, commit a half-truth). The batch read-discipline in Phase 5 exists because the brain's vector index refreshes out-of-band: write-then-semantically-reread in the same run can read stale, so the skill front-loads reads and confirms writes by id. Get those right and the skill does what it promises — nothing important is lost when the chat goes away.
+The whole point is durability across a context reset. The capture call is the one place a wrong payload would silently corrupt the record (close the wrong issue, escalate to a refusal, commit a half-truth), which is why it is dry-run-then-confirm. Routing everything through one `capture` keeps the supersession discipline, the read-after-write confirmation, and the I5 audit trail server-side — the skill never has to carry those rules itself, and every closeout is uniformly audited. Get the payload and the classification right and the skill does what it promises — nothing important is lost when the chat goes away.

specs/capture-implementation-report.md

@@ -0,0 +1,116 @@
+# Capture capability — implementation report (as-built)
+
+**Status:** Shipped 2026-06-23, tagged `v0.11.0`. Epic hyperguild #49 (sub-issues #50–#55) closed.
+**Spec:** `specs/capture-bdd-spec.md` (the design contract this implements).
+**Governed by:** `infra/docs/architecture/01-invariants.md` (I1–I5) + the I2 acceptance ledger entry in `infra/docs/security-baseline.md`.
+
+This document records what was actually built, where it lives, how it maps to the spec, and what was deferred — for onboarding and future audit. It does not restate the design rationale (see the spec and the linked brain entries).
+
+---
+
+## 1. Outcome
+
+One uniform capture capability — insights → brain, action items → Gitea tickets, optional summary → ai-sessions — reachable identically from every harness:
+
+- **In-process / direct-REST harnesses** (Claude Code CLI, Agentsquad, claude.ai Code, headless): `POST /capture` on the brain server.
+- **MCP-native harnesses** (claude.ai Chat/Cowork/Design, Crush, Pi, LLM Council): the `capture` MCP tool, reached over the existing `/mcp` OAuth connector.
+
+Both doors call the **same** `CaptureService`; only the transport and credential assembly differ. The persistence behaviour (validation, classification, I1 gate, orchestration, I5 audit, partial receipt) is written once.
+
+---
+
+## 2. Architecture (as-built)
+
+```
+                 POST /capture (REST)          capture MCP tool
+                 capturehttp.Handler           mcp.Server.brainCapture
+                          \                          /
+                           \   (auth → principal →  /
+                            \   origin; decode)    /
+                             v                    v
+                        capture.CaptureService (use-case, pure)
+            ┌───────────────┬───────────────┬──────────────┬───────────────┐
+        BrainStore     IssueTracker    SummaryWriter   ClassificationPolicy  AuditSink
+        brainstore.    gitea.Client    (nil today)     classification.Config  audit.Degrading
+        Store          (REST)                                                 Sink / SlogSink
+        │                                                                     │
+        api.WriteNote/UpdateNote/ReadNote (#45)                       LokiCentral + FileBuffer
+        + wing index + auto-tunnel + graph re-index                  + NtfyNotifier + Reconcile
+```
+
+- **`internal/capture/`** — the use-case + ports + entities. Pure; no I/O. Owns validation (fail-closed), effective-classification resolution (stricter wins), the **I1 sovereignty gate**, best-effort orchestration, the **two-phase I5 audit** (Reserve before writes / Record after), and the partial-aware receipt.
+- **`internal/brainstore/`** — concrete `BrainStore` wrapping the #45 `api` primitives + wiki upkeep (wing `_index`, auto-tunnel, graph re-index). The MCP `brain_write`/`brain_update`/`brain_get` handlers were re-pointed at it: one implementation, not two.
+- **`internal/classification/`** — `public < internal < confidential` taxonomy + per-wing/repo tags from an optional `classification.yaml`; fail-safe to confidential.
+- **`internal/gitea/`** — `IssueTracker` over the Gitea REST API; owner forced to `mathias`; token only in the Authorization header.
+- **`internal/capturehttp/`** — the REST adapter + the shared `Authenticate` / `DecodeRequest` / `OriginResolver` (also used by the MCP tool).
+- **`internal/audit/`** — `SlogSink` (default) and the `DegradingSink` (loki + durable `FileBuffer` + `NtfyNotifier` + `Reconcile`).
+- **`internal/mcp/`** — the `capture` relay tool + principal threading (re-derives the caller's principal from the Bearer header the chassis middleware discards).
+
+---
+
+## 3. Sub-issue → PR map
+
+| Sub | Issue | PR(s) | Delivered |
+|-----|-------|-------|-----------|
+| 49a | #50 | #56 | classification taxonomy + per-wing/repo tags (fail-safe to confidential) |
+| 49b | #51 | #57 | `CaptureService` use-case + ports + entities; `BrainStore` extraction (MCP re-pointed) |
+| 49c | #52 | #58 | Gitea `IssueTracker` (owner forced mathias; token never logged) |
+| 49d | #53 | #59 | `POST /capture` REST + OAuth2 + I1 sovereignty gate (server-derived origin) |
+| 49e | #54 | #60 | I5 audit path + classification-aware degradation (loki + buffer + reconcile) |
+| 49f | #55 | #61, infra #151 (ledger), #152 (deploy) | MCP `capture` relay tool + I2 ledger + I3 deploy |
+
+Predecessor: #45 (`brain_update`/`brain_get` verbs, PR #46) — the read-after-write contract capture reuses.
+
+---
+
+## 4. Invariant compliance
+
+| Inv | How satisfied |
+|-----|---------------|
+| **I1** sovereign containment | Effective classification = stricter(caller-declared, target-derived #50). Origin is **server-derived from the authenticated principal**, never `context.harness`. Confidential + us-nexus origin → refused before any write; refusal audited. Asserted-vs-derived mismatch → security event. |
+| **I2** deliberate acceptance | The relay's cross-harness reach is recorded in `infra/docs/security-baseline.md` with six containment properties + Revisit-if, **merged before relay code shipped** (infra #151). |
+| **I3** GitOps reconcilability | Env + `gitea-api-token` ExternalSecret under `infra/k3s/apps/supervisor/`, Flux-reconciled; image bumped by CD. No untracked runtime. |
+| **I5** auditability | Every capture emits a request-level audit record. Classification-aware degradation: confidential + sink-down → hard-refuse; internal/public + sink-down → durable local buffer + ntfy + reconcile-on-recovery; floor → refuse if nothing can record. |
+
+---
+
+## 5. Operational reference (env)
+
+Set on the `ingestion` deployment (`infra/k3s/apps/supervisor/ingestion-deployment.yaml`):
+
+| Env | Purpose | Notes |
+|-----|---------|-------|
+| `BRAIN_GITEA_URL` / `BRAIN_GITEA_TOKEN` | enables the `IssueTracker` → gates `/capture` + the MCP tool | token from 1P `DMABE_GITEA_API_TOKEN` via ESO; unset ⇒ capture disabled |
+| `BRAIN_LOKI_URL` | activates the `DegradingSink` | unset ⇒ `SlogSink` (audit to stdout → alloy → loki; no refuse/buffer semantics) |
+| `BRAIN_NTFY_URL` / `BRAIN_NTFY_TOKEN` | degraded-state alerts | optional |
+| `BRAIN_CAPTURE_SOVEREIGN_PRINCIPALS` | JWT subjects treated as sovereign-soil | comma-separated; static-token caller is always sovereign; unknown JWT ⇒ us-nexus (fail safe) |
+| `BRAIN_AUDIT_RECONCILE_INTERVAL` | buffer→loki replay tick | default 60s |
+
+The audit buffer lives at `<brain>/.audit-buffer/capture.jsonl` on the brain hostPath (nodeSelector-pinned to koala) — durable across restart without a separate PV.
+
+---
+
+## 6. Tests
+
+67 test functions across the six packages. Coverage maps to the spec's Gherkin: happy path, supersede-not-duplicate, fail-closed validation, partial-failure receipt, dry-run, stricter-classification-wins, I1 confidential-via-us-nexus-refused / via-sovereign-allowed / asserted-label-ignored / caller-cannot-forge-origin, I5 confidential-refuse / internal-buffer / floor-refuse / reconcile / buffer-survives-restart, and the MCP relay tool (forwards, preserves principal, unauth rejected). `task check` green.
+
+---
+
+## 7. Deferred (not in this epic)
+
+Tracked here so they aren't lost; file as issues when picked up:
+
+- **SKILL veneer** — the `close-session` SKILL becomes the claude.ai trigger/harvest layer that calls capture.
+- **Per-harness token provisioning** for Crush / Pi / LLM Council (claude.ai is done via the existing `/mcp` connector).
+- **Harvest adapters** — transcript-parse vs chat-memory-reconstruct vs agent-runlog, each assembling capture args at its own fidelity.
+- **`SummaryWriter` impl** — ai-sessions summary persistence (the port + path logic exist; the concrete writer is nil today, so a request with a summary fails that one item).
+
+---
+
+## 8. Brain learnings
+
+- `wiki/hyperguild/decisions/capture-classification-taxonomy`
+- `wiki/hyperguild/decisions/gate-on-server-derived-signals-fail-safe`
+- `wiki/hyperguild/decisions/two-phase-reserve-record-audit-gate`
+- `wiki/hyperguild/failures/mcp-bearer-middleware-discards-principal`
+- `wiki/hyperguild/facts/brain-mcp-embeddings-out-of-band-sync` (from #45, the predecessor)