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

refactor: Streamline file conventions and protocol definitions in genome template

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

162
templates/agents-genome.md
View file

@ -126,49 +126,45 @@ private: true | false
--- ---
``` ```
**Field rules:** - `draft` — single source or unvalidated.
- `maturity: draft` — newly created or based on a single source; not yet cross-validated. - `stable` — confirmed by 2+ independent sources.
- `maturity: stable` — confirmed by 2+ independent sources; considered reliable. - `deprecated` — superseded. Add `> **DEPRECATED:** <reason>` callout at top of body.
- `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. ### Links
`maturity` captures the epistemic state; `last_updated` tracks recency. - Internal: `[[folder/file]]` — Obsidian wikilinks only. Never `[text](url)` for internal refs.
- Cross-genome: `[[../genome-target/wiki/folder/file]]`.
- External: `[text](https://...)`.
### 4.2 Atomic Linking ### Index entries
Append at bottom of relevant section in `wiki/index.md`:
When you create a new page, you MUST immediately add its entry to `wiki/index.md`:
```text
- [[folder/slug]] — Brief one-line summary. `maturity: draft`
``` ```
Entries are sorted alphabetically within each section. - [[folder/slug]] — One-line summary. `maturity: draft`
```
Never reorder. Alphabetical sort is handled by the pre-commit hook.
### 4.3 Link Integrity ### Log entries
Append one entry per operation to `wiki/log.md`:
```markdown
## [YYYY-MM-DD] TYPE | Subject
- Use Obsidian-style internal links: `[[folder/file]]` - run_id: `<uuid>`
- Do **not** use standard Markdown links `[text](url)` for internal references. - model: `<model-name>`
- Cross-genome links use relative paths: `[[../genome-target/wiki/folder/file]]` - context_read: `[[path/A]]`, `[[path/B]]`
- output_written: `[[path/C]]`
- reasoning: One sentence — what changed and why.
```
Valid TYPEs: `INGEST` `LINT` `QUERY` `CONFLICT` `CONFIG` `SECURITY`
### 4.4 Lint Checks (Periodic) Parse: `grep "^## \[" wiki/log.md | tail -5`
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 ## Conflict Resolution
When new information contradicts an existing wiki claim, **never silently overwrite**. When new evidence contradicts an existing wiki claim:
### Procedure: 1. Keep existing page unchanged.
1. Keep the existing page unchanged. 2. Create `wiki/queries/conflict-<concept>-<YYYY-MM-DD>.md`:
2. Create `wiki/queries/conflict-<concept>-<YYYY-MM-DD>.md` with this structure:
```yaml ```yaml
--- ---
@ -183,102 +179,46 @@ private: false
```markdown ```markdown
## Conflict: <concept> ## Conflict: <concept>
**Source A (existing claim):** [[path/to/existing-page]] **Claim A (existing):** [[path/to/existing-page]]
> Summary of the claim held by the current wiki. > Summary of current wiki position.
**Source B (new claim):** [[path/to/new-source]] **Claim B (new):** [[path/to/new-source]]
> Summary of the contradicting evidence. > Summary of contradicting evidence.
**Agent Assessment:** **Assessment:**
- Confidence in A: high | medium | low — <reason> - Confidence A: high | medium | low — <reason>
- Confidence in B: high | medium | low — <reason> - Confidence B: high | medium | low — <reason>
- Recommended action: `accept_b` | `keep_a` | `requires_human_review` - Recommendation: `accept_b` | `keep_a` | `requires_human_review`
**Status:** ⏳ Awaiting human decision **Status:** ⏳ Awaiting human decision
``` ```
3. Add `[[queries/conflict-<concept>-<date>]]` to `wiki/index.md` under a 3. Append `[[queries/conflict-<concept>-<date>]]` to `wiki/index.md` → Conflicts section.
`## Conflicts Pending Review` section (create it if absent). 4. Log entry: `CONFLICT | <concept>`.
4. Log the conflict in `wiki/log.md` with type `CONFLICT`. 5. Open PR: `[CONFLICT] <concept> — human review required`.
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 ## Knowledge Decay
Every operation must append exactly ONE entry to `wiki/log.md`. - `maturity: stable` not updated in **180 days** → flag during lint.
The header line is required and must be grep-parseable. - `maturity: draft` not updated in **90 days** → flag during lint.
The metadata block is required for all agent-generated entries.
```markdown Flagged pages: prepend to body:
## [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:**
```bash
grep "^## \[" wiki/log.md | tail -5
```
**Parse by type:**
```bash
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:
```markdown ```markdown
> **⚠️ STALE:** Last validated {{last_updated}}. Re-validation required. > **⚠️ STALE:** Last validated {{last_updated}}. Re-validation required.
``` ```
- The agent proposes a re-validation task (checking whether the claim still holds) Propose re-validation task. Do not change `maturity` without new source evidence.
but does not change `maturity` without new source evidence.
--- ---
## 8. Ingest Workflow ## Collaboration
Triggered by a new file in `raw/` (via Forgejo webhook → n8n → agent session). | Role | Access | Permitted |
|------|--------|-----------|
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 | | Owner | Full — key holder | Read/write everywhere |
| Collaborator | Partial — no key | Push to `raw/articles`, `raw/transcripts`, `raw/code-packs`, `raw/assets` | | Collaborator | No key | Push to `raw/articles`, `raw/transcripts`, `raw/code-packs`, `raw/assets` |
| Local AI agent | Conditional | Reads `private/` only when `PRIVATE_CONTEXT: enabled` | | Local AI agent | Conditional | `private/` only when `PRIVATE_CONTEXT: enabled` |
| Cloud AI model | Public only | `PRIVATE_CONTEXT` must be `disabled`; never send private files outside the local network | | Cloud AI model | Public only | `PRIVATE_CONTEXT` must be `disabled`; never send private files outside local network |
To grant collaborator access: add as Forgejo contributor with Write role. Do not share the git-crypt key. Grant collaborator: add as Forgejo contributor with Write role. Never share the git-crypt key.