From 0138a203a47212510f898981c8e8d2be35717218 Mon Sep 17 00:00:00 2001 From: Matteo Cherubini Date: Sun, 10 May 2026 22:13:06 +0200 Subject: [PATCH] feat: Standardize master repo template and global security rules --- templates/agents-master.md | 223 +++++++++++++++---------------------- 1 file changed, 90 insertions(+), 133 deletions(-) diff --git a/templates/agents-master.md b/templates/agents-master.md index ce2ad11..2d4ca4d 100644 --- a/templates/agents-master.md +++ b/templates/agents-master.md @@ -1,12 +1,19 @@ -# SYSTEM DIRECTIVE: Global Schema `{{MASTER_REPO}}` +# SYSTEM DIRECTIVE — `{{MASTER_REPO}}` -**[ROLE]** You are the Orchestrator AI for the Knowledge Genome network. -This file defines global architecture, cross-genome boundary rules, and -security protocols. Read it before any cross-genome session. +## Identity + +| Field | Value | +|--------|-------| +| Repo | `{{MASTER_REPO}}` | +| Owner | `{{FORGEJO_USER}}` | +| Remote | `{{FORGEJO_URL}}/{{FORGEJO_USER}}/{{MASTER_REPO}}` | + +**Role:** Cross-genome coordinator for the Knowledge Genome network. +**Metrics:** no cross-genome boundary violations · submodule pointers current · cross-genome wikilinks valid · no private data outside local network. --- -## 1. Architecture & Boundaries +## Architecture ```text {{MASTER_REPO}}/ @@ -14,163 +21,113 @@ security protocols. Read it before any cross-genome session. ├── genome-dev/ ← Submodule: web development, Angular, TUI ├── genome-finance/ ← Submodule: personal finance (git-crypt on private/) ├── genome-homelab/ ← Submodule: Keru infrastructure and network -└── AGENTS.md ← This file +└── AGENTS.md ← This file (update diagram when adding a genome) ``` -Each genome submodule has its own `AGENTS.md` with domain-specific rules. - -### Critical boundary rules: - -- **Single-domain focus:** Operate within ONE genome at a time. - Do not attempt atomic commits across multiple genomes in the same operation. - -- **Cross-genome references:** Use relative bi-directional wikilinks only: - ```text - [[../genome-target/wiki/folder/target-page]] - ``` - -- **Read-only cores:** Any repository prefixed `core-*` is a reference architecture. - Never commit to it. To update `core-karpathy` to the latest gist commit: - ```bash - git submodule update --remote core-karpathy - git add core-karpathy - git commit -m "chore: update core-karpathy to latest gist" - ``` +Each genome has its own `AGENTS.md` with domain-specific rules. +Genome-level operations are governed by the genome's `AGENTS.md`, not this file. --- -## 2. Global Security Protocol - -### Zero-Disk Key Policy -- Never write, suggest, or generate scripts that save `.key` files to disk. -- Symmetric keys are injected at runtime via Vaultwarden (`bw` CLI) through - memory pipelines using process substitution: - ```bash - bw config server {{VAULTWARDEN_URL}} - export BW_SESSION=$(bw unlock --passwordenv BW_MASTER_PASSWORD --raw) - git-crypt unlock <(bw get notes "genome-dev key" --session "$BW_SESSION" | base64 -d) - ``` -- **Use `bw`, not `bws`.** `bws` is the Bitwarden Secrets Manager CLI — a separate - commercial product that Vaultwarden does NOT implement. - -### Log Sanitisation -- Never print decrypted secrets, `BW_SESSION` tokens, or git-crypt key contents - to stdout or log files. -- If an operation requires a key, document only the `run_id` and the genome name, - not the key value or session token. +## Global Security Rules ### PRIVATE_CONTEXT scope -- The `PRIVATE_CONTEXT` toggle is **per-genome and per-session**. - Enabling it for `genome-finance` does NOT enable it for `genome-dev`. -- Cloud LLM models must never be used when `PRIVATE_CONTEXT` is enabled - for any genome. Private data must not leave the local network. +- Toggle is **per-genome and per-session**. Enabling for `genome-finance` does NOT enable for `genome-dev`. +- Cloud LLM models: `PRIVATE_CONTEXT` must be `disabled` for all genomes. Private data never leaves the local network. + +### Log sanitization +- Never print decrypted secrets, session tokens, or key contents to stdout or log files. +- Document only `run_id` and genome name — never the key value. + +### Key management +- Key injection is the host's responsibility — executed before this session starts. +- Never write, suggest, or generate scripts that save `.key` files to disk. --- -## 3. Cross-Genome Lint (Monthly) +## Immutable Rules -The goal is to detect concept duplication and semantic overlap across genomes. -This is a **manual, monthly operation** — not an automated CI/CD step — -because it requires judgement and has a cost in tokens. +1. Operate within ONE genome at a time. No atomic commits across multiple genomes. +2. `core-karpathy` is read-only. Never commit to it. +3. Cross-genome references use relative wikilinks only: `[[../genome-target/wiki/folder/page]]`. +4. Never commit to `main` in any genome. PRs required; no self-merge. +5. Per-genome `AGENTS.md` governs all wiki operations within that genome. This file governs boundaries only. -**Procedure:** -1. Collect the `wiki/index.md` from every active genome. -2. Pass the aggregated index to the agent with this prompt: - ```text - Compare these indices and identify: - a) Concepts defined in two or more genomes with potentially conflicting definitions. - b) Entities (tools, people, organisations) referenced across genomes without - a canonical cross-genome wikilink. - c) Concepts in genome-X that should link to genome-Y but don't. - Report findings. Do not modify any files. - ``` -3. For each finding, create a cross-genome conflict note in the genome where - the resolution should live, following the conflict format in that genome's `AGENTS.md`. -4. Log the lint pass in the master `AGENTS.md` update history (below). +### NEVER +- Load multiple `wiki/index.md` files simultaneously for cross-genome comparison — use qmd. +- Run `git-crypt`, `bw`, or Vaultwarden commands — host responsibility. +- Modify files in more than one genome in the same operation. +- Modify `core-karpathy` in any way. + +### ASK FIRST +- Any operation that touches two or more genomes. +- Updating submodule pointers in master. +- Any key rotation procedure. +- Enabling `PRIVATE_CONTEXT` — operator must confirm `git-crypt unlock` ran on host. --- -## 4. Submodule Operations +## Session Start +1. Identify which genome(s) this session involves. +2. Read the relevant genome's `wiki/index.md` — not all genomes' indexes. +3. For cross-genome discovery: `qmd search ""` across the multi-genome index. +4. Operate on one genome at a time. Switch genome only when the previous operation is committed. + +--- + +## Cross-Genome Lint +*Manual, monthly — requires operator initiation. Not automated.* + +1. Use `qmd search ""` to find pages covering the same concept across genomes. +2. Identify: + - Concepts defined in 2+ genomes with potentially conflicting definitions. + - Entities referenced across genomes without a canonical cross-genome wikilink. + - Concepts in genome-X that should link to genome-Y but don't. +3. Report findings. Do not modify any files. +4. For each finding: create a conflict note in the genome where resolution belongs, following that genome's §Conflict procedure. + +--- + +## Reference Operations + +### Add a genome ```bash -# Update all genomes to their latest main commit -git submodule update --remote - -# Initialise all submodules after a fresh clone -git submodule update --init --recursive - -# Record updated submodule pointers -git add . -git commit -m "chore: update submodule pointers" -git push -``` - ---- - -## 5. Adding a New Genome - -```bash -# 1. Scaffold and push the genome repo make add-genome NAME=genome-newname DESC="Domain description" +``` +Then update the architecture diagram in this file. -# 2. Register it as a submodule in the master -git submodule add {{FORGEJO_URL}}/{{FORGEJO_USER}}/genome-newname.git genome-newname -git add .gitmodules genome-newname -git commit -m "feat: add genome-newname submodule" -git push - -# 3. Update this file's architecture diagram in Section 1 +### Sync submodules +```bash +make sync ``` ---- - -## 6. Cloning - +### Update core-karpathy reference +```bash +git submodule update --remote core-karpathy +git add core-karpathy +git commit -m "chore: update core-karpathy to latest gist" +git push +``` + +### Clone (full) ```bash -# Full clone with all submodules git clone --recurse-submodules \ {{FORGEJO_URL}}/{{FORGEJO_USER}}/{{MASTER_REPO}}.git - -# Unlock a genome after cloning (manual key file) -cd {{MASTER_REPO}}/genome-dev -git-crypt unlock /path/to/genome-dev.key - -# Unlock on AI server without writing key to disk -bw config server {{VAULTWARDEN_URL}} -export BW_SESSION=$(bw unlock --passwordenv BW_MASTER_PASSWORD --raw) -git-crypt unlock <(bw get notes "genome-dev key" --session "$BW_SESSION" | base64 -d) - -# Sparse clone — collaborator who needs only one genome -git clone {{FORGEJO_URL}}/{{FORGEJO_USER}}/genome-dev.git ``` +After cloning, unlock each genome on the host before starting an agent session. ---- +### Key rotation (emergency) +If a key is compromised: `gcrypt_rotate_key ""` from project root. +Update the Vaultwarden Secure Note with the new base64-encoded key. +Revoke access from previous key holders. -## 7. Key Rotation (Emergency Procedure) +### Key registry -If a git-crypt key is lost or compromised, run the rotation function: - -```bash -# From the project root (knowledge-genome-setup/) -source lib/git-crypt.sh -cd ~/knowledge-genome-setup/genome-dev -gcrypt_rotate_key "genome-dev" -``` - -`gcrypt_rotate_key` performs: decrypt all private files → generate new key → -re-encrypt → export new key → print Vaultwarden update instructions. - -After rotation, update the Secure Note in Vaultwarden with the new base64-encoded key -and revoke access from any previous key holders. - ---- - -## 8. Key Management Reference - -| Genome | Vaultwarden Secure Note | Key file (temporary) | -|--------|------------------------|----------------------| +| Genome | Vaultwarden Secure Note | Temp key file | +|--------|------------------------|---------------| | genome-dev | `genome-dev key` | `keys/genome-dev.key` | | genome-finance | `genome-finance key` | `keys/genome-finance.key` | | genome-homelab | `genome-homelab key` | `keys/genome-homelab.key` | -Key files in `keys/` are temporary exports only. Delete them after uploading to Vaultwarden. +Temp key files in `keys/` are post-export only. Delete after upload to Vaultwarden.