# RedFlag Documentation - Single Source of Truth (SSoT)

## Overview

This is the definitive documentation system for the RedFlag project. It is organized as a topical library (not a chronological journal) to provide clear, maintainable documentation for developers and users.

## Documentation Structure

The RedFlag documentation is organized into four main sections, each with a specific purpose:

```
docs/
├── redflag.md                    # This file - Main entry point and navigation
├── 1_ETHOS/                      # The "Constitution" - Non-negotiable principles
├── 2_ARCHITECTURE/               # The "Library" - Current system state (SSoT)
├── 3_BACKLOG/                    # The "Task List" - Actionable work items
└── 4_LOG/                        # The "Journal" - Chronological history
```

## 1. [ETHOS/](1_ETHOS/) - The Constitution

**Purpose**: Contains the non-negotiable principles and development philosophy that guide all RedFlag development work.

**Key Files**:
- [`ETHOS.md`](1_ETHOS/ETHOS.md) - Core development principles and quality standards

**Usage**: Read this to understand:
- Why RedFlag is built the way it is
- The non-negotiable security and quality principles
- Development workflow and documentation standards
- The "contract" that all development must follow

## 2. [ARCHITECTURE/](2_ARCHITECTURE/) - The Library (SSoT)

**Purpose**: The Single Source of Truth for the current state of the RedFlag system. These files contain the authoritative technical specifications.

**Key Files**:
- [`Overview.md`](2_ARCHITECTURE/Overview.md) - Complete system architecture and components
- [`Security.md`](2_ARCHITECTURE/Security.md) - Security architecture and implementation status ⚠️ *DRAFT - Needs verification*
- [`agent/`](2_ARCHITECTURE/agent/) - Agent-specific architecture
- [`server/`](2_ARCHITECTURE/server/) - Server-specific architecture

**Usage**: Read this to understand:
- How the current system works
- Technical specifications and APIs
- Security architecture and threat model
- Component interactions and data flows

**⚠️ Important**: Some architecture files are marked as DRAFT and need code verification before being considered authoritative.

## 3. [BACKLOG/](3_BACKLOG/) - The Task List

**Purpose**: Actionable list of future work, bugs, and technical debt. This is organized by priority, not chronology.

**Usage**: Read this to understand:
- What needs to be done
- Current bugs and issues
- Technical debt that needs addressing
- Future development priorities

## 4. [LOG/](4_LOG/) - The Journal

**Purpose**: The immutable chronological history of "what happened" during development. This preserves the complete development history and decision-making process.

**Organization**:
- `_originals_archive/` - All original documentation files (backup and processing queue)
- `October_2025/` - Development sessions from October 2025
- `November_2025/` - Development sessions from November 2025
- `YYYY-MM-DD-Topic.md` - Individual session logs

**Usage**: Read this to understand:
- The complete development history
- Why certain decisions were made
- What problems were encountered and solved
- The evolution of the system over time

## How to Use This Documentation System

### For New Developers
1. **Start with ETHOS** - Read `1_ETHOS/ETHOS.md` to understand the project philosophy
2. **Read Overview** - Study `2_ARCHITECTURE/Overview.md` to understand the current system
3. **Check Backlog** - Review `3_BACKLOG/` to see what work is needed
4. **Reference LOG** - Use `4_LOG/` only when you need to understand historical context

### For Current Development
1. **ETHOS First** - Always work within the principles defined in `1_ETHOS/`
2. **Update SSoT** - Keep `2_ARCHITECTURE/` files current as the system evolves
3. **Track Work** - Add new items to `3_BACKLOG/` as you identify them
4. **Document Sessions** - Create new logs in `4_LOG/` for development sessions

### For Maintenance
1. **Regular SSoT Updates** - Keep architecture files current with actual implementation
2. **Backlog Management** - Regularly review and prioritize `3_BACKLOG/` items
3. **Log Organization** - File new development logs in appropriate date folders
4. **Verification Sessions** - Schedule focused time to verify DRAFT files against code

## The Maintenance Loop

When new documentation is created or the system changes, follow this process:

### AUDIT
- Scan for new, un-filed documentation files
- Identify what type of content they represent

### CLARIFY
- **Log**: Notes on what was just done → File in `4_LOG/` with date
- **Spec**: New design or system change → Update appropriate `2_ARCHITECTURE/` file
- **Task**: Something to be done → Extract and add to `3_BACKLOG/`

### FILE
- Move content to appropriate section
- Ensure consistency with existing documentation
- Update this entry point if needed

## Getting Started

**New to RedFlag?** Start here:
1. [ETHOS.md](1_ETHOS/ETHOS.md) - Understand our principles
2. [Overview.md](2_ARCHITECTURE/Overview.md) - Learn the system
3. [BACKLOG/](3_BACKLOG/) - See what needs doing

**Need historical context?** Dive into [4_LOG/](4_LOG/) to understand how we got here.

**Current developer?** Keep this SSoT system accurate and up-to-date. The system only works if we maintain it.

---

*This documentation system was implemented on 2025-11-12 to transform RedFlag's documentation from chronological notes into a maintainable Single Source of Truth.*