codevoight 0.1.0__tar.gz

codevoight-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bibin Graceson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

codevoight-0.1.0/PKG-INFO

@@ -0,0 +1,191 @@
+Metadata-Version: 2.4
+Name: codevoight
+Version: 0.1.0
+Summary: Voight-Kampff Human Comprehension Gate for AI Coding Agents and Git Commits
+Author: CodeVoight Contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/bibinwithab/codevoight
+Project-URL: Repository, https://github.com/bibinwithab/codevoight
+Project-URL: Issues, https://github.com/bibinwithab/codevoight/issues
+Keywords: mcp,git,ai,commit-gate,voight-kampff,comprehension,cursor,antigravity
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Version Control :: Git
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp>=1.2.0
+Requires-Dist: pydantic>=2.6.0
+Requires-Dist: click>=8.1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+Requires-Dist: build>=1.0.0; extra == "dev"
+Requires-Dist: twine>=5.0.0; extra == "dev"
+Dynamic: license-file
+
+# CodeVoight
+
+> Voight-Kampff Human Comprehension Gate for AI Coding Agents and Git Commits
+
+**CodeVoight** (inspired by the Blade Runner Voight-Kampff interrogation test that distinguishes humans from synthetic AI) guarantees human comprehension before AI coding agents commit code. It intercepts changes into a staged verification buffer and physically blocks Git commits until the developer reviews the diff and passes an interactive comprehension quiz via the terminal.
+
+---
+
+## 1. Why CodeVoight?
+
+Autonomous AI coding agents in modern IDEs (Cursor, Windsurf, Cline, Antigravity) write code directly to disk and create Git commits without verifying whether the human developer understands what changed.
+
+CodeVoight enforces a **strict, fail-closed comprehension gate**:
+1. **Agent Stages Changes**: The AI agent calls CodeVoight's MCP tool `stage_code_change`.
+2. **Deterministic Quiz Generated**: CodeVoight analyzes the staged diff (AST changes, modified functions, error handling, touched files) and generates comprehension questions.
+3. **Out-of-Band Human Verification**: To prevent the AI agent from answering its own quiz, the quiz must be completed by the developer via the terminal (`codevoight quiz`).
+4. **Cryptographic Capability Token**: Upon passing the quiz with 100% score, an HMAC-SHA256 capability token is generated and bound to the exact SHA-256 hash of the staged diff.
+5. **Physical Enforcement**: Git commits are gated both at the MCP tool level (`commit_staged`) and at the Git repository level via a `.git/hooks/pre-commit` hook. If the staged diff changes or lacks an approved token, Git aborts the commit.
+
+---
+
+## 2. Architecture
+
+```mermaid
+flowchart TD
+    subgraph Agent["1. AI Agent (Cursor / Antigravity / Cline)"]
+        A["Calls MCP Tool: stage_code_change()"]
+        AC["Calls MCP Tool: commit_staged()"]
+    end
+
+    subgraph Storage["2. Shared State (.codevoight/state.db - SQLite WAL)"]
+        DB[("Session & Quiz Store\n- Session ID & Diff Hash\n- Status: PENDING / APPROVED\n- HMAC Capability Token")]
+    end
+
+    subgraph Human["3. Human Developer (Terminal CLI)"]
+        H["Runs: codevoight quiz [session_id]"]
+        Q["Reviews Diff & Answers Quiz"]
+        T["100% Score: Generates Capability Token"]
+    end
+
+    subgraph Gate["4. Dual Enforcement Gate"]
+        P1["Path A: MCP commit_staged()"]
+        P2["Path B: Git Hook (.git/hooks/pre-commit)"]
+        GIT[("Git Repository Commit")]
+    end
+
+    A -->|"1. Writes staged diff & quiz"| DB
+    DB -->|"2. Fetches questions"| H
+    H --> Q --> T
+    T -->|"3. Stores APPROVED token"| DB
+
+    AC -->|"Verify session token"| P1
+    DB -.->|"Validate token"| P1
+    P1 -->|"Pass"| GIT
+
+    H -.->|"Direct git commit"| P2
+    DB -.->|"Validate diff hash"| P2
+    P2 -->|"Pass"| GIT
+```
+
+---
+
+## 3. Installation & Setup
+
+### Prerequisites
+* Python 3.10+
+* Git 2.20+
+
+### Install CodeVoight
+```powershell
+# Clone or navigate to the repository
+cd C:\Users\jbibingraceson\projects\codegate
+
+# Create virtual environment and install in editable mode
+python -m venv .venv
+.\.venv\Scripts\pip.exe install -e .[dev]
+```
+
+### Install Git Pre-Commit Hook
+In your project repository, install the physical commit verification hook:
+```powershell
+.\.venv\Scripts\codevoight.exe hook install
+```
+This writes `.git/hooks/pre-commit`, ensuring that any `git commit` requires a valid quiz approval token.
+
+---
+
+## 4. IDE MCP Configuration
+
+### Cursor
+Add to `.cursor/mcp.json` or your Cursor user settings:
+```json
+{
+  "mcpServers": {
+    "codevoight": {
+      "command": "python",
+      "args": ["-m", "codevoight.server"]
+    }
+  }
+}
+```
+
+### VS Code (Cline / Roo Code)
+Add to your Cline MCP settings:
+```json
+{
+  "mcpServers": {
+    "codevoight": {
+      "command": "python",
+      "args": ["-m", "codevoight.server"],
+      "disabled": false,
+      "autoApprove": []
+    }
+  }
+}
+```
+
+### Google Antigravity
+Add to your Antigravity MCP settings:
+```json
+{
+  "mcpServers": {
+    "codevoight": {
+      "command": "python",
+      "args": ["-m", "codevoight.server"]
+    }
+  }
+}
+```
+
+---
+
+## 5. CLI Commands
+
+| Command | Description |
+| :--- | :--- |
+| `codevoight quiz [session_id]` | Interactive terminal quiz to review diff and unlock commit |
+| `codevoight status` | View active and pending staging sessions |
+| `codevoight stage <files...>` | Manually stage files and generate a comprehension quiz |
+| `codevoight hook install` | Install the `.git/hooks/pre-commit` verification gate |
+| `codevoight hook verify` | Test current staged Git changes against CodeVoight state |
+
+---
+
+## 6. Verification & Test Suite
+
+Run the full automated test suite:
+```powershell
+.\.venv\Scripts\pytest.exe -v
+```
+
+The test suite covers:
+* HMAC capability token generation, tampering detection, and TTL expiry.
+* Cross-platform diff normalization and SHA-256 hash consistency.
+* SQLite WAL concurrency and transaction rollback.
+* Deterministic AST diff question generation and grading.
+* End-to-end Git pre-commit hook enforcement.
+* MCP stdio tool execution, blocking unapproved commits and passing approved commits.

