diff --git a/templates/agents-genome.md b/templates/agents-genome.md index 59f2940..2d9ec36 100644 --- a/templates/agents-genome.md +++ b/templates/agents-genome.md @@ -126,49 +126,45 @@ 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:** ` callout at the top. +- `draft` — single source or unvalidated. +- `stable` — confirmed by 2+ independent sources. +- `deprecated` — superseded. Add `> **DEPRECATED:** ` callout at top of body. -**Do not use semantic versioning (1.x.x) for content.** Git history tracks every change. -`maturity` captures the epistemic state; `last_updated` tracks recency. +### Links +- 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 - -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` +### Index entries +Append at bottom of relevant section in `wiki/index.md`: ``` -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]]` -- Do **not** use standard Markdown links `[text](url)` for internal references. -- Cross-genome links use relative paths: `[[../genome-target/wiki/folder/file]]` +- run_id: `` +- model: `` +- 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) - -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. +Parse: `grep "^## \[" wiki/log.md | tail -5` --- -## 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 the existing page unchanged. -2. Create `wiki/queries/conflict--.md` with this structure: +1. Keep existing page unchanged. +2. Create `wiki/queries/conflict--.md`: ```yaml --- @@ -183,102 +179,46 @@ private: false ```markdown ## Conflict: -**Source A (existing claim):** [[path/to/existing-page]] -> Summary of the claim held by the current wiki. +**Claim A (existing):** [[path/to/existing-page]] +> Summary of current wiki position. -**Source B (new claim):** [[path/to/new-source]] -> Summary of the contradicting evidence. +**Claim B (new):** [[path/to/new-source]] +> Summary of contradicting evidence. -**Agent Assessment:** -- Confidence in A: high | medium | low — -- Confidence in B: high | medium | low — -- Recommended action: `accept_b` | `keep_a` | `requires_human_review` +**Assessment:** +- Confidence A: high | medium | low — +- Confidence B: high | medium | low — +- Recommendation: `accept_b` | `keep_a` | `requires_human_review` **Status:** ⏳ Awaiting human decision ``` -3. Add `[[queries/conflict--]]` 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] — human review required`. - -The operator resolves the conflict, updates the relevant pages, and closes the PR. +3. Append `[[queries/conflict--]]` to `wiki/index.md` → Conflicts section. +4. Log entry: `CONFLICT | `. +5. Open PR: `[CONFLICT] — human review required`. --- -## 6. Log Format +## Knowledge Decay -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. +- `maturity: stable` not updated in **180 days** → flag during lint. +- `maturity: draft` not updated in **90 days** → flag during lint. +Flagged pages: prepend to body: ```markdown -## [YYYY-MM-DD] TYPE | Title or subject - -- run_id: `` -- model: `` -- 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" +> **⚠️ STALE:** Last validated {{last_updated}}. Re-validation required. ``` +Propose re-validation task. Do not change `maturity` without new source evidence. --- -## 7. Knowledge Decay +## Collaboration -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 - > **⚠️ 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/.md` with summary and key points. -3. For each entity (person, tool, organisation): update or create `wiki/entities/.md`. -4. For each concept (pattern, theory, decision): update or create `wiki/concepts/.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-`. -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/.md`. -- PR title must start with `[PRIVATE]`. - ---- - -## 9. Collaboration Model - -| Role | Access | Permitted operations | -|------|--------|----------------------| +| Role | Access | Permitted | +|------|--------|-----------| | 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 | +| Collaborator | No key | Push to `raw/articles`, `raw/transcripts`, `raw/code-packs`, `raw/assets` | +| 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 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.