delimit-cli 3.5.1 → 3.6.1

package/README.md

@@ -1,11 +1,11 @@
 # delimit
 
-Stop Describing. Start Building.
+Your AI Remembers. Verifies. Ships.
 
 [![npm](https://img.shields.io/npm/v/delimit-cli)](https://www.npmjs.com/package/delimit-cli)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
-77 MCP governance tools for AI coding assistants. Prevents hallucinated results, verifies tests actually ran, enforces policies, and catches breaking API changes. Works with Claude Code, Codex, and Cursor.
+Governance layer for AI coding assistants. Your AI verifies its own work -- confirms tests ran, catches breaking API changes, audits security, and enforces policies. Works with Claude Code, Codex, and Cursor.
 
 ## Install
 
@@ -13,18 +13,18 @@ Stop Describing. Start Building.
 npx delimit-cli setup
 ```
 
-10 seconds. No API keys. No account. Installs MCP tools into your existing AI coding assistant.
+10 seconds. No API keys. No account. Installs into your existing AI coding assistant.
 
-## What happens
+## What it does
 
-Your AI agent gets 77 governance tools that verify its own work:
+Your AI agent gains the ability to verify its own work:
 
-- **Test verification** — confirms tests actually ran, measures coverage
-- **Security audit** — scans dependencies, detects hardcoded secrets and anti-patterns
-- **API governance** — catches breaking changes in OpenAPI specs before they ship
-- **Repo analysis** — code quality, health checks, config validation
-- **Deploy tracking** — plan, build, publish, verify, rollback
-- **Multi-model consensus** — Grok + Gemini + Codex deliberate on strategic decisions
+- **Test verification** -- confirms tests actually ran, measures coverage
+- **Security audit** -- scans dependencies, detects hardcoded secrets and anti-patterns
+- **API governance** -- catches breaking changes in OpenAPI specs before they ship
+- **Repo analysis** -- code quality, health checks, config validation
+- **Deploy tracking** -- plan, build, publish, verify, rollback
+- **Multi-model consensus** -- multiple AI models deliberate on strategic decisions
 
 ## Real examples
 
@@ -32,14 +32,13 @@ These happened in a single session:
 
 | Command | Result |
 |---------|--------|
-| "keep building" | Parallel agents replaced 37 dead tools with real implementations |
-| "fix the 502 error" | Traced Vercel → Caddy → Docker, found wrong IP, fixed, verified |
-| "run test coverage" | 299 → 1,113 tests, zero written manually |
+| "fix the 502 error" | Traced Vercel to Caddy to Docker, found wrong IP, fixed, verified |
+| "run test coverage" | 299 to 1,113 tests, zero written manually |
 | "run consensus on pricing" | 3 AI models debated, reached unanimous agreement |
 
 ## Free vs Pro
 
-**Free (15 tools)**: lint, diff, policy, semver, test coverage, security audit, repo analysis, zero-spec extraction, and more.
+**Free**: lint, diff, policy, semver, test coverage, security audit, repo analysis, zero-spec extraction, and more.
 
 **Pro ($10/mo)**: governance, deploy tracking, memory/vault, multi-model deliberation, evidence collection. Activate with `delimit activate YOUR_KEY`.
 

package/bin/delimit-setup.js

@@ -290,48 +290,33 @@ Run full governance compliance checks. Verify security, policy compliance, evide
 
     const claudeMd = path.join(os.homedir(), 'CLAUDE.md');
     if (!fs.existsSync(claudeMd)) {
-        fs.writeFileSync(claudeMd, `# Delimit AI Guardrails
-
-Delimit governance tools are installed. On first use, try:
-
-- "check governance health" — see the status of this project
-- "initialize governance" — set up policies and ledger for this project
-- "run test coverage" — measure test coverage
-- "analyze this repo" — get a health report
-
-## Quick Start
-If this project hasn't been initialized for governance yet, say:
-"initialize governance for this project"
-
-This creates .delimit/policies.yml and a ledger directory.
-
-## Available Agents
-- /lint — check API specs for breaking changes
-- /engineering — build, test, refactor with governance checks
-- /governance — full compliance audit
-
-## Key Tools
-- delimit_init — bootstrap governance for a project
-- delimit_lint — diff two OpenAPI specs
-- delimit_test_coverage — measure test coverage
-- delimit_gov_health — check governance status
-- delimit_repo_analyze — full repo health report
-`);
+        fs.writeFileSync(claudeMd, getClaudeMdContent());
         log(`  ${green('✓')} Created ${claudeMd} with first-run guidance`);
     } else {
-        log(`  ${dim('  CLAUDE.md already exists — skipped')}`);
+        // Check if existing CLAUDE.md is an older Delimit version that should be upgraded
+        const existing = fs.readFileSync(claudeMd, 'utf-8');
+        if (existing.includes('# Delimit AI Guardrails') || existing.includes('delimit_init') || existing.includes('delimit_lint')) {
+            fs.writeFileSync(claudeMd, getClaudeMdContent());
+            log(`  ${green('✓')} Updated ${claudeMd} with improved onboarding`);
+        } else {
+            log(`  ${dim('  CLAUDE.md already exists with custom content — skipped')}`);
+        }
     }
 
-    // Step 6: Summary
+    // Step 6: Try it now
     step(6, 'Done!');
     log('');
-    log(`  ${green('Delimit is installed.')} Your AI agents are now monitored.`);
+    log(`  ${green('Delimit is installed.')} Your AI now has persistent memory and governance.`);
+    log('');
+    log('  Try it now:');
+    log(`  ${bold('$ claude')}`);
+    log('');
+    log(`  Then say: ${blue('"check this project\'s health"')}`);
     log('');
-    log('  What happens next:');
-    log(`  ${dim('1.')} Start Claude Code in any project`);
-    log(`  ${dim('2.')} The delimit MCP tools load automatically`);
-    log(`  ${dim('3.')} Use agents: ${blue('/lint')}, ${blue('/governance')}, ${blue('/engineering')}`);
-    log(`  ${dim('4.')} Or ask: "check governance health" / "run test coverage"`);
+    log('  Or try:');
+    log(`  ${dim('-')} "add to ledger: set up CI pipeline"  ${dim('— start tracking tasks')}`);
+    log(`  ${dim('-')} "what\'s on the ledger?"               ${dim('— see what\'s pending')}`);
+    log(`  ${dim('-')} "delimit help"                        ${dim('— see all capabilities')}`);
     log('');
     log(`  ${dim('Config:')} ${MCP_CONFIG}`);
     log(`  ${dim('Server:')} ${actualServer}`);
@@ -342,6 +327,36 @@ This creates .delimit/policies.yml and a ledger directory.
     log('');
 }
 
+function getClaudeMdContent() {
+    return `# Delimit
+
+Your AI has persistent memory, verified execution, and governance.
+
+## First time? Say one of these:
+- "check this project's health" -- see what Delimit finds
+- "add to ledger: [anything]" -- start tracking tasks
+- "what's on the ledger?" -- see what's pending
+
+## Returning? Your AI remembers:
+- Ledger items persist across sessions
+- Governance rules stay configured
+- Memory carries forward
+
+## On first session, your AI will automatically:
+1. Diagnose the environment to verify everything is connected
+2. Check the ledger for any pending items from previous sessions
+3. If no governance exists yet, suggest initializing it
+
+## Available Agents
+- /lint -- check API specs for breaking changes
+- /engineering -- build, test, refactor with governance checks
+- /governance -- full compliance audit
+
+## Need help?
+Say "delimit help" for docs on any capability.
+`;
+}
+
 function copyDir(src, dest) {
     fs.mkdirSync(dest, { recursive: true });
     for (const entry of fs.readdirSync(src, { withFileTypes: true })) {

package/gateway/ai/governance.py

@@ -0,0 +1,254 @@
+"""
+Delimit Governance Layer — the loop that keeps AI agents on track.
+
+Every tool flows through governance. Governance:
+1. Logs what happened (evidence)
+2. Checks result against rules (thresholds, policies)
+3. Auto-creates ledger items for failures/warnings
+4. Suggests next steps (loops back to keep building)
+
+This replaces _with_next_steps — governance IS the next step system.
+"""
+
+import json
+import logging
+import time
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+logger = logging.getLogger("delimit.governance")
+
+
+# Governance rules — what triggers auto-ledger-creation
+RULES = {
+    "test_coverage": {
+        "threshold_key": "line_coverage",
+        "threshold": 80,
+        "comparison": "below",
+        "ledger_title": "Test coverage below {threshold}% — currently {value}%",
+        "ledger_type": "fix",
+        "ledger_priority": "P1",
+    },
+    "security_audit": {
+        "trigger_key": "vulnerabilities",
+        "trigger_if_nonempty": True,
+        "ledger_title": "Security: {count} vulnerabilities found",
+        "ledger_type": "fix",
+        "ledger_priority": "P0",
+    },
+    "security_scan": {
+        "trigger_key": "vulnerabilities",
+        "trigger_if_nonempty": True,
+        "ledger_title": "Security scan: {count} issues detected",
+        "ledger_type": "fix",
+        "ledger_priority": "P0",
+    },
+    "lint": {
+        "trigger_key": "violations",
+        "trigger_if_nonempty": True,
+        "ledger_title": "API lint: {count} violations found",
+        "ledger_type": "fix",
+        "ledger_priority": "P1",
+    },
+    "deliberate": {
+        "trigger_key": "unanimous",
+        "trigger_if_true": True,
+        "extract_actions": True,
+        "ledger_title": "Deliberation consensus reached — action items pending",
+        "ledger_type": "strategy",
+        "ledger_priority": "P1",
+    },
+    "gov_health": {
+        "trigger_key": "status",
+        "trigger_values": ["not_initialized", "degraded"],
+        "ledger_title": "Governance health: {value} — needs attention",
+        "ledger_type": "fix",
+        "ledger_priority": "P1",
+    },
+    "docs_validate": {
+        "threshold_key": "coverage_percent",
+        "threshold": 50,
+        "comparison": "below",
+        "ledger_title": "Documentation coverage below {threshold}% — currently {value}%",
+        "ledger_type": "task",
+        "ledger_priority": "P2",
+    },
+}
+
+# Next steps registry — what to do after each tool
+NEXT_STEPS = {
+    "lint": [
+        {"tool": "delimit_explain", "reason": "Get migration guide for violations", "premium": False},
+        {"tool": "delimit_semver", "reason": "Classify the version bump", "premium": False},
+    ],
+    "diff": [
+        {"tool": "delimit_semver", "reason": "Classify changes as MAJOR/MINOR/PATCH", "premium": False},
+        {"tool": "delimit_policy", "reason": "Check against governance policies", "premium": False},
+    ],
+    "semver": [
+        {"tool": "delimit_explain", "reason": "Generate human-readable changelog", "premium": False},
+    ],
+    "init": [
+        {"tool": "delimit_gov_health", "reason": "Verify governance is set up correctly", "premium": True},
+        {"tool": "delimit_diagnose", "reason": "Check for any issues", "premium": False},
+    ],
+    "test_coverage": [
+        {"tool": "delimit_test_generate", "reason": "Generate tests for uncovered files", "premium": False},
+    ],
+    "security_audit": [
+        {"tool": "delimit_evidence_collect", "reason": "Collect evidence of findings", "premium": True},
+    ],
+    "gov_health": [
+        {"tool": "delimit_gov_status", "reason": "See detailed governance status", "premium": True},
+        {"tool": "delimit_repo_analyze", "reason": "Full repo health report", "premium": True},
+    ],
+    "deploy_plan": [
+        {"tool": "delimit_deploy_build", "reason": "Build the deployment", "premium": True},
+    ],
+    "deploy_build": [
+        {"tool": "delimit_deploy_publish", "reason": "Publish the build", "premium": True},
+    ],
+    "deploy_publish": [
+        {"tool": "delimit_deploy_verify", "reason": "Verify the deployment", "premium": True},
+    ],
+    "deploy_verify": [
+        {"tool": "delimit_deploy_rollback", "reason": "Rollback if unhealthy", "premium": True},
+    ],
+    "repo_analyze": [
+        {"tool": "delimit_security_audit", "reason": "Scan for security issues", "premium": False},
+        {"tool": "delimit_gov_health", "reason": "Check governance status", "premium": True},
+    ],
+    "deliberate": [
+        {"tool": "delimit_ledger_context", "reason": "Review what's on the ledger after consensus", "premium": False},
+    ],
+    "ledger_add": [
+        {"tool": "delimit_ledger_context", "reason": "See updated ledger state", "premium": False},
+    ],
+    "diagnose": [
+        {"tool": "delimit_init", "reason": "Initialize governance if not set up", "premium": False},
+    ],
+}
+
+
+def govern(tool_name: str, result: Dict[str, Any], project_path: str = ".") -> Dict[str, Any]:
+    """
+    Run governance on a tool's result. This is the central loop.
+
+    1. Check result against rules
+    2. Auto-create ledger items if thresholds breached
+    3. Add next_steps for the AI to continue
+    4. Return enriched result
+
+    Every tool should call this before returning.
+    """
+    # Strip "delimit_" prefix for rule matching
+    clean_name = tool_name.replace("delimit_", "")
+
+    governed_result = dict(result)
+
+    # 1. Check governance rules
+    rule = RULES.get(clean_name)
+    auto_items = []
+
+    if rule:
+        triggered = False
+        context = {}
+
+        # Threshold check (e.g., coverage < 80%)
+        if "threshold_key" in rule:
+            value = _deep_get(result, rule["threshold_key"])
+            if value is not None:
+                threshold = rule["threshold"]
+                if rule.get("comparison") == "below" and value < threshold:
+                    triggered = True
+                    context = {"value": f"{value:.1f}" if isinstance(value, float) else str(value), "threshold": str(threshold)}
+
+        # Non-empty list check (e.g., vulnerabilities found)
+        if "trigger_key" in rule and "trigger_if_nonempty" in rule:
+            items = _deep_get(result, rule["trigger_key"])
+            if items and isinstance(items, list) and len(items) > 0:
+                triggered = True
+                context = {"count": str(len(items))}
+
+        # Value match check (e.g., status == "degraded")
+        if "trigger_key" in rule and "trigger_values" in rule:
+            value = _deep_get(result, rule["trigger_key"])
+            if value in rule["trigger_values"]:
+                triggered = True
+                context = {"value": str(value)}
+
+        # Boolean check (e.g., unanimous == True)
+        if "trigger_key" in rule and "trigger_if_true" in rule:
+            value = _deep_get(result, rule["trigger_key"])
+            if value:
+                triggered = True
+
+        if triggered:
+            title = rule["ledger_title"].format(**context) if context else rule["ledger_title"]
+            auto_items.append({
+                "title": title,
+                "type": rule.get("ledger_type", "task"),
+                "priority": rule.get("ledger_priority", "P1"),
+                "source": f"governance:{clean_name}",
+            })
+
+    # 2. Auto-create ledger items
+    if auto_items:
+        try:
+            from ai.ledger_manager import add_item
+            created = []
+            for item in auto_items:
+                entry = add_item(
+                    title=item["title"],
+                    type=item["type"],
+                    priority=item["priority"],
+                    source=item["source"],
+                    project_path=project_path,
+                )
+                created.append(entry.get("added", {}).get("id", ""))
+            governed_result["governance"] = {
+                "action": "ledger_items_created",
+                "items": created,
+                "reason": "Governance rule triggered by tool result",
+            }
+        except Exception as e:
+            logger.warning("Governance auto-ledger failed: %s", e)
+
+    # 3. Add next steps
+    steps = NEXT_STEPS.get(clean_name, [])
+    if steps:
+        governed_result["next_steps"] = steps
+
+    # 4. Always suggest checking the ledger
+    if clean_name not in ("ledger_add", "ledger_done", "ledger_list", "ledger_context", "ventures", "version", "help", "diagnose", "activate", "license_status", "models"):
+        if "next_steps" not in governed_result:
+            governed_result["next_steps"] = []
+        # Don't duplicate
+        existing = {s.get("tool") for s in governed_result.get("next_steps", [])}
+        if "delimit_ledger_context" not in existing:
+            governed_result["next_steps"].append({
+                "tool": "delimit_ledger_context",
+                "reason": "Check ledger for what's next",
+                "premium": False,
+            })
+
+    return governed_result
+
+
+def _deep_get(d: Dict, key: str) -> Any:
+    """Get a value from a dict, supporting nested keys with dots."""
+    if "." in key:
+        parts = key.split(".", 1)
+        sub = d.get(parts[0])
+        if isinstance(sub, dict):
+            return _deep_get(sub, parts[1])
+        return None
+
+    # Check top-level and common nested locations
+    if key in d:
+        return d[key]
+    # Check inside 'data', 'result', 'overall_coverage'
+    for wrapper in ["data", "result", "overall_coverage", "summary"]:
+        if isinstance(d.get(wrapper), dict) and key in d[wrapper]:
+            return d[wrapper][key]
+    return None

package/gateway/ai/ledger_manager.py

@@ -1,35 +1,119 @@
 """
 Delimit Ledger Manager — Strategy + Operational ledger as first-class MCP tools.
 
-Two ledgers:
+Two ledgers per project:
 - Strategy: consensus decisions, positioning, pricing, product direction
 - Operational: tasks, bugs, features — the "keep building" items
 
-Both are append-only JSONL at ~/.delimit/ledger/
+Ledger lives at {project}/.delimit/ledger/ (project-local).
+Ventures auto-registered at ~/.delimit/ventures.json on first use.
 """
 
 import json
 import hashlib
+import os
+import subprocess
 import time
-import uuid
 from pathlib import Path
 from typing import Any, Dict, List, Optional
 
-LEDGER_DIR = Path.home() / ".delimit" / "ledger"
-STRATEGY_LEDGER = LEDGER_DIR / "strategy.jsonl"
-OPS_LEDGER = LEDGER_DIR / "operations.jsonl"
-
-
-def _ensure():
-    LEDGER_DIR.mkdir(parents=True, exist_ok=True)
-    for f in [STRATEGY_LEDGER, OPS_LEDGER]:
+GLOBAL_DIR = Path.home() / ".delimit"
+VENTURES_FILE = GLOBAL_DIR / "ventures.json"
+
+
+def _detect_venture(project_path: str = ".") -> Dict[str, str]:
+    """Auto-detect venture/project info from the directory."""
+    p = Path(project_path).resolve()
+    info = {"name": p.name, "path": str(p)}
+
+    # Try package.json
+    pkg = p / "package.json"
+    if pkg.exists():
+        try:
+            d = json.loads(pkg.read_text())
+            info["name"] = d.get("name", p.name)
+            info["type"] = "node"
+        except Exception:
+            pass
+
+    # Try pyproject.toml
+    pyproj = p / "pyproject.toml"
+    if pyproj.exists():
+        try:
+            text = pyproj.read_text()
+            for line in text.splitlines():
+                if line.strip().startswith("name"):
+                    name = line.split("=", 1)[1].strip().strip('"').strip("'")
+                    if name:
+                        info["name"] = name
+                        info["type"] = "python"
+                        break
+        except Exception:
+            pass
+
+    # Try git remote
+    try:
+        remote = subprocess.run(
+            ["git", "remote", "get-url", "origin"],
+            capture_output=True, text=True, timeout=3, cwd=str(p)
+        )
+        if remote.returncode == 0:
+            url = remote.stdout.strip()
+            # Extract repo name from URL
+            repo = url.rstrip("/").split("/")[-1].replace(".git", "")
+            info["repo"] = url
+            if not info.get("type"):
+                info["name"] = repo
+    except Exception:
+        pass
+
+    return info
+
+
+def _register_venture(info: Dict[str, str]):
+    """Silently register a venture in the global registry."""
+    GLOBAL_DIR.mkdir(parents=True, exist_ok=True)
+    ventures = {}
+    if VENTURES_FILE.exists():
+        try:
+            ventures = json.loads(VENTURES_FILE.read_text())
+        except Exception:
+            pass
+
+    name = info["name"]
+    if name not in ventures:
+        ventures[name] = {
+            "path": info.get("path", ""),
+            "repo": info.get("repo", ""),
+            "type": info.get("type", ""),
+            "registered_at": time.strftime("%Y-%m-%dT%H:%M:%SZ"),
+        }
+        VENTURES_FILE.write_text(json.dumps(ventures, indent=2))
+
+
+def _project_ledger_dir(project_path: str = ".") -> Path:
+    """Get the ledger directory for the current project."""
+    p = Path(project_path).resolve()
+    return p / ".delimit" / "ledger"
+
+
+def _ensure(project_path: str = "."):
+    ledger_dir = _project_ledger_dir(project_path)
+    ledger_dir.mkdir(parents=True, exist_ok=True)
+    for name in ["strategy.jsonl", "operations.jsonl"]:
+        f = ledger_dir / name
         if not f.exists():
             f.write_text("")
 
+    # Auto-register venture on first use
+    info = _detect_venture(project_path)
+    _register_venture(info)
+
 
 def _read_ledger(path: Path) -> List[Dict]:
-    _ensure()
     items = []
+    if not path.exists():
+        return items
     for line in path.read_text().splitlines():
         line = line.strip()
         if line:
@@ -41,8 +125,9 @@ def _read_ledger(path: Path) -> List[Dict]:
 
 
 def _append(path: Path, entry: Dict) -> Dict:
-    _ensure()
-    # Add hash chain
+    path.parent.mkdir(parents=True, exist_ok=True)
+    if not path.exists():
+        path.write_text("")
     items = _read_ledger(path)
     prev_hash = items[-1].get("hash", "genesis") if items else "genesis"
     entry["hash"] = hashlib.sha256(f"{prev_hash}{json.dumps(entry, sort_keys=True)}".encode()).hexdigest()[:16]
@@ -60,17 +145,19 @@ def add_item(
     priority: str = "P1",
     description: str = "",
     source: str = "session",
+    project_path: str = ".",
     tags: Optional[List[str]] = None,
 ) -> Dict[str, Any]:
-    """Add a new item to the strategy or operational ledger."""
-    path = STRATEGY_LEDGER if ledger == "strategy" else OPS_LEDGER
+    """Add a new item to the project's strategy or operational ledger."""
+    _ensure(project_path)
+    venture = _detect_venture(project_path)
+    ledger_dir = _project_ledger_dir(project_path)
+    path = ledger_dir / ("strategy.jsonl" if ledger == "strategy" else "operations.jsonl")
 
-    # Auto-generate ID
     items = _read_ledger(path)
     prefix = "STR" if ledger == "strategy" else "LED"
-    existing_ids = [i.get("id", "") for i in items]
+    existing_ids = [i.get("id", "") for i in items if i.get("type") != "update"]
     num = len(existing_ids) + 1
-    # Find next available number
     while f"{prefix}-{num:03d}" in existing_ids:
         num += 1
     item_id = f"{prefix}-{num:03d}"
@@ -82,6 +169,7 @@ def add_item(
         "priority": priority,
         "description": description,
         "source": source,
+        "venture": venture["name"],
         "status": "open",
         "tags": tags or [],
     }
@@ -90,6 +178,7 @@ def add_item(
     return {
         "added": result,
         "ledger": ledger,
+        "venture": venture["name"],
         "total_items": len(_read_ledger(path)),
     }
 
@@ -99,14 +188,17 @@ def update_item(
     status: Optional[str] = None,
     note: Optional[str] = None,
     priority: Optional[str] = None,
+    project_path: str = ".",
 ) -> Dict[str, Any]:
     """Update an existing ledger item's status, priority, or add a note."""
-    # Search both ledgers
-    for ledger_name, path in [("ops", OPS_LEDGER), ("strategy", STRATEGY_LEDGER)]:
+    _ensure(project_path)
+    ledger_dir = _project_ledger_dir(project_path)
+
+    for ledger_name, filename in [("ops", "operations.jsonl"), ("strategy", "strategy.jsonl")]:
+        path = ledger_dir / filename
         items = _read_ledger(path)
         for item in items:
-            if item.get("id") == item_id:
-                # Append an update event
+            if item.get("id") == item_id and item.get("type") != "update":
                 update = {
                     "id": item_id,
                     "type": "update",
@@ -121,7 +213,7 @@ def update_item(
                 _append(path, update)
                 return {"updated": item_id, "changes": update, "ledger": ledger_name}
 
-    return {"error": f"Item {item_id} not found in either ledger"}
+    return {"error": f"Item {item_id} not found in project ledger"}
 
 
 def list_items(
@@ -129,14 +221,19 @@ def list_items(
     status: Optional[str] = None,
     priority: Optional[str] = None,
     limit: int = 50,
+    project_path: str = ".",
 ) -> Dict[str, Any]:
     """List ledger items with optional filters."""
+    _ensure(project_path)
+    ledger_dir = _project_ledger_dir(project_path)
+    venture = _detect_venture(project_path)
     results = {}
 
-    for ledger_name, path in [("ops", OPS_LEDGER), ("strategy", STRATEGY_LEDGER)]:
+    for ledger_name, filename in [("ops", "operations.jsonl"), ("strategy", "strategy.jsonl")]:
         if ledger not in ("both", ledger_name):
             continue
 
+        path = ledger_dir / filename
         items = _read_ledger(path)
 
         # Build current state by replaying events
@@ -155,53 +252,59 @@ def list_items(
             else:
                 state[item_id] = {**item}
 
-        # Filter
         filtered = list(state.values())
         if status:
             filtered = [i for i in filtered if i.get("status") == status]
         if priority:
             filtered = [i for i in filtered if i.get("priority") == priority]
 
-        # Sort by priority then created_at
         priority_order = {"P0": 0, "P1": 1, "P2": 2, "P3": 3}
         filtered.sort(key=lambda x: (priority_order.get(x.get("priority", "P2"), 9), x.get("created_at", "")))
 
         results[ledger_name] = filtered[:limit]
 
-    # Summary
     all_items = []
     for v in results.values():
         all_items.extend(v)
 
-    open_count = sum(1 for i in all_items if i.get("status") == "open")
-    done_count = sum(1 for i in all_items if i.get("status") == "done")
-
     return {
+        "venture": venture["name"],
         "items": results,
         "summary": {
             "total": len(all_items),
-            "open": open_count,
-            "done": done_count,
+            "open": sum(1 for i in all_items if i.get("status") == "open"),
+            "done": sum(1 for i in all_items if i.get("status") == "done"),
             "in_progress": sum(1 for i in all_items if i.get("status") == "in_progress"),
         },
     }
 
 
-def get_context() -> Dict[str, Any]:
+def get_context(project_path: str = ".") -> Dict[str, Any]:
     """Get a concise ledger summary for AI context — what's open, what's next."""
-    result = list_items(status="open")
+    venture = _detect_venture(project_path)
+    result = list_items(status="open", project_path=project_path)
     open_items = []
     for ledger_items in result["items"].values():
         open_items.extend(ledger_items)
 
-    # Sort by priority
     priority_order = {"P0": 0, "P1": 1, "P2": 2, "P3": 3}
     open_items.sort(key=lambda x: priority_order.get(x.get("priority", "P2"), 9))
 
     return {
+        "venture": venture["name"],
         "open_items": len(open_items),
         "next_up": [{"id": i["id"], "title": i["title"], "priority": i["priority"]}
                      for i in open_items[:5]],
         "summary": result["summary"],
-        "tip": "Use delimit_ledger_add to add new items, delimit_ledger_done to mark complete.",
     }
+
+
+def list_ventures() -> Dict[str, Any]:
+    """List all registered ventures/projects."""
+    if not VENTURES_FILE.exists():
+        return {"ventures": {}, "count": 0}
+    try:
+        ventures = json.loads(VENTURES_FILE.read_text())
+        return {"ventures": ventures, "count": len(ventures)}
+    except Exception:
+        return {"ventures": {}, "count": 0}

package/gateway/ai/server.py

@@ -246,10 +246,22 @@ NEXT_STEPS_REGISTRY: Dict[str, List[Dict[str, Any]]] = {
 
 
 def _with_next_steps(tool_name: str, result: Dict[str, Any]) -> Dict[str, Any]:
-    """Attach next_steps metadata to a tool response (Consensus 096)."""
-    steps = NEXT_STEPS_REGISTRY.get(tool_name, [])
-    result["next_steps"] = steps
-    return result
+    """Route every tool result through governance (replaces simple next_steps).
+
+    Governance:
+    1. Checks result against rules (thresholds, policies)
+    2. Auto-creates ledger items for failures/warnings
+    3. Adds next_steps to keep the AI building
+    4. Loops back to governance via ledger_context suggestion
+    """
+    try:
+        from ai.governance import govern
+        return govern(tool_name, result)
+    except Exception:
+        # Fallback: just add next_steps from registry
+        steps = NEXT_STEPS_REGISTRY.get(tool_name, [])
+        result["next_steps"] = steps
+        return result
 
 
 # ═══════════════════════════════════════════════════════════════════════
@@ -1799,22 +1811,45 @@ def delimit_license_status() -> Dict[str, Any]:
 # ═══════════════════════════════════════════════════════════════════════
 
 
+def _resolve_venture(venture: str) -> str:
+    """Resolve a venture name or path to an actual directory path."""
+    if not venture:
+        return "."
+    # If it's already a path
+    if venture.startswith("/") or venture.startswith("~"):
+        return str(Path(venture).expanduser())
+    # Check registered ventures
+    from ai.ledger_manager import list_ventures
+    v = list_ventures()
+    for name, info in v.get("ventures", {}).items():
+        if name == venture or venture in name:
+            return info.get("path", ".")
+    # Fallback: assume it's a directory name under common roots
+    for root in ["/home/delimit", "/home/jamsons/ventures", "/home"]:
+        candidate = Path(root) / venture
+        if candidate.exists():
+            return str(candidate)
+    return "."
+
+
 @mcp.tool()
 def delimit_ledger_add(
     title: str,
+    venture: str = "",
     ledger: str = "ops",
     type: str = "task",
     priority: str = "P1",
     description: str = "",
     source: str = "session",
 ) -> Dict[str, Any]:
-    """Add a new item to the strategy or operational ledger.
+    """Add a new item to a project's ledger.
 
-    The ledger tracks what needs to be done across sessions. Use "ops" for
-    tasks/bugs/features, "strategy" for consensus decisions and direction.
+    The ledger tracks what needs to be done across sessions. Specify the venture/project
+    name or path. If empty, auto-detects from current directory.
 
     Args:
         title: What needs to be done.
+        venture: Project name or path (e.g. "delimit-gateway", "/home/delimit/delimit-gateway"). Auto-detects if empty.
         ledger: "ops" (tasks, bugs, features) or "strategy" (decisions, direction).
         type: task, fix, feat, strategy, consensus.
         priority: P0 (urgent), P1 (important), P2 (nice to have).
@@ -1822,49 +1857,70 @@ def delimit_ledger_add(
         source: Where this came from (session, consensus, focus-group, etc).
     """
     from ai.ledger_manager import add_item
+    project = _resolve_venture(venture)
     return add_item(title=title, ledger=ledger, type=type, priority=priority,
-                    description=description, source=source)
+                    description=description, source=source, project_path=project)
 
 
 @mcp.tool()
-def delimit_ledger_done(item_id: str, note: str = "") -> Dict[str, Any]:
+def delimit_ledger_done(item_id: str, note: str = "", venture: str = "") -> Dict[str, Any]:
     """Mark a ledger item as done.
 
     Args:
         item_id: The item ID (e.g. LED-001 or STR-001).
         note: Optional completion note.
+        venture: Project name or path. Auto-detects if empty.
     """
     from ai.ledger_manager import update_item
-    return update_item(item_id=item_id, status="done", note=note)
+    project = _resolve_venture(venture)
+    return update_item(item_id=item_id, status="done", note=note, project_path=project)
 
 
 @mcp.tool()
 def delimit_ledger_list(
+    venture: str = "",
     ledger: str = "both",
     status: str = "",
     priority: str = "",
     limit: int = 20,
 ) -> Dict[str, Any]:
-    """List ledger items — see what's open, done, or in progress.
+    """List ledger items for a venture/project.
 
     Args:
+        venture: Project name or path. Auto-detects if empty.
         ledger: "ops", "strategy", or "both".
         status: Filter by status — "open", "done", "in_progress", or empty for all.
         priority: Filter by priority — "P0", "P1", "P2", or empty for all.
         limit: Max items to return.
     """
     from ai.ledger_manager import list_items
-    return list_items(ledger=ledger, status=status or None, priority=priority or None, limit=limit)
+    project = _resolve_venture(venture)
+    return list_items(ledger=ledger, status=status or None, priority=priority or None, limit=limit, project_path=project)
 
 
 @mcp.tool()
-def delimit_ledger_context() -> Dict[str, Any]:
-    """Get a quick summary of what's open in the ledger — use at session start.
+def delimit_ledger_context(venture: str = "") -> Dict[str, Any]:
+    """Get a quick summary of what's open in the ledger.
 
+    Auto-detects the venture from context. Pass a venture name to check a specific project.
     Returns the top 5 open items by priority so the AI knows what to work on.
+
+    Args:
+        venture: Project name or path. Auto-detects if empty.
     """
     from ai.ledger_manager import get_context
-    return get_context()
+    project = _resolve_venture(venture) if venture else "."
+    return get_context(project_path=project)
+
+
+@mcp.tool()
+def delimit_ventures() -> Dict[str, Any]:
+    """List all registered ventures/projects that Delimit has been used with.
+
+    Ventures are auto-registered when you use any Delimit tool in a project directory.
+    """
+    from ai.ledger_manager import list_ventures
+    return list_ventures()
 
 
 # ═══════════════════════════════════════════════════════════════════════

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "delimit-cli",
-  "version": "3.5.1",
+  "version": "3.6.1",
   "description": "Stop Describing. Start Building. 77 MCP governance tools for AI coding assistants.",
   "main": "index.js",
   "bin": {

package/tests/setup-onboarding.test.js

@@ -0,0 +1,147 @@
+const { describe, it } = require('node:test');
+const assert = require('node:assert');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// Extract getClaudeMdContent by loading the setup script source
+// We test the content function and upgrade logic in isolation.
+
+function getClaudeMdContent() {
+    return `# Delimit
+
+Your AI has persistent memory, verified execution, and governance.
+
+## First time? Say one of these:
+- "check this project's health" -- see what Delimit finds
+- "add to ledger: [anything]" -- start tracking tasks
+- "what's on the ledger?" -- see what's pending
+
+## Returning? Your AI remembers:
+- Ledger items persist across sessions
+- Governance rules stay configured
+- Memory carries forward
+
+## On first session, your AI will automatically:
+1. Diagnose the environment to verify everything is connected
+2. Check the ledger for any pending items from previous sessions
+3. If no governance exists yet, suggest initializing it
+
+## Available Agents
+- /lint -- check API specs for breaking changes
+- /engineering -- build, test, refactor with governance checks
+- /governance -- full compliance audit
+
+## Need help?
+Say "delimit help" for docs on any capability.
+`;
+}
+
+describe('CLAUDE.md onboarding content', () => {
+    it('does not mention individual tool names', () => {
+        const content = getClaudeMdContent();
+        // These tool names should never appear in user-facing CLAUDE.md
+        const toolNames = [
+            'delimit_init',
+            'delimit_lint',
+            'delimit_diff',
+            'delimit_test_coverage',
+            'delimit_gov_health',
+            'delimit_repo_analyze',
+            'delimit_diagnose',
+            'delimit_ledger_context',
+        ];
+        for (const tool of toolNames) {
+            assert.ok(
+                !content.includes(tool),
+                `CLAUDE.md should not contain tool name "${tool}"`
+            );
+        }
+    });
+
+    it('contains natural language prompts for first-time users', () => {
+        const content = getClaudeMdContent();
+        assert.ok(content.includes('check this project\'s health'), 'Should have health check prompt');
+        assert.ok(content.includes('add to ledger'), 'Should have ledger add prompt');
+        assert.ok(content.includes('what\'s on the ledger'), 'Should have ledger check prompt');
+    });
+
+    it('mentions persistent memory and governance', () => {
+        const content = getClaudeMdContent();
+        assert.ok(content.includes('persistent memory'), 'Should mention persistent memory');
+        assert.ok(content.includes('governance'), 'Should mention governance');
+    });
+
+    it('includes returning user section', () => {
+        const content = getClaudeMdContent();
+        assert.ok(content.includes('Returning?'), 'Should have returning user section');
+        assert.ok(content.includes('Ledger items persist'), 'Should mention ledger persistence');
+        assert.ok(content.includes('Memory carries forward'), 'Should mention memory persistence');
+    });
+
+    it('includes automatic first-session actions', () => {
+        const content = getClaudeMdContent();
+        assert.ok(content.includes('Diagnose the environment'), 'Should mention auto-diagnose');
+        assert.ok(content.includes('Check the ledger'), 'Should mention auto-ledger check');
+        assert.ok(content.includes('suggest initializing'), 'Should mention governance init suggestion');
+    });
+
+    it('includes help instruction', () => {
+        const content = getClaudeMdContent();
+        assert.ok(content.includes('delimit help'), 'Should tell users how to get help');
+    });
+
+    it('lists agents by slash-command not tool name', () => {
+        const content = getClaudeMdContent();
+        assert.ok(content.includes('/lint'), 'Should reference /lint agent');
+        assert.ok(content.includes('/engineering'), 'Should reference /engineering agent');
+        assert.ok(content.includes('/governance'), 'Should reference /governance agent');
+    });
+});
+
+describe('CLAUDE.md upgrade detection', () => {
+    it('detects old-format CLAUDE.md with "Delimit AI Guardrails" header', () => {
+        const oldContent = '# Delimit AI Guardrails\n\nSome old content';
+        assert.ok(
+            oldContent.includes('# Delimit AI Guardrails'),
+            'Should detect old header'
+        );
+    });
+
+    it('detects old-format CLAUDE.md with tool names', () => {
+        const oldContent = 'Some content with delimit_init and delimit_lint';
+        assert.ok(
+            oldContent.includes('delimit_init') || oldContent.includes('delimit_lint'),
+            'Should detect old tool name references'
+        );
+    });
+
+    it('does not upgrade custom CLAUDE.md without Delimit markers', () => {
+        const customContent = '# My Project\n\nThis is a custom CLAUDE.md for my project.';
+        const hasOldMarkers =
+            customContent.includes('# Delimit AI Guardrails') ||
+            customContent.includes('delimit_init') ||
+            customContent.includes('delimit_lint');
+        assert.ok(!hasOldMarkers, 'Custom content should not be detected as old Delimit format');
+    });
+});
+
+describe('setup script output messaging', () => {
+    it('setup script file contains try-it-now messaging', () => {
+        const setupPath = path.join(__dirname, '..', 'bin', 'delimit-setup.js');
+        const setupContent = fs.readFileSync(setupPath, 'utf-8');
+        assert.ok(setupContent.includes('Try it now:'), 'Should have "Try it now:" prompt');
+        assert.ok(setupContent.includes('$ claude'), 'Should suggest running claude');
+        assert.ok(setupContent.includes('check this project\'s health'), 'Should suggest health check');
+    });
+
+    it('setup script does not list tool names in output', () => {
+        const setupPath = path.join(__dirname, '..', 'bin', 'delimit-setup.js');
+        const setupContent = fs.readFileSync(setupPath, 'utf-8');
+        // Check that Step 6 output area does not reference internal tool names
+        const step6Onwards = setupContent.split('// Step 6')[1];
+        assert.ok(step6Onwards, 'Should have Step 6 section');
+        assert.ok(!step6Onwards.includes('delimit_init'), 'Step 6 should not mention delimit_init');
+        assert.ok(!step6Onwards.includes('delimit_gov_health'), 'Step 6 should not mention delimit_gov_health');
+    });
+});