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