Overview
The Work-Wiki system represents a fundamental innovation in how development history is captured and visualized. Unlike traditional Git which captures discrete snapshots (commits), Work-Wiki operates at a micro-level, recording every file save as a “sub-commit” that can later be linked to the actual Git commit. This architecture enables Work-Wiki to serve as an “upper concept” of Git - providing granularity that Git cannot offer while maintaining full integration with the existing Git workflow.Copy
┌───────────────────────────────────────────────────────────────────────────────┐
│ WORK-WIKI AS "UPPER CONCEPT" OF GIT │
├───────────────────────────────────────────────────────────────────────────────┤
│ │
│ Traditional Development View: │
│ ════════════════════════════════════════════════════════════════════════════│
│ │
│ Developer Git Repository │
│ ┌────────┐ ┌──────────────────────────────────────────┐ │
│ │ Human │ ───── │ * c1 ─── * c2 ─── * c3 ─── * c4 ─── * c5│ │
│ │ /AI │ │ Commits only - no intermediate history │ │
│ └────────┘ └──────────────────────────────────────────┘ │
│ │
│ Work-Wiki Enhanced View: │
│ ════════════════════════════════════════════════════════════════════════════│
│ │
│ Developer Work-Wiki Layer Git Repository │
│ ┌────────┐ ┌─────────────────┐ ┌─────────────────────┐ │
│ │ Human │ ───── │ oooooooooooooo │ ── │ * c1 ─── * c2 ─── │ │
│ │ │ │ Every save │ │ │ │
│ └────────┘ │ recorded │ └─────────────────────┘ │
│ ┌────────┐ │ │ │
│ │ AI │ ───── │ <><<<><><><><> │ ── (linked to commits) │
│ │ Claude │ │ AI-attributed │ │
│ └────────┘ └─────────────────┘ │
│ │
│ Key Innovation: │
│ ┌───────────────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ o = Human save <> = AI-assisted save * = Git commit │ │
│ │ │ │
│ │ Work-Wiki records EVERYTHING between commits, then links them. │ │
│ │ This creates a complete development history that Git alone cannot. │ │
│ │ │ │
│ └───────────────────────────────────────────────────────────────────────┘ │
│ │
└───────────────────────────────────────────────────────────────────────────────┘
Contribution to THE CENTER
Copy
┌───────────────────────────────────────────────────────────────────────────────┐
│ HOW WORK-WIKI EXTENSION ENABLES THE HUMAN <> AI FEEDBACK LOOP │
├───────────────────────────────────────────────────────────────────────────────┤
│ │
│ THE CENTER requires: │
│ ════════════════════════════════════════════════════════════════════════════│
│ │
│ 1. VISIBILITY of AI contributions │
│ ├── Work-Wiki tracks AI session and agent name per save │
│ └── AI Attribution Heatmap shows contribution percentage │
│ │
│ 2. TRACEABILITY of changes back to source │
│ ├── Commit linking connects micro-saves to Git commits │
│ └── Sub-commit granularity view expands commit details │
│ │
│ 3. AWARENESS of uncommitted work │
│ ├── Draft Branch visualization shows "work in progress" │
│ └── Ghost nodes represent uncommitted but recorded changes │
│ │
│ 4. COLLABORATION INSIGHT between Human and AI │
│ ├── Parallel Timeline shows Git + Work-Wiki side by side │
│ └── AI session boundaries reveal collaboration patterns │
│ │
│ Result: Complete transparency of the Human <> AI development process │
│ │
└───────────────────────────────────────────────────────────────────────────────┘
Current Implementation
The Work-Wiki system is implemented as a Rust module that records file changes before they are committed to Git. The core tracking functionality exists, but lacks the critical linkage to Git commits and AI attribution.Copy
┌───────────────────────────────────────────────────────────────────────────────┐
│ CURRENT SCHEMA LIMITATIONS │
├───────────────────────────────────────────────────────────────────────────────┤
│ │
│ WHAT'S CAPTURED: │
│ ════════════════════════════════════════════════════════════════════════════│
│ │
│ [OK] When the file was saved (timestamp) │
│ [OK] What file was changed (path) │
│ [OK] What repository it's in │
│ [OK] What HEAD was at save time │
│ [OK] What changed (diff content, additions, deletions) │
│ │
│ WHAT'S MISSING: │
│ ════════════════════════════════════════════════════════════════════════════│
│ │
│ [X] Which commit eventually included this save │
│ [X] Which AI session made this change │
│ [X] Which AI agent (Claude, GPT, etc.) │
│ [X] Type of change (save, commit, revert) │
│ │
│ CONSEQUENCE: │
│ ┌───────────────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ HEAD state tells us the state at save time, but NOT which commit │ │
│ │ eventually incorporated this change. This makes it impossible to: │ │
│ │ │ │
│ │ - Show sub-commit history for a specific commit │ │
│ │ - Calculate AI attribution per commit │ │
│ │ - Visualize uncommitted work as "draft branch" │ │
│ │ │ │
│ └───────────────────────────────────────────────────────────────────────┘ │
│ │
└───────────────────────────────────────────────────────────────────────────────┘
The 3-Layer Integration Architecture
The Work-Wiki extension creates a 3-layer architecture that unifies Git history with micro-level development tracking and AI attribution.Copy
┌───────────────────────────────────────────────────────────────────────────────┐
│ 3-LAYER INTEGRATION ARCHITECTURE │
├───────────────────────────────────────────────────────────────────────────────┤
│ │
│ ╔═════════════════════════════════════════════════════════════════════════╗ │
│ ║ LAYER 3: AI ATTRIBUTION LAYER ║ │
│ ╠═════════════════════════════════════════════════════════════════════════╣ │
│ ║ ║ │
│ ║ AI Sessions Table ║ │
│ ║ - Session identifier (UUID) ║ │
│ ║ - Agent name ("Claude Code", "GPT", etc.) ║ │
│ ║ - Links to PTY session ║ │
│ ║ - Session boundaries (start/end timestamps) ║ │
│ ║ - Total saves, additions, deletions ║ │
│ ║ ║ │
│ ║ Purpose: Track WHEN and WHO (AI) is making changes ║ │
│ ║ ║ │
│ ╚═════════════════════════════════════════════════════════════════════════╝ │
│ │ │
│ V │
│ ╔═════════════════════════════════════════════════════════════════════════╗ │
│ ║ LAYER 2: MICRO-HISTORY LAYER (Work-Wiki Extended) ║ │
│ ╠═════════════════════════════════════════════════════════════════════════╣ │
│ ║ ║ │
│ ║ File Diffs Table (Extended) ║ │
│ ║ ║ │
│ ║ EXISTING: ║ │
│ ║ - Timestamp, file path, repository path ║ │
│ ║ - HEAD hash, diff content, additions, deletions ║ │
│ ║ ║ │
│ ║ NEW COLUMNS: ║ │
│ ║ - committed_hash: Which commit included this save ║ │
│ ║ - parent_hash: Parent commit for linking ║ │
│ ║ - ai_session_id: Links to AI sessions ║ │
│ ║ - agent_name: Quick lookup of AI agent ║ │
│ ║ - change_type: 'save', 'commit', 'revert' ║ │
│ ║ ║ │
│ ║ Commit-Work Mapping Table (New) ║ │
│ ║ - Explicit link between Git commits and Work-Wiki saves ║ │
│ ║ ║ │
│ ║ Purpose: Track EVERY save between commits with AI attribution ║ │
│ ║ ║ │
│ ╚═════════════════════════════════════════════════════════════════════════╝ │
│ │ │
│ V │
│ ╔═════════════════════════════════════════════════════════════════════════╗ │
│ ║ LAYER 1: GIT LAYER (Existing Monolex Git System) ║ │
│ ╠═════════════════════════════════════════════════════════════════════════╣ │
│ ║ ║ │
│ ║ 21 Git modules, 108 commands, comprehensive Git operations ║ │
│ ║ ║ │
│ ║ Key Integration Point: Commit graph visualization ║ │
│ ║ - Base commit graph rendering ║ │
│ ║ - Extended for Work-Wiki overlay ║ │
│ ║ ║ │
│ ╚═════════════════════════════════════════════════════════════════════════╝ │
│ │
└───────────────────────────────────────────────────────────────────────────────┘
Data Flow Architecture
Copy
┌───────────────────────────────────────────────────────────────────────────────┐
│ DATA FLOW: FROM FILE SAVE TO VISUALIZATION │
├───────────────────────────────────────────────────────────────────────────────┤
│ │
│ PHASE 1: FILE SAVE CAPTURE │
│ ════════════════════════════════════════════════════════════════════════════│
│ │
│ User/AI saves file -> File Watcher Daemon -> Work-Wiki Module │
│ │
│ Work-Wiki Module: │
│ 1. Check active AI session │
│ 2. Calculate diff using Git │
│ 3. INSERT INTO file_diffs (with AI session ID if active) │
│ 4. Update AI sessions stats │
│ │
│ PHASE 2: COMMIT LINKING │
│ ════════════════════════════════════════════════════════════════════════════│
│ │
│ User/AI creates Git commit -> Commit Detection -> Work-Wiki Linking │
│ │
│ Linking Process: │
│ 1. Find saves with HEAD matching parent commit │
│ 2. UPDATE file_diffs SET committed_hash │
│ 3. INSERT INTO commit_work_mapping │
│ │
│ PHASE 3: VISUALIZATION QUERY │
│ ════════════════════════════════════════════════════════════════════════════│
│ │
│ Frontend requests graph -> Backend queries: │
│ - Base commit graph (from Git) │
│ - Pre-commit changes per commit │
│ - AI attribution per commit │
│ - Draft branch preview (uncommitted saves) │
│ │
│ Frontend receives extended graph -> Renders with overlays: │
│ - Sub-commit nodes (expandable micro-history) │
│ - AI attribution heatmap (color-coded commits) │
│ - Draft branch (ghost nodes for uncommitted work) │
│ - Parallel timeline (side-by-side view) │
│ │
└───────────────────────────────────────────────────────────────────────────────┘
Schema Extension Design
The schema extension uses SQLite ALTER TABLE for backward-compatible migration that preserves all existing data.Copy
┌───────────────────────────────────────────────────────────────────────────────┐
│ SCHEMA MIGRATION STRATEGY │
├───────────────────────────────────────────────────────────────────────────────┤
│ │
│ PRINCIPLE: Non-destructive, backward-compatible migration │
│ ════════════════════════════════════════════════════════════════════════════│
│ │
│ - No data migration required │
│ - Old records: new fields = NULL │
│ - New records: new fields populated │
│ - Full backward compatibility │
│ │
│ Migration Steps: │
│ │
│ Step 1: Check if migration needed │
│ ════════════════════════════════════════════════════════════════════════════│
│ │
│ PRAGMA table_info(file_diffs) │
│ IF NOT EXISTS column 'committed_hash' THEN RUN migrate_v2() │
│ │
│ Step 2: Add columns to file_diffs │
│ ════════════════════════════════════════════════════════════════════════════│
│ │
│ ALTER TABLE file_diffs ADD COLUMN committed_hash TEXT │
│ ALTER TABLE file_diffs ADD COLUMN parent_hash TEXT │
│ ALTER TABLE file_diffs ADD COLUMN change_type TEXT DEFAULT 'save' │
│ ALTER TABLE file_diffs ADD COLUMN ai_session_id TEXT │
│ ALTER TABLE file_diffs ADD COLUMN agent_name TEXT │
│ │
│ CREATE INDEX idx_diffs_committed ON file_diffs(committed_hash) │
│ CREATE INDEX idx_diffs_ai_session ON file_diffs(ai_session_id) │
│ │
│ Step 3: Create ai_sessions table │
│ ════════════════════════════════════════════════════════════════════════════│
│ │
│ CREATE TABLE IF NOT EXISTS ai_sessions ( │
│ id TEXT PRIMARY KEY, -- UUID │
│ agent_name TEXT NOT NULL, -- "Claude Code", etc. │
│ started_at INTEGER NOT NULL, -- Unix timestamp │
│ ended_at INTEGER, -- NULL if active │
│ terminal_session_id TEXT, -- Links to PTY session │
│ total_saves INTEGER DEFAULT 0, │
│ total_additions INTEGER DEFAULT 0, │
│ total_deletions INTEGER DEFAULT 0 │
│ ) │
│ │
│ CREATE INDEX idx_ai_sessions_terminal ON ai_sessions(terminal_session_id) │
│ CREATE INDEX idx_ai_sessions_agent ON ai_sessions(agent_name) │
│ │
│ Step 4: Create commit_work_mapping table │
│ ════════════════════════════════════════════════════════════════════════════│
│ │
│ CREATE TABLE IF NOT EXISTS commit_work_mapping ( │
│ id INTEGER PRIMARY KEY AUTOINCREMENT, │
│ commit_hash TEXT NOT NULL, -- Git commit hash │
│ diff_id INTEGER NOT NULL, -- FK to file_diffs │
│ linked_at INTEGER NOT NULL, -- When linking occurred │
│ FOREIGN KEY (diff_id) REFERENCES file_diffs(id) │
│ ) │
│ │
│ CREATE INDEX idx_commit_work_hash ON commit_work_mapping(commit_hash) │
│ CREATE INDEX idx_commit_work_diff ON commit_work_mapping(diff_id) │
│ │
└───────────────────────────────────────────────────────────────────────────────┘
Extended Schema Relationships
Copy
┌───────────────────────────────────────────────────────────────────────────────┐
│ EXTENDED SCHEMA ENTITY RELATIONSHIP DIAGRAM │
├───────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌───────────────────┐ │
│ │ ai_sessions │ │
│ ├───────────────────┤ │
│ │ PK id (UUID) │ │
│ │ agent_name │ │
│ │ started_at │ │
│ │ ended_at │ │
│ │ terminal_id │ │
│ │ total_saves │ │
│ └─────────┬─────────┘ │
│ │ │
│ │ 1:N │
│ │ │
│ V │
│ ┌───────────────────────────────────────────────────────────────────────┐ │
│ │ file_diffs (EXTENDED) │ │
│ ├───────────────────────────────────────────────────────────────────────┤ │
│ │ PK id │ EXISTING COLUMNS │ │
│ │ ts │ │ │
│ │ abs_path │ │ │
│ │ rel_path │ │ │
│ │ git_repo_path │ │ │
│ │ head_hash │ ◄── Snapshot at save time │ │
│ │ diff_content │ │ │
│ │ additions │ │ │
│ │ deletions │ │ │
│ ├───────────────────────────────────────────────────────────────────────┤ │
│ │ FK committed_hash │ NEW: Which commit included this save │ │
│ │ parent_hash │ NEW: Parent commit for linking │ │
│ │ change_type │ NEW: 'save', 'commit', 'revert' │ │
│ │ FK ai_session_id │ NEW: FK to ai_sessions │ │
│ │ agent_name │ NEW: Denormalized for fast lookup │ │
│ └───────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ │ 1:N │
│ │ │
│ V │
│ ┌───────────────────┐ │
│ │ commit_work_ │ │
│ │ mapping │ │
│ ├───────────────────┤ │
│ │ PK id │ │
│ │ commit_hash │ ◄── Git commit hash │
│ │ FK diff_id │ ◄── FK to file_diffs │
│ │ linked_at │ ◄── Timestamp │
│ └───────────────────┘ │
│ │
│ Relationships: │
│ ════════════════════════════════════════════════════════════════════════ │
│ │
│ ai_sessions 1 ──── N file_diffs One session, many saves │
│ file_diffs 1 ──── N commit_work_mapping One save, one commit link │
│ Git commit 1 ──── N commit_work_mapping One commit, many saves │
│ │
│ Key Insight: │
│ ┌───────────────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ The committed_hash in file_diffs is the BRIDGE between Work-Wiki │ │
│ │ and Git. When NULL, the save is "draft" (uncommitted). When set, │ │
│ │ it links to the Git commit that incorporated this change. │ │
│ │ │ │
│ └───────────────────────────────────────────────────────────────────────┘ │
│ │
└───────────────────────────────────────────────────────────────────────────────┘
AI Session Detection Architecture
The AI session detection system uses a state machine to track when AI agents are actively making changes.Copy
┌───────────────────────────────────────────────────────────────────────────────┐
│ AI SESSION STATE MACHINE │
├───────────────────────────────────────────────────────────────────────────────┤
│ │
│ States: │
│ ════════════════════════════════════════════════════════════════════════════│
│ │
│ IDLE: No active AI session │
│ All file saves recorded as human (no AI session ID) │
│ │
│ ACTIVE: AI agent is active in terminal │
│ All file saves recorded with current session ID │
│ │
│ Transitions: │
│ ════════════════════════════════════════════════════════════════════════════│
│ │
│ ┌────────────┐ ┌────────────┐ │
│ │ │ AI banner detected │ │ │
│ │ IDLE │ ────────────────────► │ ACTIVE │ │
│ │ │ │ │ │
│ │ session = │ terminal closed │ session = │ │
│ │ None │◄───────────────────── │ UUID │ │
│ │ │ │ │ │
│ └────────────┘ └────────────┘ │
│ ^ │ │
│ │ │ │
│ │ timeout (30 min) │ │
│ └─────────────────────────────────────┘ │
│ │
│ Detection Points: │
│ ════════════════════════════════════════════════════════════════════════════│
│ │
│ 1. Terminal Output Parsing │
│ - Pattern: AI agent banner in terminal │
│ - Extract: agent_name = "Claude Code" │
│ - Action: Start AI session │
│ │
│ 2. Terminal Session Close │
│ - On PTY session closed: End AI session │
│ │
│ 3. Inactivity Timeout │
│ - If no saves for 30 minutes: End AI session │
│ │
└───────────────────────────────────────────────────────────────────────────────┘
System Integration
File Watcher Integration
The Work-Wiki extension integrates with the existing NIIA Watcher daemon that monitors file system changes.Copy
┌───────────────────────────────────────────────────────────────────────────────┐
│ NIIA WATCHER DAEMON INTEGRATION │
├───────────────────────────────────────────────────────────────────────────────┤
│ │
│ Current Flow (rust-niia-watcher): │
│ ════════════════════════════════════════════════════════════════════════════│
│ │
│ File Modified -> NIIA Watcher Daemon -> Work-Wiki record() │
│ │
│ Extended Flow (with AI attribution): │
│ ════════════════════════════════════════════════════════════════════════════│
│ │
│ File Modified -> NIIA Watcher Daemon -> Check Active AI Session │
│ │
│ IF session active: │
│ Record with AI context (session ID, agent name) │
│ ELSE: │
│ Record as human change │
│ │
└───────────────────────────────────────────────────────────────────────────────┘
Git Commit Detection
Copy
┌───────────────────────────────────────────────────────────────────────────────┐
│ GIT COMMIT DETECTION AND LINKING │
├───────────────────────────────────────────────────────────────────────────────┤
│ │
│ Detection Method: HEAD Change Monitoring │
│ ════════════════════════════════════════════════════════════════════════════│
│ │
│ NIIA Watcher monitors .git/HEAD and .git/refs/heads/* │
│ │
│ When HEAD changes: │
│ 1. Read new HEAD hash │
│ 2. Read parent hash from commit object │
│ 3. Link Work-Wiki saves to new commit │
│ │
│ Flow: │
│ ════════════════════════════════════════════════════════════════════════════│
│ │
│ User/AI runs: git commit -m "feat: login" │
│ │ │
│ V │
│ .git/HEAD updated -> NIIA Watcher detects change │
│ │ │
│ V │
│ Read new commit: abc123, parent: def456 │
│ │ │
│ V │
│ Link saves: Find saves WHERE head_hash = def456 AND committed_hash NULL │
│ │ │
│ V │
│ UPDATE file_diffs SET committed_hash = abc123 │
│ INSERT INTO commit_work_mapping │
│ │ │
│ V │
│ Result: 15 Work-Wiki saves linked to commit abc123 │
│ Sub-commit history now available │
│ AI attribution calculated │
│ │
└───────────────────────────────────────────────────────────────────────────────┘
Copy
╔═══════════════════════════════════════════════════════════════╗
║ ║
║ THE CENTER ║
║ ║
║ "Building an environment where Human <> AI feedback ║
║ loop can operate" ║
║ ║
║ Work-Wiki Extension creates the foundation for ║
║ transparent, traceable Human <> AI collaboration ║
║ ║
╚═══════════════════════════════════════════════════════════════╝
Implementation Guide
Continue to Implementation for visualization components and frontend integration