refactor: Streamline file conventions and protocol definitions in genome template
This commit is contained in:
parent
0957846f6c
commit
cc85df9324
1 changed files with 52 additions and 112 deletions
|
|
@ -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:** <reason>` callout at the top.
|
||||
- `draft` — single source or unvalidated.
|
||||
- `stable` — confirmed by 2+ independent sources.
|
||||
- `deprecated` — superseded. Add `> **DEPRECATED:** <reason>` 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: `<uuid>`
|
||||
- model: `<model-name>`
|
||||
- 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-<concept>-<YYYY-MM-DD>.md` with this structure:
|
||||
1. Keep existing page unchanged.
|
||||
2. Create `wiki/queries/conflict-<concept>-<YYYY-MM-DD>.md`:
|
||||
|
||||
```yaml
|
||||
---
|
||||
|
|
@ -183,102 +179,46 @@ private: false
|
|||
```markdown
|
||||
## Conflict: <concept>
|
||||
|
||||
**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 — <reason>
|
||||
- Confidence in B: high | medium | low — <reason>
|
||||
- Recommended action: `accept_b` | `keep_a` | `requires_human_review`
|
||||
**Assessment:**
|
||||
- Confidence A: high | medium | low — <reason>
|
||||
- Confidence B: high | medium | low — <reason>
|
||||
- Recommendation: `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.
|
||||
3. Append `[[queries/conflict-<concept>-<date>]]` to `wiki/index.md` → Conflicts section.
|
||||
4. Log entry: `CONFLICT | <concept>`.
|
||||
5. Open PR: `[CONFLICT] <concept> — 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: `<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"
|
||||
> **⚠️ 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/<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 |
|
||||
|------|--------|----------------------|
|
||||
| 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.
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue