fix(ci): skip context:sync's drift check under CI, matching dma-cli/gitea-mcp

hyperguild's Taskfile ran context:sync unconditionally in 'check', with no
guard for the CI runner having no ancestor .context/AGENT.md. That made it
silently regenerate AGENTS.md and .context/system-prompt.txt from project
context alone (82 lines vs. the committed, correct 430) and then fail its
own drift assertion against that wrong baseline every run -- a false
positive, not real drift. Verified locally: syncing with the real root
context reproduces the committed 430-line files byte for byte; syncing
without it (as CI does) produces the shorter fallback that triggered this.

Same guard dma-cli and gitea-mcp already carry, same rationale: drift is
now caught either on a developer machine or by infra's estate-wide
context-sync-drift CronJob (ADR-0019), which does have canonical access.

.context/system-prompt.txt

@@ -53,14 +53,30 @@ These rules apply to every task across every project, regardless of harness.
    logical change (one tool, one fix, one test) with passing tests. Main is always
    deployable. Never create long-lived feature branches.
 
-   **Exception — parallel agents on same repo:** If another agent is known to be
+   **The PR trigger is RISK, not concurrency.** `risk/low` work commits straight to
-   actively working on the same repo simultaneously, create a short-lived branch
+   main with CI as the gate — that is most work and is unchanged. `risk/medium` and
-   (`agent/<description>`), finish the task, and merge to main within the same
+   above opens a PR, even solo, even with nobody waiting to review it. This mirrors
-   session. Do not leave agent branches open between sessions.
+   the tiered merge model in `assessor-loop`
+   `method/transfer-to-a-regulated-organisation.md` §4.1, so the estate practises
+   what it sells instead of merging everything on green and claiming otherwise.
 
-   **Exception — external contributor or client four-eyes requirement:** Use
+   **Concurrency is NOT a reason to branch.** Measured 2026-08-29 across three real
-   PR flow only when a human reviewer outside the project is required. Document
+   collisions between parallel sessions: two were not branching problems at all — a
-   the reason in PROJECT.md.
+   generated artifact written to the same path by both (branching turns that into a
+   merge conflict on a 33k-line JSON), and uncommitted work in a shared checkout
+   (a per-session worktree fixes it) — and the third was an ordinary non-fast-forward
+   push resolved by rebase in seconds. Use a worktree per session on shared repos and
+   timestamp generated artifacts. Do not reach for a branch.
+
+   Branch+PR flow carries documented costs on solo repos: merging auto-closes gated
+   issues, review comments live on a thread separate from the issue's, and a
+   merged-and-deleted branch cannot be amended (brain:
+   `gitea-pr-merge-autoclose-and-review-comment-footguns`). Those are the price of
+   the `risk/medium`+ lane — paid deliberately, not incurred by accident.
+
+   **Exception — external contributor or client four-eyes requirement:** Use PR flow
+   when a human reviewer outside the project is required. Document the reason in
+   PROJECT.md.
 
 6. **Close the loop — every substantive task ends with the same ritual.** Shipping
    the code is not the end of the task; capturing it is. Run this unprompted:
@@ -78,6 +94,18 @@ These rules apply to every task across every project, regardless of harness.
    - Surface the brain entries and issue numbers in the closing summary so the
      trail is auditable.
 
+   **Chat is not a durable store. Never rely on Mathias remembering anything.**
+   Every gap, caveat, risk, open question and next step must land in one of four
+   places before the turn ends: **the brain**, **a repo** (code, docs, ADR),
+   **a tracker issue**, or **a plan file**. A finding stated only in conversation is
+   lost the moment the session closes — and this estate has repeatedly proved that a
+   remembered convention is an unreliable control.
+
+   This applies hardest to what is tempting to leave as a closing remark: "worth
+   knowing X isn't enforced yet", "this is a convention, not a gate", "we should
+   revisit Y". Those are exactly the items that need a locator. If it is worth
+   saying in a summary, it is worth writing where it can be found again without you.
+
 ## CAD sprint patterns
 
 Two CAD sprint archetypes (defs: brain `wiki/homelab/decisions/continuous-agentic-development-cad-concept-2026-06-16`):
@@ -148,10 +176,10 @@ Three machines on Tailscale:
 |---------|------|-----------|
 | koala | GPU inference, heavy compute | RTX 5070, runs k3s + llama-swap + shared postgres18/pgvector |
 | iguana | Services, builds | M2 Ultra Mac |
-| flamingo | Daily driver, edge | Mac mini, ~/dev is here |
+| flamingo | Daily driver, edge | Apple Silicon Mac, ~/dev is here |
 
 - **Model routing**: LiteLLM in front of llama-swap (local) + cloud APIs (when permitted)
-- **Orchestration**: k3s cluster across all three machines
+- **Orchestration**: k3s on koala only — single control-plane node, no workers (verified 2026-08-30). iguana and flamingo are on the tailnet but are not cluster members
 - **Networking**: Tailscale mesh
 
 ## Project landscape
@@ -247,10 +275,11 @@ When working on a project tagged with a client name:
 
 ## Harness-agnostic principles
 
-This context is designed to work with any AI coding tool:
+Supported harnesses (2026-09-01) — Cursor and Aider were dropped; do not
-- Claude Code, Cursor, Aider, Open WebUI, Charmbracelet Mods/Crush
+re-add adapters for them:
-- Pi Coding Agent, Mistral Vibe, Antigravity
+- Claude Code, Antigravity, OpenCode, Mistral Vibe, Crush, Pi Coding Agent
-- Any tool that accepts a system prompt or reads a markdown context file
+- Open WebUI, Charmbracelet Mods, or any tool that takes a system prompt string
+- Any other tool that reads `AGENTS.md`, which is the de facto convention
 
 The canonical source is always `.context/AGENT.md` (root) and `.context/PROJECT.md` (per-project).
 Derived files are committed (see *How context propagates* below) so a `git pull` on any host yields full agent context with no setup.
@@ -262,15 +291,29 @@ Canonical sources of truth:
 - Project: `<repo>/.context/PROJECT.md` (per-repo)
 
 Derived files (committed, regenerated by `task context:sync`):
-- `CLAUDE.md`, `AGENTS.md`, `.cursorrules`, `.aider.conventions.md`,
+- `CLAUDE.md`, `AGENTS.md`, `.context/system-prompt.txt`
-  `.context/system-prompt.txt`
+
+Repos still carrying `.cursorrules`, `.aider.conventions.md` or
+`.aider.conf.yml` are stale: nothing regenerates them. Delete them the next time
+you touch the repo, along with their entries in that repo's `task check`
+assertion.
 
 Workflow:
 1. Edit a canonical file. Run `task context:sync`. Commit canonical and
    derived together. Push.
-2. On any other host, `git pull` brings both. Claude Code (tree-walking)
+2. On any other host, `git pull` brings both. Which file a harness reads does
-   uses `CLAUDE.md`; Crush / Pi / Antigravity (cwd-only) use `AGENTS.md`;
+   NOT split cleanly by lookup strategy, so do not reason from the strategy:
-   Cursor uses `.cursorrules`; Aider uses `.aider.conventions.md`.
+   - `CLAUDE.md` — Claude Code (walks up the tree)
+   - `AGENTS.md` — Crush, Pi, Antigravity (cwd-only), OpenCode (project root,
+     global at `~/.config/opencode/AGENTS.md`), and Mistral Vibe, which **walks
+     up** from cwd and takes the first `AGENTS.md` it finds
+     (user-level `~/.vibe/AGENTS.md`)
+   - `.context/system-prompt.txt` — Open WebUI, Mods, raw API calls; not read by
+     any harness, it is for pasting
+
+   Vibe tree-walks for `AGENTS.md`, so "tree-walkers use CLAUDE.md" is false.
+   Each repo's `AGENTS.md` embeds the canonical and is the first one found from
+   inside that repo, so this works — but by construction, not by luck.
 3. `task check` runs `context:sync` then asserts `git status --porcelain`
    is empty over the derived files (catches both modified-tracked drift
    and missing-untracked adapters). A drift fails the check with a
@@ -281,7 +324,20 @@ unconditionally on every host, every harness.
 
 ## Engineering Skills
 
