/integrity - Zero Trust File Integrity Verification

Content-addressable file integrity registry for the CODITECT Zero Trust architecture. Detects unauthorized modifications, tracks changes with cryptographic proof, and maintains an immutable audit trail in org.db.

ADR: ADR-182

Usage

# Verify all files against known-good registry (default)
/integrity

# Full scan — hash all files, update registry, log changes
/integrity --scan

# Show changes since last scan
/integrity --diff

# Show changes since specific date
/integrity --diff --since 2026-02-10

# Export manifest as JSON
/integrity --export

# Show registry statistics
/integrity --stats

# First-time baseline scan
/integrity --baseline

# Force full re-scan (ignore mtime optimization)
/integrity --scan --force-full

# JSON output for programmatic use
/integrity --verify --json

System Prompt

EXECUTION DIRECTIVE: When the user invokes /integrity, you MUST:

1. Execute immediately - No confirmation needed
2. Run the file integrity script with appropriate flags
3. Report results - Show verification status clearly

Default behavior (no arguments): Run --verify (read-only check against registry).

# Default: verify integrity
python3 "$CODITECT_CORE/scripts/file_integrity.py" --verify

# Scan (update registry with current state)
python3 "$CODITECT_CORE/scripts/file_integrity.py" --scan

# Diff (show changes since last scan)
python3 "$CODITECT_CORE/scripts/file_integrity.py" --diff

# Export manifest
python3 "$CODITECT_CORE/scripts/file_integrity.py" --export

# Statistics
python3 "$CODITECT_CORE/scripts/file_integrity.py" --stats

# Baseline (first run)
python3 "$CODITECT_CORE/scripts/file_integrity.py" --baseline

Where $CODITECT_CORE is determined by:

1. submodules/core/coditect-core/ (from repo root)
2. Or: $(git rev-parse --show-toplevel)/.coditect/ (via symlink)

---

Operations

Operation	Flag	Description	Mutates Registry?
Verify	--verify (default)	Compare files against registry, report drift	No (read-only)
Scan	--scan	Hash all files, update registry, log changes	Yes
Diff	--diff	Show audit log entries since last scan	No (read-only)
Export	--export	Export full manifest as JSON	No (read-only)
Stats	--stats	Show type distribution, duplicates, audit summary	No (read-only)
Baseline	--baseline	Initial full scan, marks all files as 'created'	Yes

Options

Option	Description
--verify	Verify files against registry (default)
--scan	Full scan — update registry with current file state
--diff	Show changes from audit log
--export	Export manifest as JSON to /tmp/
--stats	Show registry statistics
--baseline	First-time scan — creates initial registry
--force-full	Skip mtime optimization, re-hash everything
--json	JSON output format
--since DATE	Filter diff to entries after DATE (ISO 8601)
--root PATH	Custom coditect-core root (auto-detected by default)
--db PATH	Custom org.db path (auto-detected by default)
--recorded-by ID	Session identifier for audit trail

Integration with /sync

After every /sync, an integrity scan runs automatically to update the registry with the new file state. This ensures the registry always reflects the latest synced state.

/sync pipeline:
  1. Auto-detect changes
  2. Commit to coditect-core
  3. Push to GitHub
  4. Update parent submodule
  5. Push parent
  6. Sync protected installation
  7. *** Integrity scan *** ← NEW

Integration with /orient

During session orientation, a quick integrity verification runs as Step 0e. This detects any unauthorized modifications since the last session.

/orient pipeline:
  Step 0a: Check for updates
  Step 0b: License validation
  Step 0c: Quick vacuum sweep
  Step 0d: Check operator alerts
  Step 0e: *** Integrity verification *** ← NEW
  Step 1-5: Normal orientation

If verification fails, the orientation displays:

============================================================
  INTEGRITY WARNING: 3 files modified since last scan
    agents/senior-architect.md  [MODIFIED]
    scripts/core-sync.py        [MODIFIED]
    hooks/task_id_validator.py   [TAMPERED]
  Run /integrity --scan to update or /integrity --diff for details
