From f04b03e07ea55ea561370e414473de41e5aaa13b Mon Sep 17 00:00:00 2001 From: Mathias Date: Mon, 22 Jun 2026 08:25:16 +0200 Subject: [PATCH] chore(context): re-sync derived adapters after root rule-0 update context-sync regenerated the adapters from the updated root AGENT.md (rule 0 pre-task ritual + TDD constraint). The committed adapters had drifted; this is the documented `task check` remedy, not a content change in this repo. Co-Authored-By: Claude Opus 4.8 (1M context) --- .aider.conventions.md | 62 +++++++++++++++++++++++++++++++++----- .context/system-prompt.txt | 62 +++++++++++++++++++++++++++++++++----- .cursorrules | 62 +++++++++++++++++++++++++++++++++----- AGENTS.md | 62 +++++++++++++++++++++++++++++++++----- 4 files changed, 216 insertions(+), 32 deletions(-) diff --git a/.aider.conventions.md b/.aider.conventions.md index f0519f4..29dca29 100644 --- a/.aider.conventions.md +++ b/.aider.conventions.md @@ -27,6 +27,14 @@ and climate/sustainability tech. These rules apply to every task across every project, regardless of harness. +0. **Pre-task ritual — before ANY implementation (non-negotiable).** Run this before writing a single line: + - **Query the brain** (`brain_query`) for the domain + symptom. If the result changes your approach, surface it before acting. 5 seconds beats 5 hours. + - **Load the relevant skill** — see trigger table in *Engineering Skills* below. + - **Write the failing test first.** Name the test before the function. If the target is untestable (e.g. `main()` wiring), extract the logic into a testable function first. No implementation without a red test. + - **State the observable success criterion** — what specific behavior, output, or passing test proves this is done? + + **TDD is non-negotiable.** "Tests pass" is not proof of correctness — only proof the tests ran. Write tests that would catch the bug before writing code that fixes it. + 1. **No assumptions.** Don't hide confusion — surface it. Surface tradeoffs explicitly. Think before coding; if the problem is unclear, ask or state assumptions before acting. 2. **Minimum viable code.** Solve with the smallest change that works. Nothing @@ -49,6 +57,22 @@ These rules apply to every task across every project, regardless of harness. PR flow only 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: + - **Tag + bump SemVer** on the change (annotated tag; minor for a feature or + new/changed ADR, patch for a fix; docs in the same commit). Check the repo's + actual last tag — stated versions in docs drift stale. + - **Push** main and the tag (CI is the gate). + - **Persist generalizable learnings to the brain** (`brain_write`, wing/hall) — + the reusable patterns and the footguns that would bite anyone again, never + project status. See *Knowledge base — when to write* below. + - **File discovered-but-deferred work as tracker issues** on the project's own + repo — token-budget gaps, recorded ADR limitations, v2 follow-ups. Don't let + "out of scope, recorded" rot in a commit message; make it a ticket with a + source pointer. + - Surface the brain entries and issue numbers in the closing summary so the + trail is auditable. + ## Default stack | Layer | Default | Fallback | Last resort | @@ -78,6 +102,26 @@ Exploratory: Rust, Zig — I'll tell you when I want these. - **Security**: no secrets in code, govulncheck before adding deps, SOPS for encrypted config - **Dependencies**: prefer stdlib. testify, slog, templ, sqlc, google.golang.org/adk (agent projects only) are pre-approved; anything else needs justification in the commit message +## Secret handling (every harness, every command) + +Tool output is persisted: terminal → `~/.claude/projects` transcripts → +claudewatcher → brain/wiki → gitea history. A secret printed once is +searchable forever, and clearing it means rotating the key. So: + +1. **Never print, echo, log, or transform a secret to inspect it.** No + `base64`/`xxd`/`cat` of a key, and never pipe a secret through a transform + to defeat `op run`'s output masking (it masks raw values; base64 hides them + from the mask — that exact trick leaked a key on 2026-06-11). +2. **Secrets stay in the subprocess.** Reference them only as env vars consumed + *inside* `op run --env-file ~/.op-env -- `. Never place a literal secret + in a command's argv (it lands in the tool call and the transcript). +3. **Existence check without revealing the value:** `[ -n "$X" ] && echo set` — + never `${X:-...}` (returns the value when set) and never echo a substring of it. +4. **Cross-host secrets:** run the secret-consuming command on the host that has + the secret; do not forward a raw key over ssh argv/stdout. +5. If a secret does leak into output, say so immediately and flag it for rotation — + don't bury it. + ## Infrastructure Three machines on Tailscale: @@ -157,7 +201,7 @@ entries that age well are about *why*, *how to avoid*, and *what to do when*. | **Claude Code, Claude Desktop** | `brain_query` (BM25), `brain_answer` (LLM-synth + sources) MCP tools | `brain_write` MCP tool | | **Crush, Pi, Antigravity, other MCP-capable** | same MCP server: `ingestion-brain` (via the `mcp__*_brain__*` namespace once authenticated) | same | | **Anything HTTP-only (curl, scripts)** | `POST https://brain-mcp.d-ma.be/query` with `{"query":"..."}` (auth via `BRAIN_MCP_TOKEN`) | `POST .../write` with `{"content":"...","filename":"..."}` | -| **Browser / human inspection** | `https://gitea.d-ma.be/mathias/hyperguild` → `knowledge/` and `wiki/` markdown files | +| **Browser / human inspection** | `https://git.d-ma.be/mathias/hyperguild` → `knowledge/` and `wiki/` markdown files | - **Scoping**: defaults to `public` collection; client projects filter to `{client}` + `public`. - **Routing**: brain_answer's LLM uses berget.ai as primary, iguana ollama as @@ -219,15 +263,17 @@ unconditionally on every host, every harness. ## Engineering Skills -Shared engineering skills are available in `~/dev/.skills/`. Load on demand via the index. +Shared engineering skills are available in `~/dev/.skills/`. Load at task start — not "on demand" but on schedule, before writing code. See `~/dev/.skills/SKILLS_INDEX.md` for the full list. -See `~/dev/.skills/SKILLS_INDEX.md` for the full list with descriptions and "use when" triggers. +**Skill trigger table — load before starting, not after getting stuck:** -Key skills: -- **TDD**: always write tests first — load `tdd` skill -- **Code Review**: load `code-review` skill before any review -- **SOLID/Clean Code**: load `solid` or `clean-code` skill for design work -- **Problem first**: load `problem-analysis` skill before coding non-trivial features +| Task type | Load | +|-----------|------| +| Any feature or bug fix | `tdd` | +| Refactor or design | `clean-code` or `solid` | +| Debug | `problem-analysis` | +| Review code or PRs | `code-review` | +| Frame a problem before coding | `problem-analysis` | --- diff --git a/.context/system-prompt.txt b/.context/system-prompt.txt index 3349850..51498e4 100644 --- a/.context/system-prompt.txt +++ b/.context/system-prompt.txt @@ -32,6 +32,14 @@ and climate/sustainability tech. These rules apply to every task across every project, regardless of harness. +0. **Pre-task ritual — before ANY implementation (non-negotiable).** Run this before writing a single line: + - **Query the brain** (`brain_query`) for the domain + symptom. If the result changes your approach, surface it before acting. 5 seconds beats 5 hours. + - **Load the relevant skill** — see trigger table in *Engineering Skills* below. + - **Write the failing test first.** Name the test before the function. If the target is untestable (e.g. `main()` wiring), extract the logic into a testable function first. No implementation without a red test. + - **State the observable success criterion** — what specific behavior, output, or passing test proves this is done? + + **TDD is non-negotiable.** "Tests pass" is not proof of correctness — only proof the tests ran. Write tests that would catch the bug before writing code that fixes it. + 1. **No assumptions.** Don't hide confusion — surface it. Surface tradeoffs explicitly. Think before coding; if the problem is unclear, ask or state assumptions before acting. 2. **Minimum viable code.** Solve with the smallest change that works. Nothing @@ -54,6 +62,22 @@ These rules apply to every task across every project, regardless of harness. PR flow only 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: + - **Tag + bump SemVer** on the change (annotated tag; minor for a feature or + new/changed ADR, patch for a fix; docs in the same commit). Check the repo's + actual last tag — stated versions in docs drift stale. + - **Push** main and the tag (CI is the gate). + - **Persist generalizable learnings to the brain** (`brain_write`, wing/hall) — + the reusable patterns and the footguns that would bite anyone again, never + project status. See *Knowledge base — when to write* below. + - **File discovered-but-deferred work as tracker issues** on the project's own + repo — token-budget gaps, recorded ADR limitations, v2 follow-ups. Don't let + "out of scope, recorded" rot in a commit message; make it a ticket with a + source pointer. + - Surface the brain entries and issue numbers in the closing summary so the + trail is auditable. + ## Default stack | Layer | Default | Fallback | Last resort | @@ -83,6 +107,26 @@ Exploratory: Rust, Zig — I'll tell you when I want these. - **Security**: no secrets in code, govulncheck before adding deps, SOPS for encrypted config - **Dependencies**: prefer stdlib. testify, slog, templ, sqlc, google.golang.org/adk (agent projects only) are pre-approved; anything else needs justification in the commit message +## Secret handling (every harness, every command) + +Tool output is persisted: terminal → `~/.claude/projects` transcripts → +claudewatcher → brain/wiki → gitea history. A secret printed once is +searchable forever, and clearing it means rotating the key. So: + +1. **Never print, echo, log, or transform a secret to inspect it.** No + `base64`/`xxd`/`cat` of a key, and never pipe a secret through a transform + to defeat `op run`'s output masking (it masks raw values; base64 hides them + from the mask — that exact trick leaked a key on 2026-06-11). +2. **Secrets stay in the subprocess.** Reference them only as env vars consumed + *inside* `op run --env-file ~/.op-env -- `. Never place a literal secret + in a command's argv (it lands in the tool call and the transcript). +3. **Existence check without revealing the value:** `[ -n "$X" ] && echo set` — + never `${X:-...}` (returns the value when set) and never echo a substring of it. +4. **Cross-host secrets:** run the secret-consuming command on the host that has + the secret; do not forward a raw key over ssh argv/stdout. +5. If a secret does leak into output, say so immediately and flag it for rotation — + don't bury it. + ## Infrastructure Three machines on Tailscale: @@ -162,7 +206,7 @@ entries that age well are about *why*, *how to avoid*, and *what to do when*. | **Claude Code, Claude Desktop** | `brain_query` (BM25), `brain_answer` (LLM-synth + sources) MCP tools | `brain_write` MCP tool | | **Crush, Pi, Antigravity, other MCP-capable** | same MCP server: `ingestion-brain` (via the `mcp__*_brain__*` namespace once authenticated) | same | | **Anything HTTP-only (curl, scripts)** | `POST https://brain-mcp.d-ma.be/query` with `{"query":"..."}` (auth via `BRAIN_MCP_TOKEN`) | `POST .../write` with `{"content":"...","filename":"..."}` | -| **Browser / human inspection** | `https://gitea.d-ma.be/mathias/hyperguild` → `knowledge/` and `wiki/` markdown files | +| **Browser / human inspection** | `https://git.d-ma.be/mathias/hyperguild` → `knowledge/` and `wiki/` markdown files | - **Scoping**: defaults to `public` collection; client projects filter to `{client}` + `public`. - **Routing**: brain_answer's LLM uses berget.ai as primary, iguana ollama as @@ -224,15 +268,17 @@ unconditionally on every host, every harness. ## Engineering Skills -Shared engineering skills are available in `~/dev/.skills/`. Load on demand via the index. +Shared engineering skills are available in `~/dev/.skills/`. Load at task start — not "on demand" but on schedule, before writing code. See `~/dev/.skills/SKILLS_INDEX.md` for the full list. -See `~/dev/.skills/SKILLS_INDEX.md` for the full list with descriptions and "use when" triggers. +**Skill trigger table — load before starting, not after getting stuck:** -Key skills: -- **TDD**: always write tests first — load `tdd` skill -- **Code Review**: load `code-review` skill before any review -- **SOLID/Clean Code**: load `solid` or `clean-code` skill for design work -- **Problem first**: load `problem-analysis` skill before coding non-trivial features +| Task type | Load | +|-----------|------| +| Any feature or bug fix | `tdd` | +| Refactor or design | `clean-code` or `solid` | +| Debug | `problem-analysis` | +| Review code or PRs | `code-review` | +| Frame a problem before coding | `problem-analysis` | --- diff --git a/.cursorrules b/.cursorrules index ea01e8f..3c3c05b 100644 --- a/.cursorrules +++ b/.cursorrules @@ -30,6 +30,14 @@ and climate/sustainability tech. These rules apply to every task across every project, regardless of harness. +0. **Pre-task ritual — before ANY implementation (non-negotiable).** Run this before writing a single line: + - **Query the brain** (`brain_query`) for the domain + symptom. If the result changes your approach, surface it before acting. 5 seconds beats 5 hours. + - **Load the relevant skill** — see trigger table in *Engineering Skills* below. + - **Write the failing test first.** Name the test before the function. If the target is untestable (e.g. `main()` wiring), extract the logic into a testable function first. No implementation without a red test. + - **State the observable success criterion** — what specific behavior, output, or passing test proves this is done? + + **TDD is non-negotiable.** "Tests pass" is not proof of correctness — only proof the tests ran. Write tests that would catch the bug before writing code that fixes it. + 1. **No assumptions.** Don't hide confusion — surface it. Surface tradeoffs explicitly. Think before coding; if the problem is unclear, ask or state assumptions before acting. 2. **Minimum viable code.** Solve with the smallest change that works. Nothing @@ -52,6 +60,22 @@ These rules apply to every task across every project, regardless of harness. PR flow only 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: + - **Tag + bump SemVer** on the change (annotated tag; minor for a feature or + new/changed ADR, patch for a fix; docs in the same commit). Check the repo's + actual last tag — stated versions in docs drift stale. + - **Push** main and the tag (CI is the gate). + - **Persist generalizable learnings to the brain** (`brain_write`, wing/hall) — + the reusable patterns and the footguns that would bite anyone again, never + project status. See *Knowledge base — when to write* below. + - **File discovered-but-deferred work as tracker issues** on the project's own + repo — token-budget gaps, recorded ADR limitations, v2 follow-ups. Don't let + "out of scope, recorded" rot in a commit message; make it a ticket with a + source pointer. + - Surface the brain entries and issue numbers in the closing summary so the + trail is auditable. + ## Default stack | Layer | Default | Fallback | Last resort | @@ -81,6 +105,26 @@ Exploratory: Rust, Zig — I'll tell you when I want these. - **Security**: no secrets in code, govulncheck before adding deps, SOPS for encrypted config - **Dependencies**: prefer stdlib. testify, slog, templ, sqlc, google.golang.org/adk (agent projects only) are pre-approved; anything else needs justification in the commit message +## Secret handling (every harness, every command) + +Tool output is persisted: terminal → `~/.claude/projects` transcripts → +claudewatcher → brain/wiki → gitea history. A secret printed once is +searchable forever, and clearing it means rotating the key. So: + +1. **Never print, echo, log, or transform a secret to inspect it.** No + `base64`/`xxd`/`cat` of a key, and never pipe a secret through a transform + to defeat `op run`'s output masking (it masks raw values; base64 hides them + from the mask — that exact trick leaked a key on 2026-06-11). +2. **Secrets stay in the subprocess.** Reference them only as env vars consumed + *inside* `op run --env-file ~/.op-env -- `. Never place a literal secret + in a command's argv (it lands in the tool call and the transcript). +3. **Existence check without revealing the value:** `[ -n "$X" ] && echo set` — + never `${X:-...}` (returns the value when set) and never echo a substring of it. +4. **Cross-host secrets:** run the secret-consuming command on the host that has + the secret; do not forward a raw key over ssh argv/stdout. +5. If a secret does leak into output, say so immediately and flag it for rotation — + don't bury it. + ## Infrastructure Three machines on Tailscale: @@ -160,7 +204,7 @@ entries that age well are about *why*, *how to avoid*, and *what to do when*. | **Claude Code, Claude Desktop** | `brain_query` (BM25), `brain_answer` (LLM-synth + sources) MCP tools | `brain_write` MCP tool | | **Crush, Pi, Antigravity, other MCP-capable** | same MCP server: `ingestion-brain` (via the `mcp__*_brain__*` namespace once authenticated) | same | | **Anything HTTP-only (curl, scripts)** | `POST https://brain-mcp.d-ma.be/query` with `{"query":"..."}` (auth via `BRAIN_MCP_TOKEN`) | `POST .../write` with `{"content":"...","filename":"..."}` | -| **Browser / human inspection** | `https://gitea.d-ma.be/mathias/hyperguild` → `knowledge/` and `wiki/` markdown files | +| **Browser / human inspection** | `https://git.d-ma.be/mathias/hyperguild` → `knowledge/` and `wiki/` markdown files | - **Scoping**: defaults to `public` collection; client projects filter to `{client}` + `public`. - **Routing**: brain_answer's LLM uses berget.ai as primary, iguana ollama as @@ -222,15 +266,17 @@ unconditionally on every host, every harness. ## Engineering Skills -Shared engineering skills are available in `~/dev/.skills/`. Load on demand via the index. +Shared engineering skills are available in `~/dev/.skills/`. Load at task start — not "on demand" but on schedule, before writing code. See `~/dev/.skills/SKILLS_INDEX.md` for the full list. -See `~/dev/.skills/SKILLS_INDEX.md` for the full list with descriptions and "use when" triggers. +**Skill trigger table — load before starting, not after getting stuck:** -Key skills: -- **TDD**: always write tests first — load `tdd` skill -- **Code Review**: load `code-review` skill before any review -- **SOLID/Clean Code**: load `solid` or `clean-code` skill for design work -- **Problem first**: load `problem-analysis` skill before coding non-trivial features +| Task type | Load | +|-----------|------| +| Any feature or bug fix | `tdd` | +| Refactor or design | `clean-code` or `solid` | +| Debug | `problem-analysis` | +| Review code or PRs | `code-review` | +| Frame a problem before coding | `problem-analysis` | --- diff --git a/AGENTS.md b/AGENTS.md index f0519f4..29dca29 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -27,6 +27,14 @@ and climate/sustainability tech. These rules apply to every task across every project, regardless of harness. +0. **Pre-task ritual — before ANY implementation (non-negotiable).** Run this before writing a single line: + - **Query the brain** (`brain_query`) for the domain + symptom. If the result changes your approach, surface it before acting. 5 seconds beats 5 hours. + - **Load the relevant skill** — see trigger table in *Engineering Skills* below. + - **Write the failing test first.** Name the test before the function. If the target is untestable (e.g. `main()` wiring), extract the logic into a testable function first. No implementation without a red test. + - **State the observable success criterion** — what specific behavior, output, or passing test proves this is done? + + **TDD is non-negotiable.** "Tests pass" is not proof of correctness — only proof the tests ran. Write tests that would catch the bug before writing code that fixes it. + 1. **No assumptions.** Don't hide confusion — surface it. Surface tradeoffs explicitly. Think before coding; if the problem is unclear, ask or state assumptions before acting. 2. **Minimum viable code.** Solve with the smallest change that works. Nothing @@ -49,6 +57,22 @@ These rules apply to every task across every project, regardless of harness. PR flow only 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: + - **Tag + bump SemVer** on the change (annotated tag; minor for a feature or + new/changed ADR, patch for a fix; docs in the same commit). Check the repo's + actual last tag — stated versions in docs drift stale. + - **Push** main and the tag (CI is the gate). + - **Persist generalizable learnings to the brain** (`brain_write`, wing/hall) — + the reusable patterns and the footguns that would bite anyone again, never + project status. See *Knowledge base — when to write* below. + - **File discovered-but-deferred work as tracker issues** on the project's own + repo — token-budget gaps, recorded ADR limitations, v2 follow-ups. Don't let + "out of scope, recorded" rot in a commit message; make it a ticket with a + source pointer. + - Surface the brain entries and issue numbers in the closing summary so the + trail is auditable. + ## Default stack | Layer | Default | Fallback | Last resort | @@ -78,6 +102,26 @@ Exploratory: Rust, Zig — I'll tell you when I want these. - **Security**: no secrets in code, govulncheck before adding deps, SOPS for encrypted config - **Dependencies**: prefer stdlib. testify, slog, templ, sqlc, google.golang.org/adk (agent projects only) are pre-approved; anything else needs justification in the commit message +## Secret handling (every harness, every command) + +Tool output is persisted: terminal → `~/.claude/projects` transcripts → +claudewatcher → brain/wiki → gitea history. A secret printed once is +searchable forever, and clearing it means rotating the key. So: + +1. **Never print, echo, log, or transform a secret to inspect it.** No + `base64`/`xxd`/`cat` of a key, and never pipe a secret through a transform + to defeat `op run`'s output masking (it masks raw values; base64 hides them + from the mask — that exact trick leaked a key on 2026-06-11). +2. **Secrets stay in the subprocess.** Reference them only as env vars consumed + *inside* `op run --env-file ~/.op-env -- `. Never place a literal secret + in a command's argv (it lands in the tool call and the transcript). +3. **Existence check without revealing the value:** `[ -n "$X" ] && echo set` — + never `${X:-...}` (returns the value when set) and never echo a substring of it. +4. **Cross-host secrets:** run the secret-consuming command on the host that has + the secret; do not forward a raw key over ssh argv/stdout. +5. If a secret does leak into output, say so immediately and flag it for rotation — + don't bury it. + ## Infrastructure Three machines on Tailscale: @@ -157,7 +201,7 @@ entries that age well are about *why*, *how to avoid*, and *what to do when*. | **Claude Code, Claude Desktop** | `brain_query` (BM25), `brain_answer` (LLM-synth + sources) MCP tools | `brain_write` MCP tool | | **Crush, Pi, Antigravity, other MCP-capable** | same MCP server: `ingestion-brain` (via the `mcp__*_brain__*` namespace once authenticated) | same | | **Anything HTTP-only (curl, scripts)** | `POST https://brain-mcp.d-ma.be/query` with `{"query":"..."}` (auth via `BRAIN_MCP_TOKEN`) | `POST .../write` with `{"content":"...","filename":"..."}` | -| **Browser / human inspection** | `https://gitea.d-ma.be/mathias/hyperguild` → `knowledge/` and `wiki/` markdown files | +| **Browser / human inspection** | `https://git.d-ma.be/mathias/hyperguild` → `knowledge/` and `wiki/` markdown files | - **Scoping**: defaults to `public` collection; client projects filter to `{client}` + `public`. - **Routing**: brain_answer's LLM uses berget.ai as primary, iguana ollama as @@ -219,15 +263,17 @@ unconditionally on every host, every harness. ## Engineering Skills -Shared engineering skills are available in `~/dev/.skills/`. Load on demand via the index. +Shared engineering skills are available in `~/dev/.skills/`. Load at task start — not "on demand" but on schedule, before writing code. See `~/dev/.skills/SKILLS_INDEX.md` for the full list. -See `~/dev/.skills/SKILLS_INDEX.md` for the full list with descriptions and "use when" triggers. +**Skill trigger table — load before starting, not after getting stuck:** -Key skills: -- **TDD**: always write tests first — load `tdd` skill -- **Code Review**: load `code-review` skill before any review -- **SOLID/Clean Code**: load `solid` or `clean-code` skill for design work -- **Problem first**: load `problem-analysis` skill before coding non-trivial features +| Task type | Load | +|-----------|------| +| Any feature or bug fix | `tdd` | +| Refactor or design | `clean-code` or `solid` | +| Debug | `problem-analysis` | +| Review code or PRs | `code-review` | +| Frame a problem before coding | `problem-analysis` | ---