ADR-186: Protected Installation and User Data Separation

Status

ACCEPTED - 2026-01-28

Context

CODITECT framework files need clear separation between:

1. Protected Installation - Binaries, scripts, and default configurations that:

   • Should not be modified by users
   • Are managed by CODITECT setup/update processes
   • Need consistent paths for service definitions (launchd, systemd)

2. User Data - Session data, logs, databases, and custom configurations that:

   • Are generated during usage
   • May need user customization
   • Must persist across framework updates
   • Contain potentially sensitive customer data

Problem

Without clear separation:

• Framework updates may overwrite user customizations
• User data may be lost during reinstallation
• Security boundaries are unclear
• Backup strategies are complicated
• Multi-machine sync is difficult to implement

Decision

Directory Structure

Protected Installation (Framework-Managed)

Platform	Protected Location
macOS	~/Library/Application Support/CODITECT/core/
Linux	~/.local/share/coditect/core/
Windows	%APPDATA%\CODITECT\core\

Contents:

PROTECTED_LOCATION/
├── bin/                    # Compiled binaries
│   ├── codi-watcher        # Context watcher v2.0
│   └── ...
├── scripts/                # Python/Shell scripts
│   ├── unified-message-extractor.py
│   ├── context-query.py
│   └── extractors/         # LLM-specific extractors
├── config/                 # Default configurations
│   ├── llm-watchers.json   # Multi-LLM watcher defaults
│   ├── judge-personas.json
│   └── ...
├── tools/                  # Source code for tools
│   └── context-watcher/    # Rust source
├── agents/                 # Agent definitions
├── skills/                 # Skill definitions
├── commands/               # Command definitions
├── hooks/                  # Event hooks
├── schemas/                # JSON schemas
│   └── llm-watchers-v1.0.0.json
├── internal/               # Internal documentation
└── .venv/                  # Python virtual environment

Access Pattern: Symlinked for convenience

~/.coditect           → PROTECTED_LOCATION (backward compat)
~/PROJECTS/.coditect  → PROTECTED_LOCATION (primary access)
~/PROJECTS/.claude    → .coditect (relative symlink)

User Data (User-Managed)

Platform	User Data Location
macOS/Linux	~/PROJECTS/.coditect-data/
Windows	%USERPROFILE%\PROJECTS\.coditect-data\

Note: User data is in ~/PROJECTS/.coditect-data/ (not ~/.coditect-data/) to keep it alongside project working directories and separate from the protected installation symlink at ~/.coditect.

Contents:

~/PROJECTS/.coditect-data/
├── machine-id.json         # Machine identification
├── context-storage/        # Database tier (ADR-118)
│   ├── platform.db         # Tier 1: Component metadata
│   ├── org.db              # Tier 2: CRITICAL - decisions, learnings
│   ├── sessions.db         # Tier 3: Regenerable - messages, tokens
│   ├── projects.db         # Tier 4: Project embeddings
│   ├── watcher-state.json  # Unified watcher state
│   ├── unified_messages.jsonl
│   ├── exports-pending/    # Pending session exports
│   └── exports-archive/    # Archived exports
├── session-logs/           # Machine-specific session logs
├── logs/                   # Application logs
│   ├── context-watcher.log
│   ├── hooks.log
│   └── ...
├── config/                 # User config overrides (optional)
│   └── llm-watchers.json   # User customizations
├── backups/                # Local backup cache
└── <llm>-sessions-pending/ # Per-LLM export directories
    ├── claude-sessions-pending/
    ├── codex-sessions-pending/
    ├── gemini-sessions-pending/
    └── kimi-sessions-pending/

Configuration Resolution Order

For configuration files (e.g., llm-watchers.json):

1. Environment Variable - CODITECT_WATCHER_CONFIG=/path/to/config.json
2. User Override - ~/PROJECTS/.coditect-data/config/llm-watchers.json
3. Protected Default - PROTECTED_LOCATION/config/llm-watchers.json

This allows users to customize without modifying protected files.

Service Definitions

Services (launchd, systemd) reference the protected location directly:

launchd (macOS):

<key>Program</key>
<string>/Users/USER/Library/Application Support/CODITECT/core/bin/codi-watcher</string>
<key>ProgramArguments</key>
<array>
    <string>/Users/USER/Library/Application Support/CODITECT/core/bin/codi-watcher</string>
    <string>--multi-llm</string>
</array>

systemd (Linux):

[Service]
ExecStart=/home/USER/.local/share/coditect/core/bin/codi-watcher --multi-llm

Backup Implications

Category	Location	Backup Priority	Strategy
Protected Installation	PROTECTED_LOCATION/	Low	Reinstall from git
User Config Overrides	.coditect-data/config/	Medium	Include in backup
org.db (Tier 2)	.coditect-data/context-storage/	CRITICAL	Daily cloud backup
sessions.db (Tier 3)	.coditect-data/context-storage/	Low	Regenerable from exports
Session Logs	.coditect-data/session-logs/	Medium	Include in backup
Exports	.coditect-data/*-sessions-pending/	High	Process before delete

Consequences

Positive

1. Clean Updates - Framework updates don't touch user data
2. Clear Security Boundary - Protected files are read-only to users
3. Simplified Backup - Only back up .coditect-data/
4. Multi-Machine Support - User data can be synced independently
5. Service Stability - Services reference stable protected paths

Negative

1. Path Complexity - Two locations to understand
2. Symlink Dependency - Relies on symlinks for convenience
3. Config Discovery - Must check multiple locations

Neutral

1. Migration Required - Existing installations need migration
2. Documentation - Both locations must be documented

Implementation

Initial Setup (ADR-057)

The CODITECT-CORE-INITIAL-SETUP.py script:

1. Clones/updates to protected location
2. Creates symlinks for convenience
3. Initializes .coditect-data/ structure
4. Copies default configs to protected location

Binary Deployment

When building tools like codi-watcher:

# Build
cd PROTECTED_LOCATION/tools/context-watcher
cargo build --release

# Deploy to protected bin/
cp target/release/codi-watcher PROTECTED_LOCATION/bin/

Config Deployment

Default configs go to protected location:

cp config/llm-watchers.json PROTECTED_LOCATION/config/

User customizations go to user data:

cp my-custom-config.json ~/PROJECTS/.coditect-data/config/llm-watchers.json

Related Decisions

• ADR-057: Initial setup process
• ADR-058: Machine-specific session logs
• ADR-089: Two-database architecture (extended by ADR-118)
• ADR-118: Four-tier database architecture (defines Tier 2 criticality)
• ADR-134: Unified multi-LLM watcher (uses this separation)

---

Decision Date: 2026-01-28 Revisit Date: 2026-07-28