============================================================

Verification Output

File Integrity Verification Report
===================================
Scanned: 5,445 files
Verified: 5,440 (unchanged)
Modified: 3 (legitimate changes)
Tampered: 0
Missing: 2 (deleted)
New: 0 (unregistered)

Modified files:
  agents/senior-architect.md  [MODIFIED] hash changed
  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
  hooks/old-hook.py            [DELETED] was present at last scan

Integrity: PASS (no tampered files)
Audit entries created: 5

Statistics Output

File Integrity Registry Statistics
====================================
Total files:  5,445
By type:
  agent:          776
  command:        377
  skill:          445
  script:         581
  hook:           118
  config:          47
  adr:            182
  track:           14
  standard:        12
  claude-md:       23
  documentation:  870
  other:            0

Audit log:  5,445 entries
  created:    5,445
  modified:       0
  deleted:        0
  verified:       0
  tampered:       0

Duplicate content hashes: 10

Examples

Morning Verification

/integrity
# Runs --verify by default
# Output: "Integrity: PASS — all files match registry"

After Making Changes

# Edit some files, then scan to update registry
/integrity --scan
# Output: "Scanned 5,445 files: 3 modified, 5,442 unchanged"

Check What Changed This Week

/integrity --diff --since 2026-02-07
# Shows all audit log entries since Feb 7

Export for External Audit

/integrity --export
# Creates /tmp/coditect-integrity-manifest-YYYY-MM-DD.json

Database Storage

Stored in org.db (Tier 1 — irreplaceable, per ADR-118):

• file_integrity_registry — Current state: latest known hash for each file
• file_integrity_audit — Immutable append-only log of all state changes

The audit table is never updated or deleted — only appended to. This provides a cryptographic chain of evidence for every file state change.

Related Commands

Command	Purpose
/sync	Sync framework + auto integrity scan
/orient	Session start + auto integrity verify
/cx	Context extraction (uses similar hash patterns)
/backup	Database backup (includes org.db with registry)

Related

• ADR-182: Zero Trust File Integrity Registry
• ADR-118: Database Architecture (org.db = Tier 1)
• ADR-181: Incremental Context Extraction (same stat+hash pattern)
• Track D: Security Hardening
• Track M: Extended Security

Success Output

When verification completes successfully:

Integrity: PASS -- all files match registry

When scan completes:

Scan complete: 5,445 files (0 new, 3 modified, 0 deleted, 5,442 unchanged)
Audit entries created: 3

Completion Checklist

Before marking complete:

• Registry exists in org.db (run --baseline if first time)
• Verification result displayed
• Any warnings surfaced to user
• Audit trail updated (if --scan)

Failure Indicators

This command has FAILED if:

• org.db not found or not writable
• coditect-core root not found
• Python script execution error
• Registry tables don't exist (run --baseline)

When NOT to Use

Do NOT use when:

• First time setup (use --baseline instead of --verify)
• In the middle of active editing (wait until stable state)
• org.db is locked by another process

Anti-Patterns (Avoid)

Anti-Pattern	Problem	Solution
Skip baseline	Verify fails with empty registry	Run --baseline first
Manual hash comparison	Slow and error-prone	Use --verify
Ignore MODIFIED warnings	Drift accumulates	Run --scan after changes
Delete audit entries	Breaks immutable trail	Never modify audit table

Principles

This command embodies:

• #9 Based on Facts - SHA-256 cryptographic proof, not timestamps
• #3 Complete Execution - Scans all files, logs all changes
• Zero Trust - Verify everything, trust nothing

Full Standard: CODITECT-STANDARD-AUTOMATION.md

---

Script: scripts/file_integrity.py Database: org.db (Tier 1 — irreplaceable) ADR: ADR-182 Track: D (Security Hardening) Created: 2026-02-12 Author: Claude (Opus 4.6)