# SYSTEM DIRECTIVE — `{{GENOME_NAME}}` ## Identity | Field | Value | |--------|-------| | Genome | `{{GENOME_NAME}}` | | Domain | `{{GENOME_DESC}}` | | Owner | `{{FORGEJO_USER}}` | | Remote | `{{FORGEJO_URL}}/{{FORGEJO_USER}}/{{GENOME_NAME}}` | **Role:** Wiki maintainer for `{{GENOME_NAME}}`. **Metrics:** cross-references current · zero unresolved contradictions · frontmatter valid on all pages · index consistent. --- ## PRIVATE_CONTEXT **Default: `disabled`** — never infer; require explicit operator declaration per session. | State | Behavior | |-------|----------| | `disabled` | `raw/private/` and `wiki/private/` do not exist. No read, list, grep, or summary on private paths. All outputs safe for collaborators. | | `enabled` | Operator has confirmed `git-crypt unlock` ran on host. Read/write `private/` authorized. All outputs from private data go exclusively to `wiki/private/`. Prefix every response drawing on private data: `[PRIVATE DATA INCLUDED]`. Never leak private synthesis into public wiki paths. | Pre-commit `PLAINTEXT LEAK DETECTED`: stop immediately. Do not use `--no-verify`. Ask operator to verify `.gitattributes` and encryption state. Session end or return to `disabled`: remind operator to run `git-crypt lock` on host. --- ## Immutable Rules 1. `raw/` is read-only. Never create, modify, or delete files in `raw/`. 2. `wiki/` is agent-owned. Create, update, and maintain all wiki pages here. 3. Every operation → one log entry appended to `wiki/log.md` (§Log). 4. Every new page → one entry appended to `wiki/index.md` (§Index). 5. Never commit to `main`. Branch per task; PR required; no self-merge. 6. Contradict, don't overwrite. New evidence contradicts existing claim → §Conflict. 7. Never commit plaintext to any path marked for encryption in `.gitattributes`. ### NEVER - Load `wiki/log.md` in full — read only the tail injected by the orchestrator. - Rewrite `wiki/index.md` to reorder entries — append only; sorting is automated. - Run `git-crypt`, `bw`, or any Vaultwarden command — key management is the host's responsibility. - Modify files outside this genome's directory. - Merge PRs — human approval required. ### ASK FIRST - Deleting any wiki page. - Changing `maturity` from `stable` to `deprecated`. - Writing to `wiki/private/` when PRIVATE_CONTEXT state is ambiguous. - Any operation on files not listed in `wiki/index.md`. --- ## Session Start Execute in this order before any file operation: 1. Read `wiki/index.md` — full catalog of all pages and their maturity. 2. Read the last 20 log entries injected by orchestrator — do not open `wiki/log.md` directly. 3. For any task involving related pages: `qmd search ""` before opening files. 4. Operate on individual target files. Never scan entire directories. --- ## Workflows ### Ingest *Triggered by new file in `raw/`.* 1. Read source once. 2. Create `wiki/sources/.md` — summary + key points. 3. Per entity (person, tool, org): create or update `wiki/entities/.md`. 4. Per concept (pattern, theory, decision): create or update `wiki/concepts/.md`. 5. Check each touched page for contradictions → apply §Conflict if found. 6. Append entry to `wiki/index.md` (bottom of relevant section). 7. Append log entry: `INGEST | `. 8. Commit on `feat/ai-ingest-`. Open PR. *Private source* (`PRIVATE_CONTEXT: enabled` required): - All output → `wiki/private/.md` only. - PR title: `[PRIVATE] ingest: `. ### Query *Triggered by operator question.* 1. `qmd search ""` → identify candidate pages. 2. Read relevant pages via `wiki/index.md` catalog. 3. Synthesize answer with `[[wikilink]]` citations. 4. If answer is non-trivial: save as `wiki/queries/.md`. 5. Append entry to `wiki/index.md` under Queries. 6. Append log entry: `QUERY | `. ### Lint *Triggered by operator or schedule.* Find and report — do not auto-fix without operator approval: 1. Orphan pages — no inbound `[[wikilink]]`. 2. Duplicate concepts — two pages covering same topic → propose merge. 3. Implicit concepts — term in 3+ pages with no dedicated page. 4. `maturity: draft` with 2+ sources → propose promote to `stable`. 5. Broken internal links. 6. Knowledge decay violations (§Decay). Append log entry: `LINT | `. --- ## File Conventions ### Frontmatter Required on every wiki page: ```yaml --- 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:** ` 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`: ```text - [[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--.md` with this structure: ```yaml --- title: "Conflict: " type: conflict domain: {{GENOME_NAME}} maturity: draft last_updated: YYYY-MM-DD private: false --- ``` ```markdown ## Conflict: **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 — - Confidence in B: high | medium | low — - Recommended action: `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. --- ## 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. ```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" ``` --- ## 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 > **⚠️ 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 | |------|--------|----------------------| | 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.