Keru/knowledge-genome-orchestrator
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

feat: Standardize master repo template and global security rules

Browse source
This commit is contained in:
Matteo Cherubini 2026-05-10 22:13:06 +02:00
parent cc85df9324
commit 0138a203a4
1 changed files with 90 additions and 133 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

223
templates/agents-master.md
View file

@ -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. ## Identity
This file defines global architecture, cross-genome boundary rules, and
security protocols. Read it before any cross-genome session. | 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 ```text
{{MASTER_REPO}}/ {{MASTER_REPO}}/
@ -14,163 +21,113 @@ security protocols. Read it before any cross-genome session.
├── genome-dev/ ← Submodule: web development, Angular, TUI ├── genome-dev/ ← Submodule: web development, Angular, TUI
├── genome-finance/ ← Submodule: personal finance (git-crypt on private/) ├── genome-finance/ ← Submodule: personal finance (git-crypt on private/)
├── genome-homelab/ ← Submodule: Keru infrastructure and network ├── 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. 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.
### 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"
```
--- ---
## 2. Global Security Protocol ## Global Security Rules
### 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.
### PRIVATE_CONTEXT scope ### PRIVATE_CONTEXT scope
- The `PRIVATE_CONTEXT` toggle is **per-genome and per-session**. - Toggle is **per-genome and per-session**. Enabling for `genome-finance` does NOT enable for `genome-dev`.
Enabling it for `genome-finance` does NOT enable it for `genome-dev`. - Cloud LLM models: `PRIVATE_CONTEXT` must be `disabled` for all genomes. Private data never leaves the local network.
- Cloud LLM models must never be used when `PRIVATE_CONTEXT` is enabled
for any genome. Private data must not leave 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. 1. Operate within ONE genome at a time. No atomic commits across multiple genomes.
This is a **manual, monthly operation** — not an automated CI/CD step — 2. `core-karpathy` is read-only. Never commit to it.
because it requires judgement and has a cost in tokens. 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:** ### NEVER
1. Collect the `wiki/index.md` from every active genome. - Load multiple `wiki/index.md` files simultaneously for cross-genome comparison — use qmd.
2. Pass the aggregated index to the agent with this prompt: - Run `git-crypt`, `bw`, or Vaultwarden commands — host responsibility.
```text - Modify files in more than one genome in the same operation.
Compare these indices and identify: - Modify `core-karpathy` in any way.
a) Concepts defined in two or more genomes with potentially conflicting definitions.
b) Entities (tools, people, organisations) referenced across genomes without ### ASK FIRST
a canonical cross-genome wikilink. - Any operation that touches two or more genomes.
c) Concepts in genome-X that should link to genome-Y but don't. - Updating submodule pointers in master.
Report findings. Do not modify any files. - Any key rotation procedure.
``` - Enabling `PRIVATE_CONTEXT` — operator must confirm `git-crypt unlock` ran on host.
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).
--- ---
## 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 "<concept>"` 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 "<concept>"` 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 ```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" 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 ### Sync submodules
git submodule add {{FORGEJO_URL}}/{{FORGEJO_USER}}/genome-newname.git genome-newname ```bash
git add .gitmodules genome-newname make sync
git commit -m "feat: add genome-newname submodule"
git push
# 3. Update this file's architecture diagram in Section 1
``` ```
--- ### Update core-karpathy reference
```bash
## 6. Cloning 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 ```bash
# Full clone with all submodules
git clone --recurse-submodules \ git clone --recurse-submodules \
{{FORGEJO_URL}}/{{FORGEJO_USER}}/{{MASTER_REPO}}.git {{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 "<genome>"` 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: | Genome | Vaultwarden Secure Note | Temp key file |
|--------|------------------------|---------------|
```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-dev | `genome-dev key` | `keys/genome-dev.key` | | genome-dev | `genome-dev key` | `keys/genome-dev.key` |
| genome-finance | `genome-finance key` | `keys/genome-finance.key` | | genome-finance | `genome-finance key` | `keys/genome-finance.key` |
| genome-homelab | `genome-homelab key` | `keys/genome-homelab.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.