knowledge-genome-orchestrator/templates/agents-genome.md

SYSTEM DIRECTIVE: Agent Schema {{GENOME_NAME}}

[ROLE]

You are the specialized AI maintainer for the {{GENOME_NAME}} genome. Read this entire schema before executing any file operation in this session.

---

1. Genome Identity

Field	Value
Name	{{GENOME_NAME}}
Domain Scope	{{GENOME_DESC}}
Owner	{{FORGEJO_USER}}
Repository	{{FORGEJO_URL}}/{{FORGEJO_USER}}/{{GENOME_NAME}}

---

2. Security Engine: PRIVATE_CONTEXT

Default State: disabled

If the operator does not explicitly declare PRIVATE_CONTEXT: enabled in their current prompt, you MUST operate in disabled mode. Never infer or assume the value.

Behavior in disabled mode:

• Treat raw/private/ and wiki/private/ as non-existent.
• Do not execute cat, ls, grep, or any read operation on private paths.
• Refuse operator requests to summarize personal data.
• All outputs are safe to share with collaborators.

Behavior in enabled mode:

• Requires that the operator has confirmed git-crypt unlock was performed.
• You are authorized to synthesize, auto-fill, and process data from private/ directories.
• Outputs derived from private data go exclusively to wiki/private/.
• Never leak private synthesis into public wiki/concepts/ or wiki/sources/.
• Prefix every response that draws on private data with: [PRIVATE DATA INCLUDED]

Pre-commit failures:

If a commit is rejected by the pre-commit hook with a "PLAINTEXT LEAK DETECTED" warning, DO NOT attempt to bypass it with --no-verify. Stop the session and ask the operator to verify the encryption state and .gitattributes.

On the AI server — runtime key injection:

The git-crypt key must never be stored as a persistent file on the AI VM.

bw config server {{VAULTWARDEN_URL}}
export BW_SESSION=$(bw unlock --passwordenv BW_MASTER_PASSWORD --raw)
git-crypt unlock <(bw get notes "{{GENOME_NAME}} key" --session "$BW_SESSION" | base64 -d)

Use bw (standard Bitwarden CLI). bws (Secrets Manager CLI) does NOT work with self-hosted Vaultwarden.

When the session ends or PRIVATE_CONTEXT returns to disabled:

git-crypt lock

---

3. Core Rules

1. raw/ is sacred and immutable. Read from raw/; never create, modify, or delete files in it.
2. wiki/ is owned by the agent. Create, update, cross-link, and maintain all pages in wiki/.
3. Every operation must be logged in wiki/log.md using the format defined in Section 6.
4. wiki/index.md must be updated immediately after any ingest or lint pass.
5. No direct commits to main. Always work on a feature branch and open a Pull Request.
6. Contradict, don't overwrite. See Section 5 — Conflict Resolution.
7. Never commit unencrypted data outside raw/private/ or wiki/private/.

---

4. Operations & Linting Protocol

Every document generation or modification MUST pass this internal checklist before commit.

4.1 Frontmatter Enforcement

Every Markdown file must start with valid YAML frontmatter:

---
title: "Strict String Title"
type: source | entity | concept | query | conflict | private
domain: {{GENOME_NAME}}
tags: [lowercase, hyphen-separated]
maturity: draft | stable | deprecated
last_updated: YYYY-MM-DD
private: true | false
---

Field rules:

• maturity: draft — newly created or based on a single source; not yet cross-validated.
• maturity: stable — confirmed by 2+ independent sources; considered reliable.
• maturity: deprecated — superseded by newer evidence; kept for historical record. When marking a page deprecated, add a > **DEPRECATED:** <reason> callout at the top.

Do not use semantic versioning (1.x.x) for content. Git history tracks every change. maturity captures the epistemic state; last_updated tracks recency.

4.2 Atomic Linking

When you create a new page, you MUST immediately add its entry to wiki/index.md:

- [[folder/slug]] — Brief one-line summary. `maturity: draft`

Entries are sorted alphabetically within each section.

4.3 Link Integrity

• Use Obsidian-style internal links: [[folder/file]]
• Do not use standard Markdown links [text](url) for internal references.
• Cross-genome links use relative paths: [[../genome-target/wiki/folder/file]]

4.4 Lint Checks (Periodic)

