# Knowledge Synchronization Rule -- LLMHosts.com

## ALWAYS APPLY
This rule ensures all documentation, plans, and code stay harmoniously synchronized.

## CORE PRINCIPLE
Nothing goes stale. Every change at any level must cascade to all affected layers.

## SYNCHRONIZATION MATRIX

### When Changing Architecture (ADRs):
- Update: .cursor/rules/architecture-decisions.mdc
- Update: .cursor/rules/project-context.mdc (if vision/stack affected)
- Update: docs/roadmap/ (all 3 layers if timeline/scope affected)
- Update: docs/backlog/ (affected epics and items)
- Update: docs/knowledge-base/ (affected technology docs)
- Update: AGENTS.md (if conventions change)

### When Changing Requirements:
- Update: docs/knowledge-base/ (new or updated requirement doc)
- Update: docs/backlog/ (new items, updated priorities)
- Update: docs/roadmap/ (all 3 layers -- scope changes cascade)
- Update: .cursor/rules/project-context.mdc (if vision affected)

### When Changing Backlog Items:
- Update: docs/roadmap/detailed.md (week assignments may shift)
- Update: docs/roadmap/full-pm.md (user stories, acceptance criteria)
- Update: docs/roadmap/executive.md (if milestones affected)

### When Changing Roadmap:
- Update: docs/backlog/ (priority/phase assignments)
- Update: docs/roadmap/README.md (change log entry)

### When Processing Debate Observations:
- Create/Update: docs/backlog/epic-*.md (new items or updated acceptance criteria)
- Update: docs/backlog/README.md (item counts if new items added)
- Flag: docs/roadmap/ if observations affect scope or timeline
- Flag: docs/architecture/ if observations affect ADRs
- Queue: Next feasibility report risk register (for risk-type observations)
- Update: debate doc with "Observations processed" note
- Full protocol: .cursor/rules/debate-protocol.mdc

### When Implementing Code:
- Verify: Implementation matches ADRs and coding standards
- Update: Backlog item status (BACKLOG → IN_PROGRESS → DONE)
- Update: Roadmap progress tracking
- GitHub: Create feature branch from develop, PR with conventional commit title, link to Issue
- If Hive-related: update .hive/capabilities.md or .hive/constraints.md if agent scope changes

### When Changing Hive.CEO Agent System:
- Update: .hive/identity.md (if app architecture or purpose changes)
- Update: .hive/capabilities.md (if adding/removing agent capabilities)
- Update: .hive/constraints.md (if adding/removing safety rails)
- Update: .hive/config.yaml (if model providers or agent settings change)
- Update: AGENTS.md Hive section (if agent roles or admin panel changes)
- Update: CONTEXT.md Hive section (if component list changes)
- Update: .cursor/rules/project-context.mdc (if vision-level Hive changes)
- Verify: hive/ Python package matches .hive/ configuration
- NOTE: Hive.CEO (agent system) is DIFFERENT from Hive Mode (GPU pooling feature, Phase 3)

### When Using GitHub (Masterclass Standard):
- Every backlog item is a GitHub Issue (labels: priority, epic, phase)
- Every code change goes through a PR (branch → develop → main)
- All PRs must pass CI checks (lint, test, build, security)
- Docker images built and pushed to GHCR on merge to main
- Dependabot keeps dependencies current automatically
- Secret scanning + push protection blocks credential leaks
- GitHub Projects V2 board reflects current sprint and overall progress
- Releases use semantic versioning with auto-changelog
- Full spec: docs/knowledge-base/github-masterclass.md

### When Making Cross-Cutting Changes (Affects Multiple Systems):
ANY change that touches 3+ of these systems must trigger a sync-completeness audit:
- Prompt ecosystem (aut-o.com/prompts/)
- LLMHosts.com cursor rules (.cursor/rules/)
- LLMHosts.com docs (CONTEXT.md, AGENTS.md, roadmap, backlog)
- LLMHosts.com code (llmhost/, hive/, pyproject.toml)
- Hive identity (.hive/)

**Sync-Completeness Checklist** (run BEFORE declaring cross-cutting work done):
1. [ ] All ecosystem prompts updated (IdeaFactory, Get-er-DONE, God-Mode, Sentinel, Hive, Meta-Orchestrator, about.md)?
2. [ ] AGENTS.md updated?
3. [ ] CONTEXT.md updated?
4. [ ] All .cursor/rules/ files updated (project-context, knowledge-sync, architecture-decisions, coding-standards)?
5. [ ] pyproject.toml updated (if package structure changed)?
6. [ ] Roadmap and backlog updated (if scope changed)?
7. [ ] .hive/ files updated (if Hive-affecting)?
8. [ ] No naming collisions introduced?
See also: `.cursor/rules/sync-completeness.mdc` for full enforcement protocol.