codevoight-0.1.0/README.md

@@ -0,0 +1,158 @@
+# CodeVoight
+
+> Voight-Kampff Human Comprehension Gate for AI Coding Agents and Git Commits
+
+**CodeVoight** (inspired by the Blade Runner Voight-Kampff interrogation test that distinguishes humans from synthetic AI) guarantees human comprehension before AI coding agents commit code. It intercepts changes into a staged verification buffer and physically blocks Git commits until the developer reviews the diff and passes an interactive comprehension quiz via the terminal.
+
+---
+
+## 1. Why CodeVoight?
+
+Autonomous AI coding agents in modern IDEs (Cursor, Windsurf, Cline, Antigravity) write code directly to disk and create Git commits without verifying whether the human developer understands what changed.
+
+CodeVoight enforces a **strict, fail-closed comprehension gate**:
+1. **Agent Stages Changes**: The AI agent calls CodeVoight's MCP tool `stage_code_change`.
+2. **Deterministic Quiz Generated**: CodeVoight analyzes the staged diff (AST changes, modified functions, error handling, touched files) and generates comprehension questions.
+3. **Out-of-Band Human Verification**: To prevent the AI agent from answering its own quiz, the quiz must be completed by the developer via the terminal (`codevoight quiz`).
+4. **Cryptographic Capability Token**: Upon passing the quiz with 100% score, an HMAC-SHA256 capability token is generated and bound to the exact SHA-256 hash of the staged diff.
+5. **Physical Enforcement**: Git commits are gated both at the MCP tool level (`commit_staged`) and at the Git repository level via a `.git/hooks/pre-commit` hook. If the staged diff changes or lacks an approved token, Git aborts the commit.
+
+---
+
+## 2. Architecture
+
+```mermaid
+flowchart TD
+    subgraph Agent["1. AI Agent (Cursor / Antigravity / Cline)"]
+        A["Calls MCP Tool: stage_code_change()"]
+        AC["Calls MCP Tool: commit_staged()"]
+    end
+
+    subgraph Storage["2. Shared State (.codevoight/state.db - SQLite WAL)"]
+        DB[("Session & Quiz Store\n- Session ID & Diff Hash\n- Status: PENDING / APPROVED\n- HMAC Capability Token")]
+    end
+
+    subgraph Human["3. Human Developer (Terminal CLI)"]
+        H["Runs: codevoight quiz [session_id]"]
+        Q["Reviews Diff & Answers Quiz"]
+        T["100% Score: Generates Capability Token"]
+    end
+
+    subgraph Gate["4. Dual Enforcement Gate"]
+        P1["Path A: MCP commit_staged()"]
+        P2["Path B: Git Hook (.git/hooks/pre-commit)"]
+        GIT[("Git Repository Commit")]
+    end
+
+    A -->|"1. Writes staged diff & quiz"| DB
+    DB -->|"2. Fetches questions"| H
+    H --> Q --> T
+    T -->|"3. Stores APPROVED token"| DB
+
+    AC -->|"Verify session token"| P1
+    DB -.->|"Validate token"| P1
+    P1 -->|"Pass"| GIT
+
+    H -.->|"Direct git commit"| P2
+    DB -.->|"Validate diff hash"| P2
+    P2 -->|"Pass"| GIT
+```
+
+---
+
+## 3. Installation & Setup
+
+### Prerequisites
+* Python 3.10+
+* Git 2.20+
+
+### Install CodeVoight
+```powershell
+# Clone or navigate to the repository
+cd C:\Users\jbibingraceson\projects\codegate
+
+# Create virtual environment and install in editable mode
+python -m venv .venv
+.\.venv\Scripts\pip.exe install -e .[dev]
+```
+
+### Install Git Pre-Commit Hook
+In your project repository, install the physical commit verification hook:
+```powershell
+.\.venv\Scripts\codevoight.exe hook install
+```
+This writes `.git/hooks/pre-commit`, ensuring that any `git commit` requires a valid quiz approval token.
+
+---
+
+## 4. IDE MCP Configuration
+
+### Cursor
+Add to `.cursor/mcp.json` or your Cursor user settings:
+```json
+{
+  "mcpServers": {
+    "codevoight": {
+      "command": "python",
+      "args": ["-m", "codevoight.server"]
+    }
+  }
+}
+```
+
+### VS Code (Cline / Roo Code)
+Add to your Cline MCP settings:
+```json
+{
+  "mcpServers": {
+    "codevoight": {
+      "command": "python",
+      "args": ["-m", "codevoight.server"],
+      "disabled": false,
+      "autoApprove": []
+    }
+  }
+}
+```
+
+### Google Antigravity
+Add to your Antigravity MCP settings:
+```json
+{
+  "mcpServers": {
+    "codevoight": {
+      "command": "python",
+      "args": ["-m", "codevoight.server"]
+    }
+  }
+}
+```
+
+---
+
+## 5. CLI Commands
+
+| Command | Description |
+| :--- | :--- |
+| `codevoight quiz [session_id]` | Interactive terminal quiz to review diff and unlock commit |
+| `codevoight status` | View active and pending staging sessions |
+| `codevoight stage <files...>` | Manually stage files and generate a comprehension quiz |
+| `codevoight hook install` | Install the `.git/hooks/pre-commit` verification gate |
+| `codevoight hook verify` | Test current staged Git changes against CodeVoight state |
+
+---
+
+## 6. Verification & Test Suite
+
+Run the full automated test suite:
+```powershell
+.\.venv\Scripts\pytest.exe -v
+```
+
+The test suite covers:
+* HMAC capability token generation, tampering detection, and TTL expiry.
+* Cross-platform diff normalization and SHA-256 hash consistency.
+* SQLite WAL concurrency and transaction rollback.
+* Deterministic AST diff question generation and grading.
+* End-to-end Git pre-commit hook enforcement.
+* MCP stdio tool execution, blocking unapproved commits and passing approved commits.

codevoight-0.1.0/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "codevoight"
+version = "0.1.0"
+description = "Voight-Kampff Human Comprehension Gate for AI Coding Agents and Git Commits"
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [
+    { name = "CodeVoight Contributors" }
+]
+license = "MIT"
+keywords = ["mcp", "git", "ai", "commit-gate", "voight-kampff", "comprehension", "cursor", "antigravity"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Version Control :: Git",
+    "Topic :: Security",
+]
+dependencies = [
+    "mcp>=1.2.0",
+    "pydantic>=2.6.0",
+    "click>=8.1.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/bibinwithab/codevoight"
+Repository = "https://github.com/bibinwithab/codevoight"
+Issues = "https://github.com/bibinwithab/codevoight/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.23.0",
+    "build>=1.0.0",
+    "twine>=5.0.0",
+]
+
+[project.scripts]
+codevoight = "codevoight.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+asyncio_mode = "auto"

codevoight-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

codevoight-0.1.0/src/codevoight/__init__.py

@@ -0,0 +1,8 @@
+"""CodeVoight - Voight-Kampff Human Comprehension Gate for AI Commits."""
+
+from codevoight.core.config import load_dotenv
+
+__version__ = "0.1.0"
+
+# Auto-load .env if present in workspace root
+load_dotenv()

codevoight-0.1.0/src/codevoight/cli.py

@@ -0,0 +1,219 @@
+from __future__ import annotations
+
+import sys
+import time
+from pathlib import Path
+from typing import Optional
+
+import click
+
+from codevoight.core.diff import compute_diff_hash, normalize_text
+from codevoight.core.models import (
+    QuizSubmission,
+    SessionStatus,
+    StagedSession,
+)
+from codevoight.core.security import get_or_create_secret, sign_token
+from codevoight.db.repository import StateRepository
+from codevoight.generators.deterministic import (
+    DeterministicQuizEvaluator,
+    DeterministicQuizGenerator,
+)
+from codevoight.git.hook import install_pre_commit_hook, verify_staged_commit
+from codevoight.git.runner import GitRunner
+
+
+def get_repo_and_db_paths() -> tuple[Path, Path]:
+    runner = GitRunner()
+    root = (runner.get_repo_root() or Path.cwd()).resolve()
+    codevoight_dir = root / ".codevoight"
+    if not codevoight_dir.exists():
+        if (root / ".quizgate").exists():
+            codevoight_dir = root / ".quizgate"
+        elif (root / ".codegate").exists():
+            codevoight_dir = root / ".codegate"
+    db_path = codevoight_dir / "state.db"
+    return codevoight_dir, db_path
+
+
+@click.group()
+def main() -> None:
+    """CodeVoight: Voight-Kampff Comprehension Gate for AI Commits."""
+    pass
+
+
+@main.command("quiz")
+@click.argument("session_id", required=False)
+def run_quiz(session_id: Optional[str] = None) -> None:
+    """Take comprehension quiz for a staged change to unlock git commit."""
+    codevoight_dir, db_path = get_repo_and_db_paths()
+    repo = StateRepository(db_path)
+
+    session = None
+    if session_id:
+        session = repo.get_session(session_id)
+        if not session:
+            click.echo(f"[ERROR] Session '{session_id}' not found.", err=True)
+            sys.exit(1)
+    else:
+        session = repo.get_latest_pending_session()
+        if not session:
+            click.echo("[INFO] No pending quiz sessions found.", err=True)
+            click.echo("Stage code changes via MCP or 'codevoight stage' first.")
+            sys.exit(0)
+
+    click.echo("=" * 60)
+    click.echo(f"CODEVOIGHT COMPREHENSION QUIZ")
+    click.echo(f"Session ID : {session.session_id}")
+    click.echo(f"Diff Hash  : {session.diff_hash[:16]}...")
+    if session.description:
+        click.echo(f"Description: {session.description}")
+    click.echo("=" * 60)
+
+    # Show Diff Summary
+    click.echo("\n--- STAGED DIFF PREVIEW ---")
+    diff_lines = session.diff_text.strip().splitlines()
+    for line in diff_lines[:30]:
+        click.echo(line)
+    if len(diff_lines) > 30:
+        click.echo(f"... ({len(diff_lines) - 30} more lines omitted) ...")
+    click.echo("---------------------------\n")
+
+    questions = repo.get_questions_for_session(session.session_id)
+    if not questions:
+        click.echo("[WARNING] No questions found for this session. Generating on the fly...")
+        gen = DeterministicQuizGenerator()
+        questions = gen.generate_quiz(session.diff_text, session.description)
+
+    answers = {}
+    for idx, q in enumerate(questions, 1):
+        click.echo(f"\n[Question {idx}/{len(questions)}] {q.prompt}")
+        for opt in q.options:
+            click.echo(f"  [{opt.id}] {opt.text}")
+
+        valid_ids = [opt.id.upper() for opt in q.options]
+        chosen = ""
+        while chosen not in valid_ids:
+            chosen = click.prompt("Your answer", type=str).strip().upper()
+        answers[q.id] = chosen
+
+    # Evaluate
+    submission = QuizSubmission(session_id=session.session_id, answers=answers)
+    evaluator = DeterministicQuizEvaluator(passing_score=1.0)
+    result = evaluator.evaluate(submission, questions)
+
+    click.echo("\n" + "=" * 60)
+    if result.passed:
+        secret_key = get_or_create_secret(codevoight_dir)
+        token = sign_token(session.session_id, session.diff_hash, secret_key)
+        repo.update_session_status(session.session_id, SessionStatus.APPROVED, token.serialize())
+
+        click.echo(f"[PASSED] Score: {int(result.score * 100)}% ({result.correct}/{result.total})")
+        click.echo(f"[UNLOCKED] Capability token generated for diff hash {session.diff_hash[:16]}.")
+        click.echo("You may now proceed with 'git commit' or call the MCP commit tool.")
+    else:
+        repo.update_session_status(session.session_id, SessionStatus.REJECTED)
+        click.echo(f"[FAILED] Score: {int(result.score * 100)}% ({result.correct}/{result.total})")
+        click.echo("[LOCKED] Commit permission DENIED. Review the following feedback:")
+        for fb in result.feedback:
+            click.echo(f"  * {fb}")
+        click.echo("\nReview the diff and run 'codevoight quiz' to try again.")
+        sys.exit(1)
+    click.echo("=" * 60)
+
+
+@main.command("status")
+def show_status() -> None:
+    """View active and recent CodeVoight staging sessions."""
+    _, db_path = get_repo_and_db_paths()
+    if not db_path.exists():
+        click.echo("[INFO] No CodeVoight database found in current repository.")
+        return
+
+    repo = StateRepository(db_path)
+    sessions = repo.list_sessions(limit=10)
+    if not sessions:
+        click.echo("[INFO] No staging sessions found.")
+        return
+
+    click.echo(f"{'SESSION ID':<12} {'STATUS':<15} {'EXPIRES IN':<12} {'DIFF HASH':<16} {'DESCRIPTION'}")
+    click.echo("-" * 75)
+    now = time.time()
+    for s in sessions:
+        remaining = max(0, int(s.expires_at - now))
+        rem_str = f"{remaining}s" if remaining > 0 else "EXPIRED"
+        click.echo(f"{s.session_id[:10]:<12} {s.status.value:<15} {rem_str:<12} {s.diff_hash[:14]:<16} {s.description[:20]}")
+
+
+@main.command("hook")
+@click.argument("action", type=click.Choice(["install", "verify"]))
+def manage_hook(action: str) -> None:
+    """Install or test the Git pre-commit verification hook."""
+    if action == "install":
+        success, msg = install_pre_commit_hook()
+        if success:
+            click.echo(f"[SUCCESS] CodeVoight pre-commit hook installed to: {msg}")
+        else:
+            click.echo(f"[ERROR] Failed to install hook: {msg}", err=True)
+            sys.exit(1)
+    elif action == "verify":
+        success, msg = verify_staged_commit()
+        if success:
+            click.echo(f"[SUCCESS] {msg}")
+        else:
+            click.echo(f"[DENIED] {msg}", err=True)
+            sys.exit(1)
+
+
+@main.command("verify-commit", hidden=True)
+def run_verify_commit() -> None:
+    """Internal entrypoint invoked directly by .git/hooks/pre-commit."""
+    success, msg = verify_staged_commit()
+    if not success:
+        click.echo(f"[CODEVOIGHT] {msg}", err=True)
+        sys.exit(1)
+    sys.exit(0)
+
+
+@main.command("stage")
+@click.argument("files", nargs=-1, required=True)
+@click.option("--description", "-m", default="Manual CLI staging", help="Description of staged change")
+def stage_from_cli(files: tuple[str, ...], description: str) -> None:
+    """Stage files and create a comprehension quiz session."""
+    runner = GitRunner()
+    if not runner.is_git_repo():
+        click.echo("[ERROR] Not in a git repository.", err=True)
+        sys.exit(1)
+
+    runner.stage_files(list(files))
+    staged_diff = runner.get_staged_diff()
+    if not staged_diff.strip():
+        click.echo("[WARNING] No staged changes found for specified files.")
+        return
+
+    import uuid
+    codevoight_dir, db_path = get_repo_and_db_paths()
+    repo = StateRepository(db_path)
+    diff_hash = compute_diff_hash(staged_diff)
+
+    gen = DeterministicQuizGenerator()
+    questions = gen.generate_quiz(staged_diff, description)
+
+    now = time.time()
+    session = StagedSession(
+        session_id=str(uuid.uuid4())[:8],
+        diff_text=staged_diff,
+        diff_hash=diff_hash,
+        description=description,
+        status=SessionStatus.PENDING_QUIZ,
+        created_at=now,
+        expires_at=now + 1800.0,
+    )
+
+    repo.create_session(session, questions)
+    click.echo(f"[SUCCESS] Staged session created: {session.session_id}")
+    click.echo(f"Run 'codevoight quiz {session.session_id}' to take the quiz and unlock commit.")
+
+
+if __name__ == "__main__":
+    main()