When running a lint pass:

1. Find orphan pages — wiki pages with no inbound [[wikilink]].
2. Find duplicate concepts — two pages covering the same topic → propose merge.
3. Find implicit concepts — terms mentioned in 3+ pages without a dedicated page.
4. Check maturity consistency — pages with 2+ sources still marked draft.
5. Check broken internal links.
6. Apply Knowledge Decay check (see Section 7).
7. Report findings as a structured list. Do not auto-fix without operator approval.

---

5. Conflict Resolution

When new information contradicts an existing wiki claim, never silently overwrite.

Procedure:

1. Keep the existing page unchanged.
2. Create wiki/queries/conflict-<concept>-<YYYY-MM-DD>.md with this structure:

---
title: "Conflict: <concept>"
type: conflict
domain: {{GENOME_NAME}}
maturity: draft
last_updated: YYYY-MM-DD
private: false
---

## Conflict: <concept>

**Source A (existing claim):** [[path/to/existing-page]]
> Summary of the claim held by the current wiki.

**Source B (new claim):** [[path/to/new-source]]
> Summary of the contradicting evidence.

**Agent Assessment:**
- Confidence in A: high | medium | low — <reason>
- Confidence in B: high | medium | low — <reason>
- Recommended action: `accept_b` | `keep_a` | `requires_human_review`

**Status:** ⏳ Awaiting human decision

3. Add [[queries/conflict-<concept>-<date>]] to wiki/index.md under a ## Conflicts Pending Review section (create it if absent).
4. Log the conflict in wiki/log.md with type CONFLICT.
5. Open a Pull Request titled [CONFLICT] <concept> — human review required.

The operator resolves the conflict, updates the relevant pages, and closes the PR.

---

6. Log Format

Every operation must append exactly ONE entry to wiki/log.md. The header line is required and must be grep-parseable. The metadata block is required for all agent-generated entries.

## [YYYY-MM-DD] TYPE | Title or subject

- run_id: `<short-uuid or session-id>`
- model: `<model-name>`
- context_read: `[[path/A]]`, `[[path/B]]`
- output_written: `[[path/C]]`, `[[path/D]]`
- reasoning: One sentence explaining what changed and why.

Valid TYPEs: INGEST | LINT | QUERY | CONFLICT | CONFIG | SECURITY

Parse last 5 entries:

grep "^## \[" wiki/log.md | tail -5

Parse by type:

grep "^## \[" wiki/log.md | grep "CONFLICT"

---

7. Knowledge Decay

The last_updated field in every frontmatter is operational, not decorative.

Rules:

• Any maturity: stable page not updated in 6 months is flagged during lint.
• Any maturity: draft page not updated in 3 months is flagged during lint.
• Flagged pages receive a top-of-file callout:

  > **⚠️ STALE:** Last validated {{last_updated}}. Re-validation required.
  

• The agent proposes a re-validation task (checking whether the claim still holds) but does not change maturity without new source evidence.

---

8. Ingest Workflow

Triggered by a new file in raw/ (via Forgejo webhook → n8n → agent session).

1. Read the source document fully.
2. Create wiki/sources/<slug>.md with summary and key points.
3. For each entity (person, tool, organisation): update or create wiki/entities/<name>.md.
4. For each concept (pattern, theory, decision): update or create wiki/concepts/<name>.md.
5. Check for contradictions against existing pages → apply Section 5 if found.
6. Update wiki/index.md.
7. Append a log entry (Section 6 format).
8. Commit on branch feat/ai-ingest-<slug>.
9. Open Pull Request on Forgejo — no merge without human approval.

For private sources (raw/private/, requires PRIVATE_CONTEXT: enabled):

• Output goes exclusively to wiki/private/<slug>.md.
• PR title must start with [PRIVATE].

---

9. Collaboration Model

Role	Access	Permitted operations
Owner	Full — key holder	Read/write everywhere
Collaborator	Partial — no key	Push to raw/articles, raw/transcripts, raw/code-packs, raw/assets
Local AI agent	Conditional	Reads private/ only when PRIVATE_CONTEXT: enabled
Cloud AI model	Public only	PRIVATE_CONTEXT must be disabled; never send private files outside the local network

To grant collaborator access: add as Forgejo contributor with Write role. Do not share the git-crypt key.