-Shared engineering skills live in the **`mathias/skills`** repo (`git.d-ma.be/mathias/skills`). Clone it to `~/dev/skills/` and run `SKILLS_CHECKOUT_DIR="$PWD" bash install.sh` there to wire every skill into your harnesses (Claude Code, Crush, Antigravity, Mistral Vibe) as native, on-demand skills. (Use `install.sh`, not `task install` — the latter is currently broken, skills#7.) Load at task start — not "on demand" but on schedule, before writing code. Browse `~/dev/skills/SKILLS_INDEX.md` for the full list.
+Shared engineering skills live in the **`mathias/skills`** repo (`git.d-ma.be/mathias/skills`). Load at task start — not "on demand" but on schedule, before writing code. Browse `SKILLS_INDEX.md` for the full list.
+
+**Claude Code** installs the repo as a plugin from the marketplace the same repo hosts. That path also carries the `secret-guard` and `pre-task-ritual` hooks and the brain/gitea/infra MCP servers, which symlinks cannot:
+
+```
+/plugin marketplace add https://git.d-ma.be/mathias/skills.git
+/plugin install skills@mathias
+```
+
+Skills are **namespaced** under Claude Code: load `tdd` as `skills:tdd`. The trigger table below uses bare names — prefix them.
+
+**Crush, Pi and OpenCode** have no plugin system and are wired by `install.sh` as one directory symlink per harness via `~/.agents/skills`. Do not clone the checkout into `~/dev`: that folder is iCloud-shared between the Macs and spans two path roots (`/Users/mathias` vs `/home/mathias` on koala), so a checkout there is a git working tree with two concurrent writers, and any absolute symlink stored in it is broken on one side by construction (skills#23). Leave `SKILLS_CHECKOUT_DIR` at its host-local default.
+
+Check a host with `task doctor` in the skills repo; it also runs automatically at session start via the plugin.
 
 **Skill trigger table — load before starting, not after getting stuck:**
 

.dispatch-allow

@@ -0,0 +1,2 @@
+# Presence of this file marks this repo as opt-in for headless dispatch.
+# See dispatch#3.

.gitea/workflows/cd.yml

@@ -45,6 +45,12 @@ jobs:
           set -e
           trap 'rm -rf /tmp/infra-update; rm -f ~/.ssh/infra_deploy_key' EXIT
           IMAGE_TAG="${{ github.sha }}"
+          # infra#311: github.sha is never empty in practice, but the manifest
+          # patch below is the same shape that took Flux down estate-wide on
+          # 2026-08-25 -- an empty tag yields `image: <repo>:`, which is invalid
+          # YAML and fails the ENTIRE Kustomization, not just this app. The
+          # assert costs nothing and removes the class.
+          [ -n "${IMAGE_TAG:-}" ] || { echo "IMAGE_TAG is empty - refusing to patch"; exit 1; }
           mkdir -p ~/.ssh
           echo "${{ secrets.INFRA_DEPLOY_KEY }}" > ~/.ssh/infra_deploy_key
           chmod 600 ~/.ssh/infra_deploy_key

.githooks/pre-commit

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+# Pre-commit secret scan for the hyperguild repo.
+#
+# task check -> security:gitleaks enforces this in CI, but CI is after the
+# push. This catches a staged secret before it ever leaves the machine --
+# the infra#39 rotation pass found exactly this class of leak (a printed
+# credential, committed, archived into git) and there was no local gate to
+# have caught it. Mirrors infra's own .githooks/pre-commit (infra#326).
+#
+# Enable once per clone:   git config core.hooksPath .githooks
+# Bypass if absolutely needed: git commit --no-verify
+
+set -euo pipefail
+
+GITLEAKS="$(command -v gitleaks || true)"
+if [[ -z "$GITLEAKS" && -x "$(go env GOPATH 2>/dev/null)/bin/gitleaks" ]]; then
+  GITLEAKS="$(go env GOPATH)/bin/gitleaks"
+fi
+
+if [[ -z "$GITLEAKS" ]]; then
+  echo "⚠ gitleaks not installed — skipping local secret scan (CI still enforces it)."
+  echo "  Install: go install github.com/zricethezav/gitleaks/v8@latest"
+  exit 0
+fi
+
+echo "→ Scanning staged changes for secrets..."
+if ! "$GITLEAKS" protect --staged --redact --config .gitleaks.toml >/dev/null 2>&1; then
+  echo "  ✗ gitleaks found a secret in the staged changes."
+  echo "    Review with: gitleaks protect --staged --redact --config .gitleaks.toml -v"
+  echo "    If it is a false positive, allowlist it in .gitleaks.toml or add a"
+  echo "    '# gitleaks:allow' comment. Do NOT --no-verify a real secret."
+  exit 1
+fi
+echo "  ✓ no staged secrets"

.gitleaks.toml

@@ -56,8 +56,16 @@ paths = [
   '''ingestion/internal/claudewatcher/watcher_test\.go$''',
 ]
 
-[[allowlists]]
+# infra#344: the allowlist that used to sit here is gone, and so is the reason
-description = "Literal placeholder word REDACTED matched as if it were a token (verified 2026-08-04: extracted Secret == 'REDACTED' exactly, gitleaks' curl-auth-header rule matched the placeholder text itself, not a real credential)"
+# for it. It suppressed docs/superpowers/plans/2026-04-22-phase4-attempt-wiring.md
-condition = "AND"
+# on the stated grounds that "extracted Secret == 'REDACTED' exactly ... the
-paths = ['''docs/superpowers/plans/2026-04-22-phase4-attempt-wiring\.md$''']
+# placeholder text itself, not a real credential" (verified 2026-08-04). That was
-regexes = ['''REDACTED''']
+# not what the file contained: line 1054 carried a real 40-char hex Gitea PAT in
+# an `Authorization: token ...` header. Confirmed dead by side-effect — GET
+# /api/v1/user with it returns 401 — and redacted in that file, so there is now
+# nothing to allowlist.
+#
+# The `paths` entry also made the block far broader than its description: gitleaks
+# ORs global allowlist clauses and ignores `condition = "AND"`, so the whole file
+# was immune, not just lines matching /REDACTED/. A live token added to that doc
+# would have been suppressed on the strength of a note about a different value.

.gitleaksignore

@@ -0,0 +1,33 @@
+# Historical gitleaks findings, dispositioned (infra#326 / infra#317).
+#
+# WHY THIS FILE AND NOT .gitleaks.toml:
+# This is a finding in git HISTORY, surfaced by the full-history audit
+# (`task security:gitleaks:history`). The working-tree scan that gates commits
+# (`task security:gitleaks`, the pre-commit hook, CI) is clean. Suppressing by
+# PATH in .gitleaks.toml would also blind the working-tree scan for that file
+# forever; a fingerprint pins one finding in one commit, so a NEW secret in the
+# same file still fires.
+#
+# History is not rewritten here, so the remediation for a real leak is
+# ROTATION -- making the committed value worthless -- never scrubbing.
+#
+# Dispositioned 2026-08-29. Re-check with: task security:gitleaks:history
+
+# --- Real credential, ALREADY DEAD -------------------------------------------
+# A Gitea PAT pasted into a CD-watching command in a planning doc
+# (`Authorization: token <40-hex>`, last_eight 3105a670).
+#
+# Verified dead 2026-08-29: authenticating against
+# GET https://git.d-ma.be/api/v1/user with this exact value returns 401, so the
+# committed token no longer grants anything. It was almost certainly invalidated
+# by the early-August rotation of the `mathias` PATs (the same rotation whose
+# fan-out caused infra#260, where CI copies of the old value kept failing).
+#
+# No rotation action outstanding. Kept as a fingerprint rather than removed from
+# history because history cannot be rewritten here.
+#
+# The generalisable lesson is recorded separately: a credential printed into a
+# doc/transcript is permanent, so the only remedy is rotating it -- which in
+# this case had already happened for unrelated reasons, by luck rather than by
+# the leak being noticed.
+c9310b1079478bf4430b0a2dfb25445d7ccc9b59:docs/superpowers/plans/2026-04-22-phase4-attempt-wiring.md:curl-auth-header:1053

AGENTS.md

@@ -48,14 +48,30 @@ These rules apply to every task across every project, regardless of harness.
    logical change (one tool, one fix, one test) with passing tests. Main is always
    deployable. Never create long-lived feature branches.
 
-   **Exception — parallel agents on same repo:** If another agent is known to be
+   **The PR trigger is RISK, not concurrency.** `risk/low` work commits straight to
-   actively working on the same repo simultaneously, create a short-lived branch
+   main with CI as the gate — that is most work and is unchanged. `risk/medium` and
-   (`agent/<description>`), finish the task, and merge to main within the same
+   above opens a PR, even solo, even with nobody waiting to review it. This mirrors
-   session. Do not leave agent branches open between sessions.
+   the tiered merge model in `assessor-loop`
+   `method/transfer-to-a-regulated-organisation.md` §4.1, so the estate practises
+   what it sells instead of merging everything on green and claiming otherwise.
 
-   **Exception — external contributor or client four-eyes requirement:** Use
+   **Concurrency is NOT a reason to branch.** Measured 2026-08-29 across three real
-   PR flow only when a human reviewer outside the project is required. Document
+   collisions between parallel sessions: two were not branching problems at all — a
-   the reason in PROJECT.md.
+   generated artifact written to the same path by both (branching turns that into a
+   merge conflict on a 33k-line JSON), and uncommitted work in a shared checkout
+   (a per-session worktree fixes it) — and the third was an ordinary non-fast-forward
+   push resolved by rebase in seconds. Use a worktree per session on shared repos and
+   timestamp generated artifacts. Do not reach for a branch.
+
+   Branch+PR flow carries documented costs on solo repos: merging auto-closes gated
+   issues, review comments live on a thread separate from the issue's, and a
+   merged-and-deleted branch cannot be amended (brain:
+   `gitea-pr-merge-autoclose-and-review-comment-footguns`). Those are the price of
+   the `risk/medium`+ lane — paid deliberately, not incurred by accident.
+
+   **Exception — external contributor or client four-eyes requirement:** Use PR flow
+   when a human reviewer outside the project is required. Document the reason in
+   PROJECT.md.
 
 6. **Close the loop — every substantive task ends with the same ritual.** Shipping
    the code is not the end of the task; capturing it is. Run this unprompted:
@@ -73,6 +89,18 @@ These rules apply to every task across every project, regardless of harness.
    - Surface the brain entries and issue numbers in the closing summary so the
      trail is auditable.
 
+   **Chat is not a durable store. Never rely on Mathias remembering anything.**
+   Every gap, caveat, risk, open question and next step must land in one of four
+   places before the turn ends: **the brain**, **a repo** (code, docs, ADR),
+   **a tracker issue**, or **a plan file**. A finding stated only in conversation is
+   lost the moment the session closes — and this estate has repeatedly proved that a
+   remembered convention is an unreliable control.
+
+   This applies hardest to what is tempting to leave as a closing remark: "worth
+   knowing X isn't enforced yet", "this is a convention, not a gate", "we should
+   revisit Y". Those are exactly the items that need a locator. If it is worth
+   saying in a summary, it is worth writing where it can be found again without you.
+
 ## CAD sprint patterns
 
 Two CAD sprint archetypes (defs: brain `wiki/homelab/decisions/continuous-agentic-development-cad-concept-2026-06-16`):
@@ -143,10 +171,10 @@ Three machines on Tailscale:
 |---------|------|-----------|
 | koala | GPU inference, heavy compute | RTX 5070, runs k3s + llama-swap + shared postgres18/pgvector |
 | iguana | Services, builds | M2 Ultra Mac |
-| flamingo | Daily driver, edge | Mac mini, ~/dev is here |
+| flamingo | Daily driver, edge | Apple Silicon Mac, ~/dev is here |
 
 - **Model routing**: LiteLLM in front of llama-swap (local) + cloud APIs (when permitted)
-- **Orchestration**: k3s cluster across all three machines
+- **Orchestration**: k3s on koala only — single control-plane node, no workers (verified 2026-08-30). iguana and flamingo are on the tailnet but are not cluster members
 - **Networking**: Tailscale mesh
 
 ## Project landscape
@@ -242,10 +270,11 @@ When working on a project tagged with a client name:
 
 ## Harness-agnostic principles
 
-This context is designed to work with any AI coding tool:
+Supported harnesses (2026-09-01) — Cursor and Aider were dropped; do not
-- Claude Code, Cursor, Aider, Open WebUI, Charmbracelet Mods/Crush
+re-add adapters for them:
-- Pi Coding Agent, Mistral Vibe, Antigravity
+- Claude Code, Antigravity, OpenCode, Mistral Vibe, Crush, Pi Coding Agent
-- Any tool that accepts a system prompt or reads a markdown context file
+- Open WebUI, Charmbracelet Mods, or any tool that takes a system prompt string
+- Any other tool that reads `AGENTS.md`, which is the de facto convention
 
 The canonical source is always `.context/AGENT.md` (root) and `.context/PROJECT.md` (per-project).
 Derived files are committed (see *How context propagates* below) so a `git pull` on any host yields full agent context with no setup.
@@ -257,15 +286,29 @@ Canonical sources of truth:
 - Project: `<repo>/.context/PROJECT.md` (per-repo)
 
 Derived files (committed, regenerated by `task context:sync`):
-- `CLAUDE.md`, `AGENTS.md`, `.cursorrules`, `.aider.conventions.md`,
+- `CLAUDE.md`, `AGENTS.md`, `.context/system-prompt.txt`
-  `.context/system-prompt.txt`
+
+Repos still carrying `.cursorrules`, `.aider.conventions.md` or
+`.aider.conf.yml` are stale: nothing regenerates them. Delete them the next time
+you touch the repo, along with their entries in that repo's `task check`
+assertion.
 
 Workflow:
 1. Edit a canonical file. Run `task context:sync`. Commit canonical and
    derived together. Push.
-2. On any other host, `git pull` brings both. Claude Code (tree-walking)
+2. On any other host, `git pull` brings both. Which file a harness reads does
-   uses `CLAUDE.md`; Crush / Pi / Antigravity (cwd-only) use `AGENTS.md`;
+   NOT split cleanly by lookup strategy, so do not reason from the strategy:
-   Cursor uses `.cursorrules`; Aider uses `.aider.conventions.md`.
+   - `CLAUDE.md` — Claude Code (walks up the tree)
+   - `AGENTS.md` — Crush, Pi, Antigravity (cwd-only), OpenCode (project root,
+     global at `~/.config/opencode/AGENTS.md`), and Mistral Vibe, which **walks
+     up** from cwd and takes the first `AGENTS.md` it finds
+     (user-level `~/.vibe/AGENTS.md`)
+   - `.context/system-prompt.txt` — Open WebUI, Mods, raw API calls; not read by
+     any harness, it is for pasting
+
+   Vibe tree-walks for `AGENTS.md`, so "tree-walkers use CLAUDE.md" is false.
+   Each repo's `AGENTS.md` embeds the canonical and is the first one found from
+   inside that repo, so this works — but by construction, not by luck.
 3. `task check` runs `context:sync` then asserts `git status --porcelain`
    is empty over the derived files (catches both modified-tracked drift
    and missing-untracked adapters). A drift fails the check with a
@@ -276,7 +319,20 @@ unconditionally on every host, every harness.
 
 ## Engineering Skills
 
-Shared engineering skills live in the **`mathias/skills`** repo (`git.d-ma.be/mathias/skills`). Clone it to `~/dev/skills/` and run `SKILLS_CHECKOUT_DIR="$PWD" bash install.sh` there to wire every skill into your harnesses (Claude Code, Crush, Antigravity, Mistral Vibe) as native, on-demand skills. (Use `install.sh`, not `task install` — the latter is currently broken, skills#7.) Load at task start — not "on demand" but on schedule, before writing code. Browse `~/dev/skills/SKILLS_INDEX.md` for the full list.
+Shared engineering skills live in the **`mathias/skills`** repo (`git.d-ma.be/mathias/skills`). Load at task start — not "on demand" but on schedule, before writing code. Browse `SKILLS_INDEX.md` for the full list.
+
+**Claude Code** installs the repo as a plugin from the marketplace the same repo hosts. That path also carries the `secret-guard` and `pre-task-ritual` hooks and the brain/gitea/infra MCP servers, which symlinks cannot:
+
+```
+/plugin marketplace add https://git.d-ma.be/mathias/skills.git
+/plugin install skills@mathias
+```
+
+Skills are **namespaced** under Claude Code: load `tdd` as `skills:tdd`. The trigger table below uses bare names — prefix them.
+
+**Crush, Pi and OpenCode** have no plugin system and are wired by `install.sh` as one directory symlink per harness via `~/.agents/skills`. Do not clone the checkout into `~/dev`: that folder is iCloud-shared between the Macs and spans two path roots (`/Users/mathias` vs `/home/mathias` on koala), so a checkout there is a git working tree with two concurrent writers, and any absolute symlink stored in it is broken on one side by construction (skills#23). Leave `SKILLS_CHECKOUT_DIR` at its host-local default.
+
+Check a host with `task doctor` in the skills repo; it also runs automatically at session start via the plugin.
 
 **Skill trigger table — load before starting, not after getting stuck:**
 

README.md

@@ -5,6 +5,11 @@ Instead of letting Claude Code do whatever it wants, hyperguild enforces structu
 workflows (TDD red/green/refactor), logs every session, and accumulates learnings
 into a searchable brain.
 
+**This repo is also where `brain-mcp` lives** — the MCP server at
+`brain-mcp.d-ma.be` that `brain_query`, `brain_write`, `brain_read`, `brain_edit`
+and `capture` are served from. It is not a separate deployable; see
+[Where brain-mcp lives](#where-brain-mcp-lives).
+
 ## Hypothesis
 
 > We believe routing skill tasks through local models, backed by brain context,
@@ -20,7 +25,7 @@ usage, the fast-model routing path should be reconsidered.
 
 **hyperguild = Claude Code + MCP.** This is a supervisor for Claude Code sessions specifically.
 For multi-agent orchestration (OpenCode + LiteLLM, executor/reviewer pipelines), see
-[agentsquad](http://gitea.d-ma.be/mathias/agentsquad) — a separate harness for a different
+[agentsquad](https://git.d-ma.be/mathias/agentsquad) — a separate harness for a different
 orchestration model. Skills (mathias/skills) are shared between both.
 
 ## How it works
@@ -44,6 +49,33 @@ brain/
 └── knowledge/      — legacy flat notes (migration pending: hyperguild#22)
 ```
 
+## Where brain-mcp lives
+
+`brain-mcp` is served from **`ingestion/internal/mcp`** in this repo, at
+**`brain-mcp.d-ma.be`**. It is a component *inside* the `ingestion` service, not
+a standalone deployable — one pod in the `supervisor` namespace serves the MCP
+endpoint, the REST API, and the claudewatcher together.
+
+| You are looking for | It is here |
+|---|---|
+| The MCP tool surface (`brain_query`, `brain_write`, `brain_read`, `brain_edit`, `capture`, …) | `ingestion/internal/mcp` |
+| The HTTP/REST API (`/query`, `/write`, `/ingest`) | `ingestion/internal/api` |
+| Session ingestion from Claude Code transcripts | `ingestion/internal/claudewatcher` |
+| The brain *content* (notes, wings, halls) | [`mathias/brain`](https://git.d-ma.be/mathias/brain) — a separate repo |
+| Deployment manifests | `config/supervisor` |
+
+### Why it is not its own repo
+
+Asked and decided in [#91](https://git.d-ma.be/mathias/hyperguild/issues/91)
+(part 2). `internal/mcp` imports 17 of ingestion's other internal packages and
+has exactly one importer — it is the MCP facade over the service's own
+internals, so "move it out" resolves to renaming `ingestion`, publishing 17
+packages as a shared library, or maintaining a shim. The discoverability problem
+that prompted the question is answered by naming it here instead.
+
+Full reasoning, including the reversal trigger: brain
+`wiki/hyperguild/decisions/brain-mcp-stays-in-ingestion-fix-discoverability-by-name`.
+
 ## Phase 1 tools (available now)
 
 | Tool | What it does |
@@ -58,7 +90,7 @@ brain/
 | `tier` | Returns the current connectivity tier (1=cloud, 2=LAN, 3=offline) |
 
 > **Note:** `tdd_red/green/refactor` and `spec` were retired in Plan 7 (2026-05-12).
-> They are now SKILL.md files in [mathias/skills](http://gitea.d-ma.be/mathias/skills).
+> They are now SKILL.md files in [mathias/skills](https://git.d-ma.be/mathias/skills).
 
 ## Connect a project
 
@@ -147,7 +179,7 @@ The routing pod selects models per skill call based on historical pass rate:
 
 ## Open issues
 
-See [issues](http://gitea.d-ma.be/mathias/hyperguild/issues) — key open items:
+See [issues](https://git.d-ma.be/mathias/hyperguild/issues) — key open items:
 
 - **#25** — skills platform overhaul (audit first, then lazy loading + brain feedback loop)
 - **#24** — reduce context burn from skill listing

Taskfile.yml

@@ -86,8 +86,26 @@ tasks:
   check:
     desc: Run all checks (context freshness + lint + test + vet) across all modules
     cmds:
-      - task: context:sync
+      # Context sync is skipped under CI, matching dma-cli, gitea-mcp, and the
+      # rest of the estate. It is not a preference: context-sync.sh walks UP
+      # the tree for the canonical .context/AGENT.md, which lives in local-dev
+      # and does not exist on a CI runner. Without this guard, the script
+      # silently falls back to "project context only" and regenerates AGENTS.md
+      # and .context/system-prompt.txt shorter than their committed, correct
+      # versions -- so the drift assertion fails every CI run for a purely
+      # environmental reason, not real drift. Verified, not assumed: this is
+      # exactly what was happening here (AGENTS.md 430 lines committed vs. an
+      # 82-line regeneration on the runner).
+      #
+      # The cost is real and worth stating: drift is therefore only ever caught
+      # on a developer machine, or by infra's estate-wide context-sync-drift
+      # CronJob (ADR-0019), which does have canonical access and is the actual
+      # enforcement mechanism now.
       - cmd: |
+          if [ -n "${CI:-}" ]; then
+            echo "✓ context sync: skipped in CI (no canonical AGENT.md on the runner)"
+          else
+            bash scripts/context-sync.sh
             drift=$(git status --porcelain -- AGENTS.md CLAUDE.md .context/system-prompt.txt 2>/dev/null)
             if [ -n "$drift" ]; then
               echo "ERROR: derived adapters drifted from canonical context." >&2
@@ -98,6 +116,7 @@ tasks:
               exit 1
             fi
             echo "✓ context: canonical and adapters are in sync"
+          fi
       - task: lint
       - task: test
       - task: vet

docs/superpowers/plans/2026-04-22-phase4-attempt-wiring.md

@@ -1051,7 +1051,7 @@ git push
 ```bash
 # Poll until complete (replace RUN_ID with the new run):
 curl -s "https://gitea.d-ma.be/api/v1/repos/mathias/hyperguild/actions/runs?limit=2" \
-  -H "Authorization: token 736a8c36adcc6ecb41fff56e5ae4d0eb3105a670" \
+  -H "Authorization: token <REDACTED-dead-gitea-pat-infra#344>" \
   | python3 -c "import sys,json; [print(r['id'],r['status'],r.get('conclusion','—')) for r in json.load(sys.stdin)['workflow_runs']]"
 ```
 

ingestion/cmd/server/main.go

@@ -144,6 +144,16 @@ func envInt(key string, fallback int) int {
 	return fallback
 }
 
+// buildNotifier returns the ntfy notifier, or a nil interface when
+// BRAIN_NTFY_URL is unset. A nil *interface* (not a typed-nil) is required so
+// DegradingSink/Reconcile and the governance observer skip it cleanly.
+func buildNotifier() audit.Notifier {
+	if n := audit.NewNtfyNotifier(os.Getenv("BRAIN_NTFY_URL"), os.Getenv("BRAIN_NTFY_TOKEN")); n != nil {
+		return n
+	}
+	return nil
+}
+
 // 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;
@@ -161,12 +171,7 @@ func buildAuditSink(ctx context.Context, brainDir string, logger *slog.Logger) c
 		logger.Error("capture audit buffer init", "err", err)
 		os.Exit(1)
 	}
-	// Keep notifier as a nil interface (not a typed-nil) when unconfigured
+	notifier := buildNotifier()
-	// 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()))
@@ -231,6 +236,11 @@ func main() {
 			fallbackModel := envOr("BRAIN_LLM_FALLBACK_MODEL", "gemma4:31b")
 			router.Fallback = llm.New(fallbackURL, "", fallbackModel, timeout)
 		}
+		if tertiaryURL := os.Getenv("BRAIN_LLM_TERTIARY_URL"); tertiaryURL != "" {
+			tertiaryModel := envOr("BRAIN_LLM_TERTIARY_MODEL", "gemini-2.5-flash")
+			tertiaryKey := os.Getenv("GEMINI_API_KEY")
+			router.Tertiary = llm.New(tertiaryURL, tertiaryKey, tertiaryModel, timeout)
+		}
 		answerComplete = router.Complete
 		logger.Info("brain answer LLM configured", "primary", primaryURL, "model", primaryModel)
 	}
@@ -490,7 +500,13 @@ func main() {
 		// 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))
+		// hyperguild#97: a governance-file rewrite gets the same trail a
+		// capture already gets, plus an out-of-band alert. Wired here because
+		// brain_edit_root needs the capture plumbing anyway — that is what
+		// re-derives the static principal its gate checks.
+		mcpSrv.WithGovernanceObserver(auditSink, buildNotifier())
+		logger.Info("capture enabled (REST + MCP tool)", "sovereign_principals", len(sovereign),
+			"governance_observer", true)
 	} else {
 		logger.Info("capture endpoint disabled (BRAIN_GITEA_TOKEN unset)")
 	}

ingestion/internal/api/handler.go

@@ -12,6 +12,7 @@ import (
 	"time"
 
 	"github.com/mathiasbq/hyperguild/ingestion/internal/brain"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/claim"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/extract"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/pipeline"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/search"
@@ -152,15 +153,24 @@ func writeHallNote(brainDir string, opts WriteNoteOptions) (string, error) {
 	if err != nil {
 		return "", err
 	}
-	if err := os.MkdirAll(filepath.Dir(dest), 0o755); err != nil {
-		return "", fmt.Errorf("create hall dir: %w", err)
-	}
-
 	existingFields, body := splitFrontmatter(opts.Content)
 	existingByKey := make(map[string]frontmatterField, len(existingFields))
 	for _, f := range existingFields {
 		existingByKey[f.key] = f
 	}
+
+	// Validate the claim-property envelope BEFORE creating the directory, so a
+	// rejected write leaves nothing behind — not even an empty hall dir
+	// (brain#21). Fail closed: a value outside the enum is worse than an absent
+	// one, because a lint skips what it cannot parse and the note then reads as
+	// classified while nothing acts on it.
+	if err := claim.ValidateEnvelope(scalarValues(existingFields)); err != nil {
+		return "", fmt.Errorf("claim envelope: %w", err)
+	}
+
+	if err := os.MkdirAll(filepath.Dir(dest), 0o755); err != nil {
+		return "", fmt.Errorf("create hall dir: %w", err)
+	}
 	emitted := make(map[string]bool, 6)
 
 	var fm strings.Builder
@@ -218,6 +228,25 @@ func writeHallNote(brainDir string, opts WriteNoteOptions) (string, error) {
 	return filepath.ToSlash(rel), nil
 }
 
+// scalarValues flattens frontmatter fields to key -> scalar value for
+// validation. Multi-line values (lists, nested blocks) yield the text after
+// the colon on the first line, which is empty for a list — correct here,
+// since every claim-property field is a scalar enum.
+func scalarValues(fields []frontmatterField) map[string]string {
+	out := make(map[string]string, len(fields))
+	for _, f := range fields {
+		if len(f.lines) == 0 {
+			continue
+		}
+		_, value, found := strings.Cut(f.lines[0], ":")
+		if !found {
+			continue
+		}
+		out[f.key] = strings.TrimSpace(value)
+	}
+	return out
+}
+
 // frontmatterField is one top-level YAML key from a frontmatter block,
 // along with its raw line and any indented continuation lines (e.g. a
 // bulleted list value spanning multiple lines).

ingestion/internal/api/handler_test.go

@@ -440,3 +440,60 @@ func TestIngestPath_Directory(t *testing.T) {
 	require.True(t, ok, "pages must be an array")
 	assert.NotEmpty(t, pagesSlice)
 }
+
+// --- brain#21: claim-property envelope on the write path -------------------
+
+func TestWriteNote_PreservesClaimEnvelopeVerbatim(t *testing.T) {
+	// writeHallNote already passes unknown keys through; this pins that
+	// behaviour for the envelope specifically, so a future refactor of the
+	// merge loop cannot silently drop it.
+	dir := t.TempDir()
+
+	rel, err := api.WriteNote(dir, api.WriteNoteOptions{
+		Content: "---\nhalf_life: durable\napplies: universal\nclaim_provenance: asserted\n---\n\nA durable claim.\n",
+		Wing:    "homelab",
+		Hall:    "decisions",
+	})
+	require.NoError(t, err)
+
+	got, err := os.ReadFile(filepath.Join(dir, filepath.FromSlash(rel)))
+	require.NoError(t, err)
+	assert.Contains(t, string(got), "half_life: durable")
+	assert.Contains(t, string(got), "applies: universal")
+	assert.Contains(t, string(got), "claim_provenance: asserted")
+}
+
+func TestWriteNote_RejectsInvalidClaimEnvelopeAndWritesNothing(t *testing.T) {
+	// Fail closed: a value outside the enum must not land. A lint skips what
+	// it cannot parse, so an unvalidated write produces a note that reads as
+	// classified while nothing acts on it.
+	dir := t.TempDir()
+
+	_, err := api.WriteNote(dir, api.WriteNoteOptions{
+		Content:  "---\nhalf_life: forever\nclaim_provenance: asserted\n---\n\nBody.\n",
+		Filename: "bad-envelope",
+		Wing:     "homelab",
+		Hall:     "facts",
+	})
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "half_life")
+
+	_, statErr := os.Stat(filepath.Join(dir, "wiki/homelab/facts/bad-envelope.md"))
+	assert.True(t, os.IsNotExist(statErr), "a rejected write must leave no file behind")
+}
+
+func TestWriteNote_RejectsClaimFieldWithoutProvenance(t *testing.T) {
+	dir := t.TempDir()
+
+	_, err := api.WriteNote(dir, api.WriteNoteOptions{
+		Content:  "---\napplies: homelab\n---\n\nBody.\n",
+		Filename: "no-provenance",
+		Wing:     "homelab",
+		Hall:     "facts",
+	})
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "claim_provenance")
+
+	_, statErr := os.Stat(filepath.Join(dir, "wiki/homelab/facts/no-provenance.md"))
+	assert.True(t, os.IsNotExist(statErr))
+}

ingestion/internal/claim/claim.go

@@ -0,0 +1,98 @@
+// Package claim validates the claim-property frontmatter that says when and
+// where a note's claim holds, and who decided that (brain#21).
+//
+// Two families were designed together and land separately. This is the
+// applicability envelope:
+//
+//	half_life:        volatile | seasonal | durable   — how fast it decays
+//	applies:          local | homelab | universal     — how widely it holds
+//	claim_provenance: asserted | inferred             — who set the above
+//
+// The strength family (confidence, contested) follows once the ingest-time
+// contradiction detector exists to populate it.
+//
+// Why the envelope is validated rather than merely accepted: a value outside
+// the enum is worse than an absent one. A lint skips what it cannot parse, so
+// the note reads as classified while nothing acts on it — the field becomes
+// decoration that suppresses the very review it was added to trigger.
+//
+// Why `applies` and not `scope`: `scope:` has been in use since brain#5 for
+// glossary terms (`homelab-core`, `project:<repo>`) — a disjoint value space
+// on the same key. The shipped schema keeps the name; this one takes another.
+package claim
+
+import (
+	"fmt"
+	"strings"
+)
+
+// Field names, exported so writers and lints agree on the spelling.
+const (
+	FieldHalfLife   = "half_life"
+	FieldApplies    = "applies"
+	FieldProvenance = "claim_provenance"
+)
+
+var (
+	halfLives   = []string{"volatile", "seasonal", "durable"}
+	appliesTo   = []string{"local", "homelab", "universal"}
+	provenances = []string{"asserted", "inferred"}
+)
+
+// ValidateEnvelope checks the envelope fields of one note's frontmatter.
+//
+// Absent fields are valid: the envelope is opt-in for new writes, and a
+// corpus-wide backfill is deliberately out of scope (brain#21) — inferring
+// 1113 notes' properties in bulk has the same failure mode as the extraction
+// pass that produced 28 wrong wikilinks out of 67.
+func ValidateEnvelope(fm map[string]string) error {
+	halfLife, hasHalfLife := present(fm, FieldHalfLife)
+	applies, hasApplies := present(fm, FieldApplies)
+	prov, hasProv := present(fm, FieldProvenance)
+
+	if hasHalfLife {
+		if err := oneOf(FieldHalfLife, halfLife, halfLives); err != nil {
+			return err
+		}
+	}
+	if hasApplies {
+		if err := oneOf(FieldApplies, applies, appliesTo); err != nil {
+			return err
+		}
+	}
+	if hasProv {
+		if err := oneOf(FieldProvenance, prov, provenances); err != nil {
+			return err
+		}
+	}
+
+	// The field and its provenance travel together or not at all. A value
+	// whose author is unknown cannot be trusted differently from one Mathias
+	// asserted, which is how an inferred guess hardens into accepted fact.
+	switch {
+	case (hasHalfLife || hasApplies) && !hasProv:
+		return fmt.Errorf("%s is required when %s or %s is set",
+			FieldProvenance, FieldHalfLife, FieldApplies)
+	case hasProv && !hasHalfLife && !hasApplies:
+		return fmt.Errorf("%s is set but neither %s nor %s is",
+			FieldProvenance, FieldHalfLife, FieldApplies)
+	}
+	return nil
+}
+
+// present reports a trimmed field value and whether it was set to anything
+// non-empty. A key written with an empty value is treated as absent rather
+// than as an error: that is a caller emitting a placeholder, not asserting.
+func present(fm map[string]string, key string) (string, bool) {
+	v := strings.TrimSpace(fm[key])
+	return v, v != ""
+}
+
+func oneOf(field, value string, allowed []string) error {
+	for _, a := range allowed {
+		if a == value {
+			return nil
+		}
+	}
+	return fmt.Errorf("%s: %q is not one of %s", field, value, strings.Join(allowed, ", "))
+}

ingestion/internal/claim/claim_test.go

@@ -0,0 +1,89 @@
+// Package claim_test covers the claim-property envelope (brain#21).
+package claim_test
+
+import (
+	"testing"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/claim"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestValidateEnvelope(t *testing.T) {
+	tests := []struct {
+		name    string
+		fm      map[string]string
+		wantErr string
+	}{
+		{
+			name: "absent is fine — the fields are opt-in on new writes",
+			fm:   map[string]string{"wing": "homelab", "hall": "facts"},
+		},
+		{
+			name: "complete envelope with provenance",
+			fm: map[string]string{
+				"half_life": "durable", "applies": "universal", "claim_provenance": "asserted",
+			},
+		},
+		{
+			name: "inferred provenance is equally valid — it just must be stated",
+			fm: map[string]string{
+				"half_life": "volatile", "applies": "local", "claim_provenance": "inferred",
+			},
+		},
+		{
+			// A value nobody can act on is worse than no value: a lint
+			// silently skips it, so the note looks classified and isn't.
+			name:    "unknown half_life value",
+			fm:      map[string]string{"half_life": "forever", "claim_provenance": "asserted"},
+			wantErr: `half_life: "forever" is not one of volatile, seasonal, durable`,
+		},
+		{
+			name:    "unknown applies value",
+			fm:      map[string]string{"applies": "galaxy", "claim_provenance": "asserted"},
+			wantErr: `applies: "galaxy" is not one of local, homelab, universal`,
+		},
+		{
+			// brain#21: a value a model inferred must never be
+			// indistinguishable from one Mathias asserted. Writing the field
+			// without saying who set it is exactly that laundering.
+			name:    "envelope field without provenance",
+			fm:      map[string]string{"half_life": "durable"},
+			wantErr: "claim_provenance is required when half_life or applies is set",
+		},
+		{
+			name:    "applies without provenance",
+			fm:      map[string]string{"applies": "homelab"},
+			wantErr: "claim_provenance is required when half_life or applies is set",
+		},
+		{
+			name:    "unknown provenance value",
+			fm:      map[string]string{"half_life": "durable", "claim_provenance": "probably"},
+			wantErr: `claim_provenance: "probably" is not one of asserted, inferred`,
+		},
+		{
+			// Provenance alone says who set fields that aren't there.
+			name:    "provenance without any envelope field",
+			fm:      map[string]string{"claim_provenance": "asserted"},
+			wantErr: "claim_provenance is set but neither half_life nor applies is",
+		},
+		{
+			// The glossary wing has used scope: homelab-core since #5. The
+			// envelope deliberately does NOT claim that key (brain#21).
+			name: "glossary scope is untouched",
+			fm:   map[string]string{"scope": "homelab-core", "term": "koala"},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			err := claim.ValidateEnvelope(tt.fm)
+			if tt.wantErr == "" {
+				assert.NoError(t, err)
+				return
+			}
+			require.Error(t, err)
+			assert.Contains(t, err.Error(), tt.wantErr)
+		})
+	}
+}

ingestion/internal/llm/router.go

@@ -5,14 +5,18 @@ import (
 	"fmt"
 )
 
-// Router calls Primary first; on any error falls back to Fallback.
+// Router calls Primary first; on any error falls back to Fallback, then to
-// Fallback may be nil, in which case primary errors are returned directly.
+// Tertiary. Fallback and Tertiary may each be nil — a nil tier is skipped and
+// the chain returns the errors accumulated so far.
 type Router struct {
 	Primary  *Client
 	Fallback *Client
+	Tertiary *Client
 }
 
-// Complete implements pipeline.CompleteFunc, routing through Primary then Fallback.
+// Complete implements pipeline.CompleteFunc, routing through Primary, then
+// Fallback, then Tertiary — trying each configured tier in order and
+// returning the first success.
 func (r *Router) Complete(ctx context.Context, system, user string) (string, error) {
 	out, err := r.Primary.Complete(ctx, system, user)
 	if err == nil {
@@ -22,8 +26,15 @@ func (r *Router) Complete(ctx context.Context, system, user string) (string, err
 		return "", fmt.Errorf("primary llm: %w", err)
 	}
 	out, err2 := r.Fallback.Complete(ctx, system, user)
-	if err2 != nil {
+	if err2 == nil {
+		return out, nil
+	}
+	if r.Tertiary == nil {
 		return "", fmt.Errorf("primary llm: %w; fallback llm: %v", err, err2)
 	}
+	out, err3 := r.Tertiary.Complete(ctx, system, user)
+	if err3 != nil {
+		return "", fmt.Errorf("primary llm: %w; fallback llm: %v; tertiary llm: %v", err, err2, err3)
+	}
 	return out, nil
 }

ingestion/internal/llm/router_test.go

@@ -69,3 +69,78 @@ func TestRouter_NilFallback(t *testing.T) {
 	_, err := r.Complete(context.Background(), "sys", "user")
 	assert.Error(t, err)
 }
+
+func TestRouter_FallsBackToTertiaryWhenPrimaryAndFallbackFail(t *testing.T) {
+	fail := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		http.Error(w, "unavailable", http.StatusServiceUnavailable)
+	}))
+	defer fail.Close()
+	tertiary := mockServer(t, "from-tertiary")
+	defer tertiary.Close()
+
+	r := &Router{
+		Primary:  New(fail.URL, "", "m", time.Second),
+		Fallback: New(fail.URL, "", "m", time.Second),
+		Tertiary: New(tertiary.URL, "", "m", time.Second),
+	}
+	out, err := r.Complete(context.Background(), "sys", "user")
+	require.NoError(t, err)
+	assert.Equal(t, "from-tertiary", out)
+}
+
+func TestRouter_TertiaryNotCalledWhenFallbackSucceeds(t *testing.T) {
+	fail := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		http.Error(w, "unavailable", http.StatusServiceUnavailable)
+	}))
+	defer fail.Close()
+	fallback := mockServer(t, "from-fallback")
+	defer fallback.Close()
+	tertiary := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		t.Error("tertiary must not be called when fallback succeeds")
+	}))
+	defer tertiary.Close()
+
+	r := &Router{
+		Primary:  New(fail.URL, "", "m", time.Second),
+		Fallback: New(fallback.URL, "", "m", time.Second),
+		Tertiary: New(tertiary.URL, "", "m", time.Second),
+	}
+	out, err := r.Complete(context.Background(), "sys", "user")
+	require.NoError(t, err)
+	assert.Equal(t, "from-fallback", out)
+}
+
+func TestRouter_AllThreeFail(t *testing.T) {
+	fail := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		http.Error(w, "err", http.StatusBadGateway)
+	}))
+	defer fail.Close()
+
+	r := &Router{
+		Primary:  New(fail.URL, "", "m", time.Second),
+		Fallback: New(fail.URL, "", "m", time.Second),
+		Tertiary: New(fail.URL, "", "m", time.Second),
+	}
+	_, err := r.Complete(context.Background(), "sys", "user")
+	assert.Error(t, err)
+	assert.Contains(t, err.Error(), "primary llm")
+	assert.Contains(t, err.Error(), "fallback llm")
+	assert.Contains(t, err.Error(), "tertiary llm")
+}
+
+func TestRouter_NilTertiary(t *testing.T) {
+	// Existing 2-tier deployments (no BRAIN_LLM_TERTIARY_URL) must keep working
+	// exactly as before — Tertiary is opt-in, not required.
+	fail := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		http.Error(w, "err", http.StatusBadGateway)
+	}))
+	defer fail.Close()
+
+	r := &Router{
+		Primary:  New(fail.URL, "", "m", time.Second),
+		Fallback: New(fail.URL, "", "m", time.Second),
+	}
+	_, err := r.Complete(context.Background(), "sys", "user")
+	assert.Error(t, err)
+	assert.NotContains(t, err.Error(), "tertiary")
+}

ingestion/internal/mcp/server.go

@@ -49,6 +49,8 @@ type rpcError struct {
 // Server handles MCP JSON-RPC over HTTP for the ingestion service.
 type Server struct {
 	brainDir  string
+	govAudit  capture.AuditSink
+	govNotify govNotifier
 	pipeline  pipeline.Config
 	llm       pipeline.CompleteFunc
 	answerLLM pipeline.CompleteFunc // nil = brain_answer and brain_classify unavailable

ingestion/internal/mcp/tools_notes.go

@@ -6,8 +6,11 @@ import (
 	"fmt"
 	"log/slog"
 	"strings"
+	"time"
 
 	"github.com/mathiasbq/hyperguild/ingestion/internal/brain"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/capture"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/classification"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/notes"
 )
 
@@ -52,6 +55,20 @@ func noteToolDescriptors() []map[string]any {
 	}
 }
 
+// --- hyperguild#97: governance-rewrite observability -----------------------
+
+// govNotifier raises an out-of-band alert. Declared here rather than importing
+// internal/audit so the MCP package keeps depending on capture alone.
+type govNotifier interface {
+	Notify(ctx context.Context, msg string) error
+}
+
+// WithGovernanceObserver attaches the audit sink and notifier that observe a
+// successful brain_edit_root. Both are optional; either may be nil.
+func (s *Server) WithGovernanceObserver(sink capture.AuditSink, n govNotifier) {
+	s.govAudit, s.govNotify = sink, n
+}
+
 type brainReadArgs struct {
 	Path string `json:"path"`
 }
@@ -75,8 +92,17 @@ type brainEditArgs struct {
 }
 
 // brainEdit is the model-facing editor: notes only.
+//
+// Deliberately NOT audited (#97). A note edit is already fully reconstructible
+// from git history, which carries the same before/after bytes plus a diff.
+// Governance files get the extra trail because they change what later agents
+// obey — the asymmetry is about instruction-carrying content, not about how
+// hard the change is to reconstruct. Auditing every note edit would also bury
+// the rare governance record under routine traffic, which is how an alert
+// stops being read.
 func (s *Server) brainEdit(_ context.Context, args json.RawMessage) (json.RawMessage, error) {
-	return s.editWithScope(args, notes.ScopeNotes)
+	_, out, err := s.editWithScope(args, notes.ScopeNotes)
+	return out, err
 }
 
 // brainEditRoot edits a governance file (CLAUDE.md). De-surfaced AND gated on
@@ -89,22 +115,72 @@ func (s *Server) brainEditRoot(ctx context.Context, args json.RawMessage) (json.
 		return nil, fmt.Errorf("brain_edit_root requires the local static principal; " +
 			"a governance file is not editable from a model-facing origin")
 	}
-	out, err := s.editWithScope(args, notes.ScopeRoot)
+	res, out, err := s.editWithScope(args, notes.ScopeRoot)
-	if err == nil {
+	if err != nil {
+		// A refusal is not a rewrite. Recording or alerting on one would cry
+		// wolf, and the gate already logs its own denials.
+		return out, err
+	}
 	// A durable instruction rewrite should be loud, not silent.
 	slog.Warn("brain_edit_root applied", "principal", info.principal, "result", string(out))
-	}
+	s.observeGovernanceEdit(ctx, info.principal, res)
 	return out, err
 }
 
-func (s *Server) editWithScope(args json.RawMessage, scope notes.Scope) (json.RawMessage, error) {
+// observeGovernanceEdit records and alerts on a rewrite that already landed.
+//
+// Best-effort by construction: the bytes are written and brain-sync will commit
+// them within the quarter hour, so failing the call here would report a
+// non-rewrite to the caller while the rewrite sits on disk. A failure to
+// observe is therefore logged at ERROR — the one case where the trail itself is
+// what broke, and the only remaining signal.
+func (s *Server) observeGovernanceEdit(ctx context.Context, principal string, res notes.Result) {
+	// Path and hashes only. The notification leaves the cluster for a phone
+	// via a third-party topic; a hash identifies the rewrite, the bytes would
+	// leak whatever was written into an instruction file.
+	msg := fmt.Sprintf("brain_edit_root applied\npath=%s\nprincipal=%s\nbefore=%s\nafter=%s",
+		res.Path, principal, res.PrevContentHash, res.ContentHash)
+
+	if s.govNotify != nil {
+		if err := s.govNotify.Notify(ctx, msg); err != nil {
+			slog.Error("brain_edit_root notify failed", "path", res.Path, "err", err)
+		}
+	}
+	if s.govAudit == nil {
+		return
+	}
+	// Internal, not Confidential: a governance file is not client data, and
+	// Confidential would make DegradingSink REFUSE to record while loki is
+	// down rather than buffer — losing exactly the record that matters most.
+	outcome, err := s.govAudit.Reserve(ctx, classification.Internal)
+	if err != nil {
+		slog.Error("brain_edit_root audit reserve failed", "path", res.Path, "err", err)
+		return
+	}
+	entry := capture.AuditEntry{
+		Timestamp:               time.Now().UTC(),
+		Principal:               principal,
+		Actor:                   "brain_edit_root",
+		Harness:                 "mcp",
+		EffectiveClassification: classification.Internal.String(),
+		Items:                   []string{res.Path},
+		SecurityEvents: []string{fmt.Sprintf(
+			"governance file rewritten: %s before=%s after=%s",
+			res.Path, res.PrevContentHash, res.ContentHash)},
+	}
+	if err := s.govAudit.Record(ctx, entry, outcome); err != nil {
+		slog.Error("brain_edit_root audit record failed", "path", res.Path, "err", err)
+	}
+}
+
+func (s *Server) editWithScope(args json.RawMessage, scope notes.Scope) (notes.Result, json.RawMessage, error) {
 	var a brainEditArgs
 	if err := json.Unmarshal(args, &a); err != nil {
-		return nil, fmt.Errorf("parse args: %w", err)
+		return notes.Result{}, nil, fmt.Errorf("parse args: %w", err)
 	}
 	res, err := notes.Edit(s.brainDir, a.Path, a.OldStr, a.NewStr, scope)
 	if err != nil {
-		return nil, err
+		return notes.Result{}, nil, err
 	}
 
 	// Reindex only when the edit could have changed what the index reads.
@@ -121,7 +197,8 @@ func (s *Server) editWithScope(args json.RawMessage, scope notes.Scope) (json.Ra
 			res.ReindexError = ierr.Error()
 		}
 	}
-	return json.Marshal(res)
+	out, merr := json.Marshal(res)
+	return res, out, merr
 }
 
 // wingOf returns the wing for a wiki path, or "" for knowledge/ and root.

ingestion/internal/mcp/tools_notes_test.go

@@ -2,13 +2,22 @@
 package mcp_test
 
 import (
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
 	"encoding/json"
 	"net/http"
 	"net/http/httptest"
 	"os"
 	"path/filepath"
+	"strings"
 	"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"
@@ -125,3 +134,164 @@ func mustJSON(t *testing.T, v any) []byte {
 	require.NoError(t, err)
 	return b
 }
+
+// ---- hyperguild#97: a governance rewrite must be observed, not just gated ----
+
+// govSink captures audit records. Governance edits are rare, so the whole
+// history is kept and asserted on rather than sampled.
+type govSink struct {
+	entries  []capture.AuditEntry
+	outcomes []capture.AuditOutcome
+	recErr   error
+}
+
+func (s *govSink) Reserve(context.Context, classification.Level) (capture.AuditOutcome, error) {
+	return capture.AuditCentral, nil
+}
+
+func (s *govSink) Record(_ context.Context, e capture.AuditEntry, o capture.AuditOutcome) error {
+	s.entries = append(s.entries, e)
+	s.outcomes = append(s.outcomes, o)
+	return s.recErr
+}
+
+type govNotifier struct {
+	msgs []string
+	err  error
+}
+
+func (n *govNotifier) Notify(_ context.Context, msg string) error {
+	n.msgs = append(n.msgs, msg)
+	return n.err
+}
+
+// govServer wires capture (which is what re-derives the static principal) plus
+// the #97 observer, and returns the brain dir so the test can read the file.
+func govServer(t *testing.T) (*mcp.Server, string, *govSink, *govNotifier) {
+	t.Helper()
+	dir := newBrainRepo(t)
+	cfg, err := classification.Load(dir)
+	require.NoError(t, err)
+	svc := capture.NewService(brainstore.New(dir), capFakeTracker{}, cfg, audit.NewSlogSink(nil))
+
+	srv := mcp.NewServer(dir, nil, nil, nil)
+	srv.WithCapture(svc, nil, capStaticTok, "local-cli", capturehttp.NewOriginResolver(nil))
+	sink, notifier := &govSink{}, &govNotifier{}
+	srv.WithGovernanceObserver(sink, notifier)
+	return srv, dir, sink, notifier
+}
+
+// authCall is call() with an Authorization header, so the static principal is
+// present and brain_edit_root's gate opens.
+func authCall(t *testing.T, srv *mcp.Server, authz, name string, args map[string]any) map[string]any {
+	t.Helper()
+	req := httptest.NewRequest(http.MethodPost, "/mcp", body(t, map[string]any{
+		"jsonrpc": "2.0", "id": 1, "method": "tools/call",
+		"params": map[string]any{"name": name, "arguments": args},
+	}))
+	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 sha256hex(s string) string {
+	sum := sha256.Sum256([]byte(s))
+	return hex.EncodeToString(sum[:])
+}
+
+func TestBrainEditRoot_RecordsAnAuditEntryNamingPrincipalPathAndBothHashes(t *testing.T) {
+	// The gate proves a rewrite was ALLOWED. Only a record proves one HAPPENED
+	// — and brain-sync will commit it within 15 minutes authored `brain-sync`,
+	// so git history cannot tell it apart from routine note traffic.
+	srv, dir, sink, _ := govServer(t)
+
+	resp := authCall(t, srv, "Bearer "+capStaticTok, "brain_edit_root", map[string]any{
+		"path": "CLAUDE.md", "old_str": "# rules", "new_str": "# rewritten",
+	})
+	require.NotContains(t, resp, "error", "%v", resp["error"])
+
+	require.Len(t, sink.entries, 1, "exactly one audit record per governance rewrite")
+	e := sink.entries[0]
+	assert.Equal(t, "local-cli", e.Principal)
+	assert.Contains(t, e.Items, "CLAUDE.md", "the record must name what was rewritten")
+
+	joined := strings.Join(e.SecurityEvents, " ")
+	assert.Contains(t, joined, sha256hex("# rules\n"), "before-hash must be recorded")
+	assert.Contains(t, joined, sha256hex("# rewritten\n"), "after-hash must be recorded")
+	assert.NotZero(t, e.Timestamp)
+
+	got, err := os.ReadFile(filepath.Join(dir, "CLAUDE.md"))
+	require.NoError(t, err)
+	assert.Equal(t, "# rewritten\n", string(got))
+}
+
+func TestBrainEditRoot_NotifiesWithPathAndHashesButNeverContent(t *testing.T) {
+	srv, _, _, notifier := govServer(t)
+
+	resp := authCall(t, srv, "Bearer "+capStaticTok, "brain_edit_root", map[string]any{
+		"path": "CLAUDE.md", "old_str": "# rules", "new_str": "# rewritten",
+	})
+	require.NotContains(t, resp, "error", "%v", resp["error"])
+
+	require.Len(t, notifier.msgs, 1)
+	msg := notifier.msgs[0]
+	assert.Contains(t, msg, "CLAUDE.md")
+	assert.Contains(t, msg, "local-cli")
+	assert.Contains(t, msg, sha256hex("# rules\n"))
+	assert.Contains(t, msg, sha256hex("# rewritten\n"))
+
+	// The notification travels to a phone through a third-party topic. A hash
+	// identifies a rewrite; the bytes would leak whatever was written.
+	assert.NotContains(t, msg, "# rewritten", "no file content in the notification body")
+	assert.NotContains(t, msg, "# rules")
+}
+
+func TestBrainEditRoot_RefusedProducesNoRecordNoNotificationNoWrite(t *testing.T) {
+	srv, dir, sink, notifier := govServer(t)
+
+	// No Authorization header → no static principal → the gate stays shut.
+	resp := authCall(t, srv, "", "brain_edit_root", map[string]any{
+		"path": "CLAUDE.md", "old_str": "# rules", "new_str": "# rewritten",
+	})
+	require.Contains(t, resp, "error")
+
+	assert.Empty(t, sink.entries, "a refusal is not a rewrite — recording one would cry wolf")
+	assert.Empty(t, notifier.msgs)
+	got, err := os.ReadFile(filepath.Join(dir, "CLAUDE.md"))
+	require.NoError(t, err)
+	assert.Equal(t, "# rules\n", string(got))
+}
+
+func TestBrainEditRoot_FailedEditProducesNoRecordNoNotification(t *testing.T) {
+	// Authorised but no match: the door opened and nothing went through it.
+	srv, _, sink, notifier := govServer(t)
+
+	resp := authCall(t, srv, "Bearer "+capStaticTok, "brain_edit_root", map[string]any{
+		"path": "CLAUDE.md", "old_str": "absent-from-the-file", "new_str": "x",
+	})
+	require.Contains(t, resp, "error")
+
+	assert.Empty(t, sink.entries)
+	assert.Empty(t, notifier.msgs)
+}
+
+func TestBrainEdit_OnOrdinaryNotesIsNotAudited(t *testing.T) {
+	// The decided asymmetry (#97): note edits are covered by git history, which
+	// carries the same before/after bytes with a diff. Governance files get the
+	// extra trail because they change what later agents obey, not because they
+	// are harder to reconstruct.
+	srv, _, sink, notifier := govServer(t)
+
+	resp := authCall(t, srv, "Bearer "+capStaticTok, "brain_edit", map[string]any{
+		"path": "wiki/homelab/facts/n.md", "old_str": "beta", "new_str": "BETA",
+	})
+	require.NotContains(t, resp, "error", "%v", resp["error"])
+
+	assert.Empty(t, sink.entries, "note edits must not fill the governance audit trail")
+	assert.Empty(t, notifier.msgs)
+}

ingestion/internal/notes/edit.go

@@ -37,6 +37,10 @@ var pathLocks sync.Map // string -> *sync.Mutex
 // Result is what a successful edit reports.
 type Result struct {
 	Path string `json:"path"`
+	// PrevContentHash is the sha256 of the file as it was before this edit.
+	// Paired with ContentHash it identifies a rewrite in an audit trail or an
+	// alert without carrying any of the bytes (hyperguild#97).
+	PrevContentHash string `json:"prev_content_hash"`
 	ContentHash     string `json:"content_hash"`
 	BytesBefore     int    `json:"bytes_before"`
 	BytesAfter      int    `json:"bytes_after"`
@@ -149,8 +153,10 @@ func Edit(brainDir, path, oldStr, newStr string, scope Scope) (Result, error) {
 	}
 
 	sum := sha256.Sum256([]byte(after))
+	prev := sha256.Sum256(before)
 	return Result{
 		Path:            t.Rel,
+		PrevContentHash: hex.EncodeToString(prev[:]),
 		ContentHash:     hex.EncodeToString(sum[:]),
 		BytesBefore:     len(before),
 		BytesAfter:      len(after),

scripts/context-sync.sh

@@ -5,15 +5,29 @@
 # For Claude Code: generates project-only CLAUDE.md (it inherits root via tree walk)
 # For everything else: concatenates root AGENT.md + project PROJECT.md
 #
-# Usage: ./scripts/context-sync.sh [adapter...]
+# Cursor and Aider adapters removed 2026-09-01 — neither is a supported harness
+# any more. Supported: Claude Code, Antigravity, OpenCode, Mistral Vibe, Crush,
+# Pi. All read CLAUDE.md or AGENTS.md; system-prompt.txt remains for Open WebUI,
+# Mods and raw API use.
+#
+# Usage: ./scripts/context-sync.sh [--force] [adapter...]
 # Task:  task context:sync
 #
 # Override root context: ROOT_CONTEXT=~/dev/.context/AGENT.md ./scripts/context-sync.sh
 
 set -euo pipefail
 
+# Parse --force flag and collect adapter names separately
+FORCE=false
+ADAPTERS=()
+for _arg in "$@"; do
+  case "$_arg" in
+    --force) FORCE=true ;;
+    *) ADAPTERS+=("$_arg") ;;
+  esac
+done
+
 PROJECT_FILE=".context/PROJECT.md"
-SKILLS_DIR=".skills"
 
 # Walk up to find root .context/AGENT.md
 find_root_context() {
@@ -36,19 +50,28 @@ if [ ! -f "$PROJECT_FILE" ]; then
   exit 1
 fi
 
+# Pre-flight: reject unfilled {{...}} placeholders unless --force
+if [ "$FORCE" = false ]; then
+  _placeholders=$(grep -n '{{[^}]*}}' "$PROJECT_FILE" 2>/dev/null || true)
+  if [ -n "$_placeholders" ]; then
+    echo "Error: unfilled placeholders in $PROJECT_FILE:" >&2
+    while IFS= read -r _match; do
+      _lineno="${_match%%:*}"
+      _content="${_match#*:}"
+      _token=$(printf '%s' "$_content" | grep -o '{{[^}]*}}' | head -1)
+      echo "  $PROJECT_FILE:$_lineno: unfilled placeholder $_token" >&2
+    done <<< "$_placeholders"
+    echo "" >&2
+    echo "Fill these placeholders, then re-run: task context:sync" >&2
+    echo "To bypass validation: bash scripts/context-sync.sh --force" >&2
+    exit 1
+  fi
+fi
+
 if [ -n "$ROOT_CONTEXT" ] && [ -f "$ROOT_CONTEXT" ]; then
   echo "  Root context: $ROOT_CONTEXT"
 else
-  # No reachable root AGENT.md — common in CI's clean checkout. The root+project
+  echo "  No root AGENT.md found (project context only)"
-  # adapters (AGENTS.md, system-prompt.txt) require the root context to
-  # regenerate correctly, so we skip them entirely and only regenerate CLAUDE.md
-  # (which is project-only and inherits root via tree walk in Claude Code itself).
-  echo "  No root AGENT.md found — regenerating CLAUDE.md only"
-  echo "Syncing project context from $PROJECT_FILE..."
-  cat "$PROJECT_FILE" > CLAUDE.md
-  echo "  → CLAUDE.md (project-only)"
-  echo "Done."
-  exit 0
 fi
 
 # Emit root context + separator
@@ -95,6 +118,7 @@ generate_system_prompt() {
 
 # ── MCP config ───────────────────────────────────────────────
 generate_mcp() {
+  # Ensure baseline file exists with project-specific knowledge server
   if [ ! -f .context/mcp.json ]; then
     cat > .context/mcp.json << 'JSON'
 {
@@ -106,27 +130,47 @@ generate_mcp() {
   }
 }
 JSON
-    echo "  → .context/mcp.json (new)"
-  else
-    echo "  → .context/mcp.json (exists, skipped)"
   fi
+
+  # Merge root mcp-servers.json if found alongside root AGENT.md
+  local root_mcp=""
+  if [ -n "$ROOT_CONTEXT" ] && [ -f "$ROOT_CONTEXT" ]; then
+    local candidate
+    candidate="$(dirname "$ROOT_CONTEXT")/mcp-servers.json"
+    [ -f "$candidate" ] && root_mcp="$candidate"
+  fi
+
+  if [ -z "$root_mcp" ]; then
+    echo "  → .context/mcp.json (exists, no root mcp-servers.json found)"
+    return
+  fi
+
+  # Root servers take precedence over project entries on key conflict
+  local root_servers count updated
+  root_servers=$(jq '.servers' "$root_mcp")
+  count=$(printf '%s' "$root_servers" | jq 'keys | length')
+  updated=$(jq --argjson root "$root_servers" \
+    '.mcpServers = (.mcpServers + $root)' \
+    .context/mcp.json)
+  printf '%s\n' "$updated" > .context/mcp.json
+  echo "  → .context/mcp.json (merged $count root servers)"
 }
 
 echo "Syncing project context from $PROJECT_FILE..."
 
-if [ $# -eq 0 ]; then
+if [ ${#ADAPTERS[@]} -eq 0 ]; then
   generate_claude
   generate_agents
   generate_system_prompt
   generate_mcp
 else
-  for adapter in "$@"; do
+  for adapter in "${ADAPTERS[@]}"; do
     case "$adapter" in
       claude)  generate_claude ;;
       agents)  generate_agents ;;
       prompt|system|openwebui|owui|generic) generate_system_prompt ;;
       mcp)     generate_mcp ;;
-      *) echo "Unknown adapter: $adapter" ;;
+      *) echo "Unknown adapter: $adapter" >&2; exit 1 ;;
     esac
   done
 fi