ADR-182: Zero Trust File Integrity Registry

Status

Accepted — 2026-02-12

Context

CODITECT is moving toward a Zero Trust platform architecture where every file, configuration, and component is cryptographically verified. The framework currently has no mechanism to:

1. Detect unauthorized modifications to agents, commands, skills, scripts, or hooks
2. Verify integrity of files across sessions — a tampered agent definition could alter AI behavior
3. Track what changed between sessions with cryptographic proof
4. Deduplicate identical files that exist at different paths
5. Provide an immutable audit trail of all file state changes

With 3,458 components across 37 tracks, manual integrity checking is impractical. The framework needs automated, cryptographic verification.

Threat Model

Threat	Impact	Without Registry
Modified agent definition	AI behavior altered silently	Undetectable
Tampered hook script	Security bypass	Undetectable until exploited
Corrupted skill file	Feature degradation	Manual discovery only
Unauthorized config change	System misconfiguration	No audit trail
Supply chain (submodule)	Injected code via dependency	No verification baseline

Decision

Create a content-addressable file integrity registry stored in org.db (Tier 1 — irreplaceable per ADR-118) with:

1. SHA-256 content hashes of all framework files
2. Immutable append-only audit log of all state changes
3. Verification command to detect drift from known-good state
4. Integration with /sync and /cx pipelines

Database Schema

Two tables in org.db:

-- Current state: latest known hash for each file
CREATE TABLE IF NOT EXISTS file_integrity_registry (
    file_path TEXT PRIMARY KEY,
    file_name TEXT NOT NULL,
    content_hash TEXT NOT NULL,          -- sha256
    file_size INTEGER NOT NULL,
    file_mtime REAL NOT NULL,
    file_type TEXT NOT NULL,             -- agent, command, skill, script, hook, config, adr, track, standard, claude-md
    first_seen_at TEXT NOT NULL,         -- ISO 8601
    last_verified_at TEXT NOT NULL,      -- ISO 8601
    last_changed_at TEXT NOT NULL,       -- ISO 8601
    verified_by TEXT NOT NULL DEFAULT 'system'  -- session ID or 'system'
);

CREATE INDEX IF NOT EXISTS idx_fir_type ON file_integrity_registry(file_type);
CREATE INDEX IF NOT EXISTS idx_fir_hash ON file_integrity_registry(content_hash);
CREATE INDEX IF NOT EXISTS idx_fir_changed ON file_integrity_registry(last_changed_at);

-- Immutable audit log: append-only, never updated or deleted
CREATE TABLE IF NOT EXISTS file_integrity_audit (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    file_path TEXT NOT NULL,
    action TEXT NOT NULL,                -- created, modified, deleted, verified, tampered, restored
    old_hash TEXT,                       -- NULL for 'created'
    new_hash TEXT,                       -- NULL for 'deleted'
    file_size INTEGER,
    recorded_at TEXT NOT NULL,           -- ISO 8601
    recorded_by TEXT NOT NULL,           -- session ID or 'system'
    details TEXT                         -- JSON metadata (reason, context)
);

CREATE INDEX IF NOT EXISTS idx_fia_path ON file_integrity_audit(file_path);
CREATE INDEX IF NOT EXISTS idx_fia_action ON file_integrity_audit(action);
CREATE INDEX IF NOT EXISTS idx_fia_recorded ON file_integrity_audit(recorded_at);

File Scope

All files under coditect-core/ matching these patterns:

Pattern	file_type	Count (approx)
agents/*.md	agent	152
commands/*.md	command	80+
skills/*/SKILL.md	skill	221
scripts/*.py	script	339
hooks/*.py	hook	62
config/*.json	config	15+
internal/architecture/adrs/*.md	adr	182+
internal/project/plans/tracks/TRACK-*.md	track	14
coditect-core-standards/*.md	standard	10+
**/CLAUDE.md	claude-md	20+
docs/**/*.md	documentation	50+

Operations

Operation	Description	When
--scan	Hash all files, update registry, log changes	On demand, /sync
--verify	Compare files against registry, report drift	On demand, session start
--diff	Show changes since last scan	Between sessions
--export	Export manifest as JSON	Backup, audit
--baseline	Initial full scan, marks all as 'created'	First run

Verification Output

File Integrity Verification Report
===================================
Scanned: 1,147 files
Verified: 1,142 (unchanged)
Modified: 3 (legitimate changes)
Tampered: 0
Missing: 2 (deleted)

Modified files:
  agents/senior-architect.md  [MODIFIED] hash changed (expected: last /sync was 2h ago)
  scripts/core-sync.py        [MODIFIED] hash changed
  config/component-counts.json [MODIFIED] hash changed

Missing files:
  agents/deprecated-agent.md   [DELETED] was present at last scan

Audit entries created: 5

Consequences

Positive

• Tamper detection: Any unauthorized modification is immediately visible
• Immutable audit trail: Complete history of every file state change in org.db
• Change detection: Know exactly what changed between sessions (cryptographic, not mtime)
• Deduplication: SHA-256 makes identical files instantly discoverable
• Incremental processing: Hash comparison enables skip-unchanged patterns
• Zero Trust foundation: First building block for platform-wide integrity verification

Negative

• org.db growth: Audit log grows ~100 bytes per change event (negligible)
• Scan time: Full scan of ~1,100 files takes ~2-5 seconds (SHA-256 is fast)
• False positives: Legitimate changes flagged until scan is run (solved by /sync integration)

Neutral

• Reuses compute_file_hash() pattern from J.15.3 project indexer
• Stored in org.db (Tier 1) alongside decisions — appropriate for trust-critical data
• Does not replace git — complements it with runtime verification

Related

• ADR-118: Database Architecture (org.db = Tier 1 irreplaceable)
• ADR-181: Incremental Context Extraction (same stat+hash pattern)
• J.15.3: Project Indexer (content hashing pattern source)
• Track D: Security Hardening
• Track M: Extended Security