feat: Standardize master repo template and global security rules
This commit is contained in:
parent
cc85df9324
commit
0138a203a4
1 changed files with 90 additions and 133 deletions
|
|
@ -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 "<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
|
||||
# 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 "<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:
|
||||
|
||||
```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.
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue