nexu 0.2.5__py3-none-any.whl

nexu-0.2.5.dist-info/METADATA

@@ -0,0 +1,162 @@
+Metadata-Version: 2.4
+Name: nexu
+Version: 0.2.5
+Summary: Visual Intent Contract Orchestrator: freeze project slices, evolve capsules, verify intent contracts.
+Author-email: Tom Sapletta <tom@sapletta.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: capsule,contracts,intent,llm,mock,static-analysis,workflow
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+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: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0
+Requires-Dist: typer>=0.12.0
+Provides-Extra: dev
+Requires-Dist: costs>=0.1.20; extra == 'dev'
+Requires-Dist: goal>=2.1.0; extra == 'dev'
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pfix>=0.1.60; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: llm
+Requires-Dist: litellm>=1.0; extra == 'llm'
+Provides-Extra: watch
+Requires-Dist: watchdog>=4.0; extra == 'watch'
+Description-Content-Type: text/markdown
+
+# Vico
+
+
+## AI Cost Tracking
+
+![PyPI](https://img.shields.io/badge/pypi-costs-blue) ![Version](https://img.shields.io/badge/version-0.2.5-blue) ![Python](https://img.shields.io/badge/python-3.9+-blue) ![License](https://img.shields.io/badge/license-Apache--2.0-green)
+![AI Cost](https://img.shields.io/badge/AI%20Cost-$0.51-orange) ![Human Time](https://img.shields.io/badge/Human%20Time-2.3h-blue) ![Model](https://img.shields.io/badge/Model-openrouter%2Fqwen%2Fqwen3--coder--next-lightgrey)
+
+- 🤖 **LLM usage:** $0.5133 (5 commits)
+- 👤 **Human dev:** ~$231 (2.3h @ $100/h, 30min dedup)
+
+Generated on 2026-05-29 using [openrouter/qwen/qwen3-coder-next](https://openrouter.ai/qwen/qwen3-coder-next)
+
+---
+
+**Vico** — **Visual Intent Contract Orchestrator**.
+
+Vico is a Python package and CLI for creating small, isolated project capsules from a large codebase.
+It helps you freeze a baseline, extract a slice of code/data/contracts, evolve that slice through multiple
+LLM or human iterations, and verify the result against formal intent contracts before promoting it back.
+
+The core workflow is:
+
+```text
+freeze → capsule create → blueprint → iterate → export-prompt → verify → promote
+```
+
+Vico is designed to work with **Intract**-style intent contracts, but it can run as a standalone prototype.
+The goal is not to make an LLM magically correct. The goal is to keep the LLM inside a small, versioned,
+contract-bound sandbox and detect when its output diverges from declared intent.
+
+## What changed in 0.2.0
+
+The second iteration adds the missing practical loop around capsules:
+
+- baseline hash lock per capsule,
+- capsule diff against the frozen slice,
+- source drift check against the original files,
+- generated UI/API/test blueprint,
+- LLM-ready prompt export,
+- capsule status command,
+- richer verification with evidence for outputs, forbidden effects, required intents and secret-like values.
+
+## Why Vico?
+
+Long-running IDE prompting has a common failure mode:
+
+```text
+large repo + vague task + many steps = context drift and hallucinated implementation
+```
+
+Vico changes the operating model:
+
+```text
+large repo
+  ↓ freeze baseline
+small capsule
+  ↓ evolve only this capsule
+verified result
+  ↓ promote to the real project
+```
+
+## Install locally
+
+```bash
+python -m venv .venv
+. .venv/bin/activate
+pip install -e .[dev]
+vico --help
+```
+
+## First run
+
+```bash
+vico init .
+vico freeze . --name baseline
+vico capsule create . --name menu-icons --domain menu --include "examples/frontend_view/src/**" --route /menu-icons
+vico capsule blueprint menu-icons --print
+vico capsule iterate menu-icons --steps 3 --goal "Add preview, confidence and reason fields"
+vico capsule export-prompt menu-icons
+vico capsule verify menu-icons
+vico capsule diff menu-icons
+vico capsule drift menu-icons
+vico capsule promote menu-icons --dry-run
+```
+
+## Important folders
+
+```text
+src/vico/       Python package
+docs/           documentation
+examples/       runnable example projects
+tests/          unit tests
+```
+
+## Documentation
+
+Start here:
+
+- [Docs index](docs/README.md)
+- [Getting started](docs/getting-started.md)
+- [Architecture](docs/architecture.md)
+- [Commands](docs/commands.md)
+- [Capsule format](docs/capsule-format.md)
+- [Intent contracts](docs/intent-contracts.md)
+- [Verification model](docs/verification.md)
+- [Examples](docs/examples.md)
+- [Roadmap](docs/roadmap.md)
+
+## Main commands
+
+```bash
+vico init .
+vico freeze . --name baseline
+vico capsule create . --name my-slice --include "src/my_module/**"
+vico capsule list
+vico capsule status my-slice
+vico capsule blueprint my-slice
+vico capsule iterate my-slice --steps 10 --goal "Evolve final screen"
+vico capsule export-prompt my-slice
+vico capsule diff my-slice
+vico capsule drift my-slice
+vico capsule verify my-slice
+vico capsule promote my-slice --dry-run
+```
+
+## License
+
+Licensed under Apache-2.0.

nexu-0.2.5.dist-info/RECORD

@@ -0,0 +1,25 @@
+vico/__init__.py,sha256=Za4pJa4NUfmTkuozhc_cumhz9R20gJreE1o6APfdQV8,85
+vico/__main__.py,sha256=Qd-f8z2Q2vpiEP2x6PBFsJrpACWDVxFKQk820MhFmHo,59
+vico/blueprint.py,sha256=gZZaQ8sQFPcIggVk2Kkct3Fptu5H-kmwVBkYTZW8FcA,2308
+vico/capsule.py,sha256=BhlldQS1_bxM_YAMiFvp6RcRiUBIZuI-GOBrvvxDgd8,4139
+vico/cli.py,sha256=5omthXaj39M0_uIdspPJrUjUtcHI3AMzGFxy8Gqk74M,9321
+vico/diff.py,sha256=PgEudYl0PUwDvo3AWGMcHKXl4qbHyqM8tN63BQOyhRA,1163
+vico/drift.py,sha256=e6Q9-8oZiAWxrWFcOdEBC3JCacT3k_2Kbrg_GmmotmU,1279
+vico/export_prompt.py,sha256=g5imi0ZbdLl37ri5_9rcut3P5Gq5EskOiTAKydZd5yo,3068
+vico/files.py,sha256=FTw6RoVA2ZqVVifBXbSYJQjt0WEdDkkpWl4EO38k3fA,1400
+vico/freeze.py,sha256=hV35Rc60jloe2Blkb_eefgL5Knl6wi7Mfo1DCig2VKE,857
+vico/git.py,sha256=nNb5NK742864BsPLlIERrQ5BmwryuPv5AnZ6u839fH0,528
+vico/hashing.py,sha256=YWfXowKAujajxLccu6xLEJf6WhB5kI-NhnmAdU12fKA,406
+vico/init_project.py,sha256=nNPwerrnPQ-NABWNMUgdmt_ernN-Ov7FCDUqyEbZo_k,2217
+vico/intract.py,sha256=T3Oc-QKYqaqfSNEWcslVHEwosLTKlnxu_AM8g3DsHwM,4325
+vico/iterate.py,sha256=Y1vPfuJxUV1tg9lR5obY6Fm9X4KOqmiwTmgmeKj4xTQ,1774
+vico/models.py,sha256=i3cp43SARCJmWOt6MoSCRf-fcE4Rn66zFeUWOA8lSkc,4480
+vico/paths.py,sha256=Ntmgw7Rdy6OiF2SRM3BwDQEz8Kgavg2U04lHTGj81tg,766
+vico/promote.py,sha256=6_97KK4L_PEbBcjaxXYI3VXWJW7lKdwB-Ec1zcwwbEc,1079
+vico/status.py,sha256=_-2Mi1zWQU32-beMb1LL7xu8B3Dwtydgcw4zkbUI5ac,1245
+vico/verify.py,sha256=cSp4ML67sa9sGKkIZWh-E1SSidahjOv0mukKOlL0gAM,8356
+nexu-0.2.5.dist-info/METADATA,sha256=ozAQj9BC9_vdVb7styWhdDBwUn1DoX5j0YjXhtHeleY,5162
+nexu-0.2.5.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+nexu-0.2.5.dist-info/entry_points.txt,sha256=k2shiqY3NKmRNxX2naq1rXE4vuoxhqhZ2AaFI2YwWbc,38
+nexu-0.2.5.dist-info/licenses/LICENSE,sha256=LohVyrbMSdy_MRztx2hmoCEm6khRfo7doDiZ3SpJCNs,600
+nexu-0.2.5.dist-info/RECORD,,

nexu-0.2.5.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

nexu-0.2.5.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+vico = vico.cli:app

nexu-0.2.5.dist-info/licenses/LICENSE

@@ -0,0 +1,16 @@
+Apache License
+Version 2.0, January 2004
+
+Copyright 2026 Vico contributors
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

vico/__init__.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+__version__ = "0.2.5"
+
+__all__ = ["__version__"]

vico/__main__.py

@@ -0,0 +1,4 @@
+from .cli import app
+
+if __name__ == "__main__":
+    app()

vico/blueprint.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from .capsule import load_capsule
+from .intract import read_manifest_contracts
+from .models import utc_now, write_yaml
+from .paths import capsule_dir
+
+
+def build_blueprint(root: Path, name: str) -> dict:
+    capsule = load_capsule(root, name)
+    base = capsule_dir(root, name)
+    contracts = read_manifest_contracts(base / capsule.contracts_manifest)
+    routes = capsule.selection.routes
+    endpoints = capsule.selection.endpoints
+
+    screens = []
+    for route in routes or [f"/capsules/{name}"]:
+        screens.append(
+            {
+                "route": route,
+                "layout": "capsule_preview",
+                "sections": [
+                    {"id": "intent_summary", "type": "summary"},
+                    {"id": "input_fixtures", "type": "data_panel"},
+                    {"id": "preview", "type": "mock_surface"},
+                    {"id": "evidence", "type": "verification_panel"},
+                ],
+            }
+        )
+
+    api = []
+    for endpoint in endpoints:
+        method, _, path = endpoint.partition(":")
+        api.append(
+            {
+                "method": method or "GET",
+                "path": path or endpoint,
+                "kind": "mock_endpoint",
+                "response": {"status": "ok", "source": "capsule_fixture"},
+            }
+        )
+
+    blueprint = {
+        "version": "vico.blueprint.v1",
+        "capsule": name,
+        "created_at": utc_now(),
+        "type": capsule.type,
+        "domain": capsule.selection.domain,
+        "contracts": [
+            {
+                "id": contract.contract_id,
+                "intent": contract.intent,
+                "input": contract.input,
+                "output": contract.output,
+                "effect": contract.effect,
+                "forbid": contract.forbid,
+            }
+            for contract in contracts
+        ],
+        "ui": {"screens": screens},
+        "api": {"endpoints": api},
+        "tests": {
+            "suggested": [
+                "contract_outputs_are_present",
+                "forbidden_effects_are_absent",
+                "capsule_promotion_plan_is_reviewable",
+            ]
+        },
+    }
+    write_yaml(base / "blueprints" / "blueprint.yaml", blueprint)
+    return blueprint

vico/capsule.py

@@ -0,0 +1,122 @@
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+from .files import collect_files, rel
+from .git import current_git_sha
+from .hashing import sha256_file
+from .models import Capsule, CapsuleSelection, read_yaml, utc_now, write_yaml
+from .paths import capsule_dir, capsules_dir, ensure_project_dirs
+
+
+def default_contract_manifest(capsule: Capsule) -> dict:
+    intent = f"evolve:{capsule.name.replace('-', '_')}"
+    return {
+        "version": "intract.v1",
+        "project": {"name": capsule.name, "intent": intent},
+        "contracts": [
+            {
+                "id": f"capsule.{capsule.name}.main",
+                "scope": "module",
+                "intent": intent,
+                "priority": 2,
+                "domain": capsule.selection.domain,
+                "input": ["frozen_slice", "fixtures", "user_goal"],
+                "output": ["evolved_capsule", "promotion_plan", "evidence_map"],
+                "effect": ["read"],
+                "forbid": ["destructive_write", "secret_leak"],
+                "require": ["validate.contracts", "verify.capsule"],
+                "validate": ["input_presence", "output_presence", "no_forbidden_effect"],
+                "meaning": "evolve this isolated project slice without mutating the source project",
+            }
+        ],
+    }
+
+
+def create_capsule(
+    root: Path,
+    name: str,
+    *,
+    domain: str = "general",
+    include: list[str] | None = None,
+    exclude: list[str] | None = None,
+    routes: list[str] | None = None,
+    endpoints: list[str] | None = None,
+    snapshot_id: str | None = None,
+) -> Capsule:
+    ensure_project_dirs(root)
+    include = include or ["src/**", "contracts/**", "frontend/**", "backend/**", "shared/**", "*.py", "*.md"]
+    selection = CapsuleSelection(
+        domain=domain,
+        routes=routes or [],
+        endpoints=endpoints or [],
+        include=include,
+        exclude=exclude or [],
+    )
+    target = capsule_dir(root, name)
+    if target.exists():
+        raise FileExistsError(f"Capsule already exists: {target}")
+
+    copied: list[str] = []
+    baseline_files: dict[str, str] = {}
+    capsule = Capsule(
+        name=name,
+        source_project_root=str(root),
+        source_snapshot_id=snapshot_id,
+        source_git_sha=current_git_sha(root),
+        selection=selection,
+        baseline_files=baseline_files,
+    )
+
+    for subdir in [
+        target / "src",
+        target / "fixtures",
+        target / "iterations" / "S0",
+        target / "evidence",
+        target / "prompts",
+        target / "blueprints",
+    ]:
+        subdir.mkdir(parents=True, exist_ok=True)
+
+    for source in collect_files(root, include=include, exclude=selection.exclude):
+        relative = rel(source, root)
+        destination = target / "src" / relative
+        destination.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(source, destination)
+        copied.append(relative)
+        baseline_files[relative] = sha256_file(source)
+
+    write_yaml(target / "capsule.yaml", capsule.to_dict())
+    write_yaml(target / "intract.yaml", default_contract_manifest(capsule))
+    write_yaml(
+        target / "iterations" / "S0" / "state.yaml",
+        {
+            "state": "S0",
+            "created_at": utc_now(),
+            "description": "Frozen capsule baseline copied from source project.",
+            "copied_files": copied,
+            "baseline_lock": {
+                "source_git_sha": capsule.source_git_sha,
+                "source_snapshot_id": capsule.source_snapshot_id,
+                "file_count": len(baseline_files),
+            },
+        },
+    )
+    return capsule
+
+
+def list_capsules(root: Path) -> list[str]:
+    base = capsules_dir(root)
+    if not base.exists():
+        return []
+    return sorted(path.name for path in base.iterdir() if path.is_dir())
+
+
+def load_capsule(root: Path, name: str) -> Capsule:
+    data = read_yaml(capsule_dir(root, name) / "capsule.yaml")
+    return Capsule.from_dict(data)
+
+
+def save_capsule(root: Path, capsule: Capsule) -> None:
+    write_yaml(capsule_dir(root, capsule.name) / "capsule.yaml", capsule.to_dict())

vico/cli.py

@@ -0,0 +1,219 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from rich.console import Console
+from rich.table import Table
+from rich.syntax import Syntax
+
+from .blueprint import build_blueprint
+from .capsule import create_capsule, list_capsules
+from .diff import diff_capsule
+from .drift import check_source_drift
+from .export_prompt import export_iteration_prompt
+from .freeze import freeze_project
+from .init_project import init_project
+from .iterate import iterate_capsule
+from .paths import project_root
+from .promote import build_promotion_plan
+from .status import capsule_status
+from .verify import verify_capsule
+
+app = typer.Typer(help="Vico — Visual Intent Contract Orchestrator.")
+capsule_app = typer.Typer(help="Create, iterate, verify and promote project capsules.")
+app.add_typer(capsule_app, name="capsule")
+console = Console()
+
+
+@app.command()
+def init(path: Annotated[str, typer.Argument(help="Project root.")] = ".") -> None:
+    """Initialize Vico files in a project."""
+    root = project_root(path)
+    created = init_project(root)
+    if not created:
+        console.print("[green]Vico already initialized.[/green]")
+        return
+    for item in created:
+        console.print(f"[green]created[/green] {item.relative_to(root)}")
+
+
+@app.command()
+def freeze(
+    path: Annotated[str, typer.Argument(help="Project root.")] = ".",
+    name: Annotated[str, typer.Option("--name", "-n", help="Snapshot name.")] = "baseline",
+    include: Annotated[list[str] | None, typer.Option("--include", "-i", help="Glob include.")] = None,
+) -> None:
+    """Freeze a lightweight hash snapshot of the current project."""
+    root = project_root(path)
+    snapshot = freeze_project(root, name=name, include=include)
+    console.print(f"[green]snapshot[/green] {snapshot.id}")
+    console.print(f"files: {len(snapshot.files)}")
+    if snapshot.git_sha:
+        console.print(f"git: {snapshot.git_sha[:12]}")
+
+
+@capsule_app.command("create")
+def capsule_create(
+    path: Annotated[str, typer.Argument(help="Project root.")] = ".",
+    name: Annotated[str, typer.Option("--name", "-n", help="Capsule name.")] = "capsule",
+    domain: Annotated[str, typer.Option("--domain", "-d", help="Domain name.")] = "general",
+    include: Annotated[list[str] | None, typer.Option("--include", "-i", help="Glob include pattern.")] = None,
+    route: Annotated[list[str] | None, typer.Option("--route", help="UI route covered by capsule.")] = None,
+    endpoint: Annotated[list[str] | None, typer.Option("--endpoint", help="Endpoint covered by capsule.")] = None,
+    snapshot: Annotated[str | None, typer.Option("--snapshot", help="Source snapshot id.")] = None,
+) -> None:
+    """Create an isolated capsule from selected project files."""
+    root = project_root(path)
+    capsule = create_capsule(
+        root,
+        name,
+        domain=domain,
+        include=include,
+        routes=route,
+        endpoints=endpoint,
+        snapshot_id=snapshot,
+    )
+    build_blueprint(root, capsule.name)
+    console.print(f"[green]capsule created[/green] {capsule.name}")
+    console.print(f"location: .vico/capsules/{capsule.name}")
+    console.print(f"baseline files: {len(capsule.baseline_files)}")
+
+
+@capsule_app.command("list")
+def capsule_list(path: Annotated[str, typer.Argument(help="Project root.")] = ".") -> None:
+    """List local capsules."""
+    root = project_root(path)
+    names = list_capsules(root)
+    if not names:
+        console.print("[yellow]No capsules found.[/yellow]")
+        return
+    table = Table("Capsule")
+    for name in names:
+        table.add_row(name)
+    console.print(table)
+
+
+@capsule_app.command("status")
+def capsule_status_command(
+    name: Annotated[str, typer.Argument(help="Capsule name.")],
+    path: Annotated[str, typer.Option("--path", "-p", help="Project root.")] = ".",
+) -> None:
+    """Show capsule status, latest iteration, diff counters and verification summary."""
+    root = project_root(path)
+    status = capsule_status(root, name)
+    console.print(f"[bold]{status['name']}[/bold] ({status['type']})")
+    console.print(f"domain: {status['domain']}")
+    console.print(f"latest iteration: {status['latest_iteration']}")
+    files = status["files"]
+    table = Table("Counter", "Value")
+    for key, value in files.items():
+        table.add_row(key, str(value))
+    console.print(table)
+    if status.get("verification"):
+        verification = status["verification"]
+        console.print(f"verification: {verification.get('status')} score={verification.get('score')}")
+
+
+@capsule_app.command("iterate")
+def capsule_iterate(
+    name: Annotated[str, typer.Argument(help="Capsule name.")],
+    path: Annotated[str, typer.Option("--path", "-p", help="Project root.")] = ".",
+    steps: Annotated[int, typer.Option("--steps", "-s", help="How many planned iterations to create.")] = 1,
+    goal: Annotated[str, typer.Option("--goal", "-g", help="Iteration goal.")] = "Evolve capsule safely.",
+) -> None:
+    """Create planned S1..Sn iteration folders and prompts."""
+    root = project_root(path)
+    created = iterate_capsule(root, name, steps=steps, goal=goal)
+    console.print(f"[green]created iterations[/green] {', '.join(created)}")
+
+
+@capsule_app.command("blueprint")
+def capsule_blueprint(
+    name: Annotated[str, typer.Argument(help="Capsule name.")],
+    path: Annotated[str, typer.Option("--path", "-p", help="Project root.")] = ".",
+    print_yaml: Annotated[bool, typer.Option("--print/--no-print", help="Print generated YAML.")] = False,
+) -> None:
+    """Generate a UI/API/test blueprint from capsule selection and Intract contracts."""
+    root = project_root(path)
+    blueprint = build_blueprint(root, name)
+    console.print(f"[green]blueprint[/green] .vico/capsules/{name}/blueprints/blueprint.yaml")
+    if print_yaml:
+        import yaml
+
+        console.print(Syntax(yaml.safe_dump(blueprint, sort_keys=False, allow_unicode=True), "yaml"))
+
+
+@capsule_app.command("export-prompt")
+def capsule_export_prompt(
+    name: Annotated[str, typer.Argument(help="Capsule name.")],
+    path: Annotated[str, typer.Option("--path", "-p", help="Project root.")] = ".",
+    iteration: Annotated[str | None, typer.Option("--iteration", "-i", help="Iteration id, e.g. S3.")] = None,
+) -> None:
+    """Export an LLM-ready prompt constrained by capsule contracts and blueprint."""
+    root = project_root(path)
+    export = export_iteration_prompt(root, name, iteration=iteration)
+    console.print(f"[green]prompt exported[/green] {Path(export.path).relative_to(root)}")
+
+
+@capsule_app.command("diff")
+def capsule_diff(
+    name: Annotated[str, typer.Argument(help="Capsule name.")],
+    path: Annotated[str, typer.Option("--path", "-p", help="Project root.")] = ".",
+) -> None:
+    """Compare capsule src files against the frozen baseline lock."""
+    root = project_root(path)
+    report = diff_capsule(root, name)
+    table = Table("Kind", "Count")
+    table.add_row("added", str(len(report.added)))
+    table.add_row("modified", str(len(report.modified)))
+    table.add_row("deleted", str(len(report.deleted)))
+    table.add_row("unchanged", str(len(report.unchanged)))
+    console.print(table)
+
+
+@capsule_app.command("drift")
+def capsule_drift(
+    name: Annotated[str, typer.Argument(help="Capsule name.")],
+    path: Annotated[str, typer.Option("--path", "-p", help="Project root.")] = ".",
+) -> None:
+    """Check whether the original source files changed since capsule creation."""
+    root = project_root(path)
+    report = check_source_drift(root, name)
+    color = "green" if report["status"] == "pass" else "yellow"
+    console.print(f"status: [{color}]{report['status']}[/]")
+    console.print(f"changed: {len(report['changed'])}")
+    console.print(f"missing: {len(report['missing'])}")
+
+
+@capsule_app.command("verify")
+def capsule_verify(
+    name: Annotated[str, typer.Argument(help="Capsule name.")],
+    path: Annotated[str, typer.Option("--path", "-p", help="Project root.")] = ".",
+) -> None:
+    """Verify a capsule against basic intent-contract gates."""
+    root = project_root(path)
+    report = verify_capsule(root, name)
+    color = "green" if report.status == "pass" else "red" if report.status == "fail" else "yellow"
+    console.print(f"status: [{color}]{report.status}[/]")
+    console.print(f"score: {report.score:.2f}")
+    table = Table("Gate", "Status", "Message")
+    for finding in report.findings:
+        table.add_row(finding.code, finding.status, finding.message)
+    console.print(table)
+
+
+@capsule_app.command("promote")
+def capsule_promote(
+    name: Annotated[str, typer.Argument(help="Capsule name.")],
+    path: Annotated[str, typer.Option("--path", "-p", help="Project root.")] = ".",
+    dry_run: Annotated[bool, typer.Option("--dry-run/--apply", help="Only create a promotion plan.")] = True,
+) -> None:
+    """Build a promotion plan for copying capsule changes back to the source project."""
+    root = project_root(path)
+    plan = build_promotion_plan(root, name)
+    console.print(f"[green]promotion plan[/green] .vico/capsules/{name}/promotion-plan.yaml")
+    console.print(f"files to review: {len(plan['files_to_review'])}")
+    if not dry_run:
+        console.print("[yellow]Apply mode is intentionally not implemented in MVP. Review the plan first.[/yellow]")

vico/diff.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from .capsule import load_capsule
+from .files import collect_files, rel
+from .hashing import sha256_file
+from .models import CapsuleDiff, write_yaml
+from .paths import capsule_dir
+
+
+def diff_capsule(root: Path, name: str) -> CapsuleDiff:
+    capsule = load_capsule(root, name)
+    base = capsule_dir(root, name)
+    src = base / "src"
+    current: dict[str, str] = {
+        rel(path, src): sha256_file(path)
+        for path in collect_files(src)
+    }
+    baseline = capsule.baseline_files
+
+    added = sorted(path for path in current if path not in baseline)
+    deleted = sorted(path for path in baseline if path not in current)
+    modified = sorted(path for path, digest in current.items() if path in baseline and baseline[path] != digest)
+    unchanged = sorted(path for path, digest in current.items() if path in baseline and baseline[path] == digest)
+
+    report = CapsuleDiff(
+        capsule=name,
+        added=added,
+        modified=modified,
+        deleted=deleted,
+        unchanged=unchanged,
+    )
+    write_yaml(base / "evidence" / "diff.yaml", report.to_dict())
+    return report