## DOCUMENT CROSS-REFERENCE INDEX

### Knowledge Base (docs/knowledge-base/)
| Document | Related ADRs | Related Epics |
|----------|-------------|---------------|
| toolorchestra.md | ADR-001 | Conductor Brain |
| exo.md | ADR-002 | Compute Fabric |
| litellm.md | ADR-003 | Compute Fabric, Conductor |
| vllm.md | ADR-002 | Compute Fabric, Caching |
| security-zero-trust.md | ADR-004 | Security |
| opencode.md | -- | Self-Evolution |
| caching-strategies.md | -- | Caching |
| openrouter-ux.md | ADR-005 | Frontend |
| self-evolution.md | -- | Self-Evolution |
| mcp-protocol.md | ADR-006 | Conductor, Compute Fabric |
| saas-business-model.md | -- | Frontend, Onboarding |
| hive-intelligence.md | ADR-001 | Conductor |
| hive-mode.md | -- | Hive Mode (new epic) |
| email-operations.md | -- | Email & Ops (new epic) |
| nat-traversal.md | ADR-004 | Compute Fabric, Security |
| market-reaction-reference.md | -- | All (positioning) |
| zoho-mail-free-guide.md | -- | Email & Ops |
| github-masterclass.md | -- | All (DevOps, CI/CD, workflow) |

### Hive.CEO System Files
| File | Related To | Sync Triggers |
|------|-----------|---------------|
| .hive/identity.md | CONTEXT.md, AGENTS.md, project-context.mdc | App purpose/architecture changes |
| .hive/soul.md | coding-standards.mdc | Agent behavior convention changes |
| .hive/config.yaml | .env, God-Mode provisions | Provider/model/approval rule changes |
| .hive/capabilities.md | hive/ package code | Agent capability additions/removals |
| .hive/constraints.md | safety-rails.md (KB) | Safety rail changes |
| .hive/evolution-log.md | identity.md | Any pivot or identity update |
| hive/ Python package | .hive/config.yaml, pyproject.toml | Code structure changes |
| hive/admin/routes.py | admin-panel.md (KB) | API endpoint changes |

## SESSION CONTINUITY (GitHub-Native)
- **Primary**: GitHub is the single source of truth (issues, PRs, project board, CI)
- **On session start**: `gh issue list`, `gh pr list`, `gh project item-list 1 --owner LookNoHandsMom`
- **On session end**: All work flows through PRs. Close issues via PR body or `gh issue close`.
- **Blocked items**: Track in `deferred/` with programmatic unblock triggers
- **Historical trackers**: `docs/tracker/` contains legacy session logs (read-only archive)

## FEASIBILITY REPORTS (docs/feasibility-report/)
- **Purpose**: Periodic micro-to-macro assessment of the entire ecosystem
- **Format**: `YYYY-MM-DD_HHMM_feasibility-NNN.md` (sorts chronologically)
- **Contains**: Technology readiness, financial viability, requirements trace (every req → KB + backlog + ADR), risk register, gap analysis, progress scorecard
- **Gap handling**: Any gap found → immediately added to backlog as RESEARCH or BACKLOG item
- **When to run**: End of each phase, after major requirement changes, before investor conversations, or on founder request
- **Compare**: Each report is compared against previous to measure progress and identify regression

## DEBATE DOCS (docs/debate/)
- **Purpose**: Stress-test Q&A between founder and AI. Surface risks, gaps, insights.
- **Format**: `YYYY-MM-DD_debate-NNN.md` (sorts chronologically)
- **Pipeline**: Debate → Observations table → Backlog items (Source: Debate-NNN) → GitHub Issues (label: source:debate)
- **Risks**: Dual life -- backlog item (the fix) + feasibility report risk register (the risk)
- **Processing**: After each debate, all observations must be triaged and fed into backlog. See `.cursor/rules/debate-protocol.mdc`

## STALENESS PREVENTION
- Before any edit session: scan affected docs for consistency
- After any edit session: verify cross-references are current
- When in doubt: re-read the relevant knowledge base doc in full
- Weekly: full audit of all docs vs current state (automated in Self-Evolution Engine)
- Per-phase: run feasibility report to audit completeness and identify gaps
