uv-suite 0.26.3 → 0.26.5

package/README.md

@@ -1,34 +1,70 @@
 # UV Suite
 
-Portable framework for AI-assisted software development. Works with Claude Code, Cursor, and OpenAI Codex.
+A portable layer that turns Claude Code, Cursor, or Codex into a labeled, observable, anti-slop dev environment — with named sessions, a real-time observability dashboard, anti-slop guardrails, and per-session memory across launches.
 
 ## Install
 
 ```bash
 npm install -g uv-suite
-uv install
+uvs claude pro                # auto-installs into the current project on first launch
 ```
 
 Or with npx:
 
 ```bash
-npx uv-suite install
+npx uv-suite install          # explicit install only
 ```
 
-This installs 10 agents, 10 skills, 8 hooks, 6 guardrails, and 4 personas into your project.
+> **Note:** The CLI is `uvs`, not `uv`. The name `uv` belongs to Astral's Python package manager and likely already exists on your system.
 
 ## Quick Start
 
 ```bash
-uv install                    # Install UV Suite into current project
-uv claude pro                 # Start Claude Code, Professional persona
-uv codex auto                 # Start Codex, Auto persona
-uv pro                        # Shorthand for uv claude pro
+uvs claude pro                # Claude Code, Professional persona
+uvs codex auto                # Codex, Auto persona
+uvs pro                       # Shorthand for uvs claude pro
+uvs install                   # Explicit install (also runs automatically on launch)
+uvs watch                     # Open the Watchtower observability dashboard
+uvs info                      # Show what's installed
 ```
 
-## Modes
+On every `uvs` launch, you'll be prompted to label the session:
 
-Four personas for different contexts. Pick one when you start a session.
+```
+Label this session (Enter to skip — you'll be reminded):
+  name:                     payments retry refactor
+  kind [long/outcome]:      outcome
+  purpose:                  ship retry-on-5xx for the Stripe webhook handler
+  priority [low/med/high]:  high
+```
+
+Skip any field with Enter. If you skip the name, `/session-init` will be suggested every few prompts until you label it. Set `UVS_NO_PROMPT=1` to suppress prompts entirely.
+
+## Sessions and Watchtower
+
+Each `uvs` launch generates a `UVS_SESSION_ID` and writes metadata to `.uv-suite-state/sessions/<id>.json`. This unlocks:
+
+- **Concurrent terminals don't collide.** Two `uvs` launches in the same repo run as distinct sessions with separate names, checkpoints, and dashboard rows.
+- **`uvs watch` shows them all.** The Watchtower dashboard at `localhost:4200` streams every tool call across every session in real time — labeled by your name, sorted by priority (high to top, low dimmed), color-coded by persona.
+- **Per-session checkpoints.** `/checkpoint` writes to `uv-out/checkpoints/<sid>/`, and `/restore` auto-picks the current session's latest. Pass a session id prefix or name to restore from a different one.
+- **Status line shows it all.** The Claude Code status bar shows session name, persona, priority, and elapsed time continuously.
+
+### Watchtower at a glance
+
+```
+Sessions               Events    Tool calls    Errors    Need human
+4                      1,247     914           2         0
+
+[payments retry [auto]   [P:high]  [outcome]      ] (147)
+[infra cleanup  [pro]    [P:med]   [long-running] ] (382)
+[exec deck      [spike]  [P:low]   [outcome]      ] (89)
+```
+
+Hooks fire on every Claude Code event (`PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `SessionStart`, `Stop`, `PermissionRequest`, ...) and forward to the dashboard with the session metadata merged in. Zero dependencies — vanilla Node + SSE.
+
+## Personas
+
+Four modes for different contexts. Pick one when you start a session.
 
 ```
              Spike          Sport        Professional       Auto
@@ -43,12 +79,7 @@ Writes       New files      Anything     Anything           Anything
              only                        (reviewed)         (autonomous)
 Edits        Blocked        Allowed      Allowed            Allowed
 
-Hooks        1              1            8                  3
-             doc-slop       lint         all                lint, block,
-                                                            timer
-
 Guardrails   Doc slop       None         All 6              All 6
-
 Human gates  After each     End only     Every Act          Final output
              map                         boundary           only
 ```
@@ -56,7 +87,7 @@ Human gates  After each     End only     Every Act          Final output
 ### When to use what
 
 | Situation | Mode | Why |
-|-----------|------|-----|
+|---|---|---|
 | Joining a new codebase | **Spike** | Understand before changing. Writes docs, not code. |
 | Architecture review | **Spike** | Map the system, write ADRs, document findings. |
 | Prototyping a demo | **Sport** | Move fast, iterate freely, quality comes later. |
@@ -71,121 +102,114 @@ Human gates  After each     End only     Every Act          Final output
 - Spike → Auto (research thoroughly, then let the agent execute)
 - Sport → Professional (prototype fast, switch to rigor when it matters)
 
-## What You Get
-
-| Category | Count | What |
-|----------|-------|------|
-| Agents | 10 | Subagent definitions for Claude Code, Cursor, and Codex |
-| Skills | 10 | Slash commands with dynamic context injection |
-| Hooks | 8 | Auto-lint, slop check, danger zones, session tracking, destructive blocks |
-| Guardrails | 6 | Anti-slop rules (comments, overengineering, tests, docs, architecture, errors) |
-| Personas | 4 | Spike, Sport, Professional, Auto |
-
-## Three Subsystems
-
-```
-UV Index          UV Acts           UV Guard
-Understand        Build             Review
-Learn             Deliver           Harden
-Remember          Present           Protect
-```
-
-**UV Index** maps codebases using [Graphify](https://github.com/safishamsi/graphify) knowledge graphs, captures context, builds persistent memory.
-
-**UV Acts** delivers software in sequential phases (Acts) with parallel tasks, human-in-the-loop cycle budgets, and spec-driven development.
-
-**UV Guard** catches AI slop in real time, reviews code for security (OWASP, [Semgrep](https://github.com/semgrep/semgrep)), and enforces danger zones.
-
-## Skills
+## Skills (slash commands)
 
 | Command | What it does |
-|---------|-------------|
+|---|---|
 | `/map-codebase [dir]` | Build a knowledge graph of the codebase |
 | `/map-stack [dir]` | Map multiple services and their connections |
 | `/spec [requirements]` | Write a technical specification |
 | `/architect [spec]` | Design architecture, decompose into Acts |
-| `/review` | Code review: correctness, security, performance, slop |
+| `/prototype [concept]` | Build a static React prototype |
 | `/write-tests [file]` | Generate tests matching project conventions |
 | `/write-evals [prompt]` | Write AI/LLM evaluation cases ([DeepEval](https://github.com/confident-ai/deepeval) compatible) |
+| `/review` | Code review: correctness, security, performance, slop |
 | `/slop-check` | Detect 6 categories of AI-generated slop |
-| `/prototype [concept]` | Build a static React prototype |
 | `/security-review` | OWASP audit, dependency scan, secret detection |
+| `/investigate` | Systematic root-cause debugging |
+| `/commit` | Review → test → slop-check → commit (and optionally PR) |
+| `/checkpoint [label]` | Save session state to `uv-out/checkpoints/<sid>/` |
+| `/restore [sid-prefix\|name]` | Load the latest checkpoint for the current (or named) session |
+| `/session-init [name\|--kind\|--purpose\|--priority]` | Label or relabel the current session |
+| `/confirm [on\|off\|<n>]` | Toggle reframe-and-confirm for prompts over `<n>` words |
+| `/uv-help` | List every skill, agent, hook, guardrail, and persona |
 
-## Hooks
+## Hooks (lifecycle automation)
 
-Fire automatically. You never invoke these.
+Fire automatically on Claude Code events. You never invoke these.
 
 | Hook | Fires on | What it does |
-|------|----------|-------------|
+|---|---|---|
 | auto-lint | File write | Runs prettier, ruff, or gofmt |
-| Slop check | File write | Haiku scans for obvious slop patterns |
-| Danger zone | File edit | Warns if file is in DANGER-ZONES.md |
-| Destructive block | Bash command | Blocks rm -rf, force push, DROP TABLE |
-| Session start | Session start | Records start time for duration tracking |
-| Session timer | Every 20th tool call | Checkpoint reminders at 45/90/180 min |
-| Session end | Session stop | Shows duration, today's total, reflection prompt |
-| Status line | Continuous | Shows session time in Claude Code's status bar |
+| slop-grep | File write | Greps for obvious slop patterns (over-commented code, vague docs) |
+| doc-slop-grep | File write | Catches vague adjectives in markdown |
+| danger-zone-check | File edit | Warns if file is in DANGER-ZONES.md |
+| block-destructive | Bash command | Blocks `rm -rf /`, force push to main, `DROP TABLE` |
+| confirm-prompt | UserPromptSubmit | For prompts over the threshold, requires Claude to restate before any work starts |
+| session-label-nag | UserPromptSubmit | Reminds you to run `/session-init` every Nth prompt while the session has no name |
+| context-warning | PostToolUse | Warns when context usage crosses thresholds |
+| watchtower-send | All events | Forwards every event (with session metadata) to `localhost:4200` |
+| session-start | SessionStart | Records start time, fires bootstrap event with session metadata |
+| session-timer | PostToolUse | Reminders at 45 / 90 / 180 minutes |
+| session-end | Stop | Shows duration, today's total, reflection prompt |
+| session-review-reminder | Stop | Nudges you to review uncommitted changes |
+| status-line | Continuous | Renders session label, persona, priority, and timer in the Claude Code status bar |
 
 ## Agents
 
-10 agents, each in 4 formats (Claude Code, Cursor, Codex, Portable):
+10 agents, each in 4 formats (Claude Code, Cursor, Codex, portable):
 
 | Agent | Subsystem | Model | Cycle Budget |
-|-------|-----------|-------|-------------|
-| Cartographer | UV Index | Opus | 1 |
-| Spec Writer | UV Acts | Opus | 1 |
-| Architect | UV Acts | Opus | 2 |
-| Reviewer | UV Guard | Opus | 1 |
-| Test Writer | UV Acts | Sonnet | 3 |
-| Eval Writer | UV Acts | Opus | 2 |
-| Anti-Slop Guard | UV Guard | Opus | 1 |
-| Prototype Builder | UV Acts | Sonnet | 3 |
-| DevOps | UV Acts | Opus | 2 |
-| Security | UV Guard | Opus | 1 |
+|---|---|---|---|
+| Cartographer | Index | Opus | 1 |
+| Spec Writer | Acts | Opus | 1 |
+| Architect | Acts | Opus | 2 |
+| Reviewer | Guard | Opus | 1 |
+| Test Writer | Acts | Sonnet | 3 |
+| Eval Writer | Acts | Opus | 2 |
+| Anti-Slop Guard | Guard | Opus | 1 |
+| Prototype Builder | Acts | Sonnet | 3 |
+| DevOps | Acts | Opus | 2 |
+| Security | Guard | Opus | 1 |
 
 ## Artifacts
 
 Agents write persistent output to `uv-out/`. Each agent reads prior artifacts automatically.
 
-| Agent output | Read by |
-|-------------|---------|
+| Output | Read by |
+|---|---|
 | `uv-out/map-codebase.md` | /architect, /review, /security-review |
 | `uv-out/specs/*.md` | /architect, /write-tests, /write-evals |
 | `uv-out/architecture/*.md` | /review, /write-tests, /slop-check |
 | `uv-out/review-*.md` | /slop-check, /security-review |
+| `uv-out/checkpoints/<sid>/*.md` | /restore |
 
 ## Integrations
 
 | Tool | Used by | Purpose |
-|------|---------|---------|
+|---|---|---|
 | [Graphify](https://github.com/safishamsi/graphify) | Cartographer | Knowledge graph from codebase via Tree-sitter |
-| [Semgrep](https://github.com/semgrep/semgrep) | Security Agent | SAST with 4000+ OWASP-mapped rules |
-| [Gitleaks](https://github.com/gitleaks/gitleaks) | Security Agent | Secret detection in git repos |
-| [Trivy](https://github.com/aquasecurity/trivy) | Security Agent | Dependency vulnerability scanning |
+| [Semgrep](https://github.com/semgrep/semgrep) | Security | SAST with 4000+ OWASP-mapped rules |
+| [Gitleaks](https://github.com/gitleaks/gitleaks) | Security | Secret detection in git repos |
+| [Trivy](https://github.com/aquasecurity/trivy) | Security | Dependency vulnerability scanning |
 | [DeepEval](https://github.com/confident-ai/deepeval) | Eval Writer | Pytest-compatible LLM evaluation |
-| [Playwright](https://playwright.dev/docs/getting-started-mcp) | Prototype Builder, Test Writer | Browser automation and e2e testing |
+| [Playwright](https://playwright.dev/docs/getting-started-mcp) | Prototype, Test Writer | Browser automation and e2e testing |
 
 ## Project Structure After Install
 
 ```
 .claude/
-  settings.json        Permissions, hooks (from persona)
-  agents/              10 agent definitions
-  skills/              10 slash commands
-  hooks/               7 hook scripts
-  rules/               6 anti-slop guardrails
-  personas/            4 persona configs
-.codex/agents/         10 Codex agent definitions
-.cursor/rules/         10 Cursor rule definitions
-AGENTS.md              Codex instruction file
-DANGER-ZONES.md        Risky areas (commit this)
-uv-out/                Agent output artifacts (gitignored)
+  settings.json          Permissions and hooks (seeded from your persona on first install)
+  agents/                10 agent definitions
+  skills/                17 slash commands
+  hooks/                 14 hook scripts + 2 helpers
+  rules/                 6 anti-slop guardrails (Pro / Auto only)
+  personas/              4 persona configs
+.codex/agents/           10 Codex agent definitions
+.cursor/rules/           10 Cursor rule definitions
+AGENTS.md                Codex instruction file
+DANGER-ZONES.md          Risky areas (commit this)
+.uv-suite-state/         Session metadata + counters (gitignored)
+  current-session.txt
+  sessions/<sid>.json
+uv-out/                  Agent output artifacts (gitignored)
+  checkpoints/<sid>/     Per-session checkpoints
 ```
 
 ## Documentation
 
 | Document | What it covers |
-|----------|---------------|
+|---|---|
 | [usage-guide.md](usage-guide.md) | Full SDLC mapped to exact commands |
 | [personas.md](personas.md) | 4 personas, 7 knobs, when to use each |
 | [practices.md](practices.md) | Working principles (honesty, parallelism, scope, completion) |

package/bin/cli.js

@@ -1,16 +1,18 @@
 #!/usr/bin/env node
 
-const { execSync, spawn } = require('child_process');
-const path = require('path');
-const fs = require('fs');
+const { execSync, spawn } = require("child_process");
+const path = require("path");
+const fs = require("fs");
+const crypto = require("crypto");
+const readline = require("readline");
 
-const UV_SUITE_DIR = path.resolve(__dirname, '..');
+const UV_SUITE_DIR = path.resolve(__dirname, "..");
 const args = process.argv.slice(2);
 const command = args[0];
-const pkg = require(path.join(UV_SUITE_DIR, 'package.json'));
+const pkg = require(path.join(UV_SUITE_DIR, "package.json"));
 
-const PERSONAS = ['spike', 'sport', 'pro', 'professional', 'auto'];
-const TOOLS = ['claude', 'codex'];
+const PERSONAS = ["spike", "sport", "pro", "professional", "auto"];
+const TOOLS = ["claude", "codex"];
 
 function usage() {
   console.log(`
@@ -57,208 +59,333 @@ function info() {
 }
 
 function install() {
-  const installScript = path.join(UV_SUITE_DIR, 'install.sh');
+  const installScript = path.join(UV_SUITE_DIR, "install.sh");
   if (!fs.existsSync(installScript)) {
-    console.error('Error: install.sh not found at', installScript);
+    console.error("Error: install.sh not found at", installScript);
     process.exit(1);
   }
-  const installArgs = args.slice(1).join(' ');
+  const installArgs = args.slice(1).join(" ");
   try {
-    execSync(`bash "${installScript}" ${installArgs}`, { stdio: 'inherit' });
+    execSync(`bash "${installScript}" ${installArgs}`, { stdio: "inherit" });
   } catch (e) {
     process.exit(e.status || 1);
   }
 }
 
 function normPersona(p) {
-  if (p === 'pro' || p === 'professional') return 'professional';
+  if (p === "pro" || p === "professional") return "professional";
   if (PERSONAS.includes(p)) return p;
   return null;
 }
 
 function personaLabel(p) {
   const labels = {
-    spike: 'Spike — research & docs (Opus, max)',
-    sport: 'Sport — lightweight (Sonnet, high)',
-    professional: 'Professional — full rigor (all hooks, all guardrails)',
-    auto: 'Auto — autonomous (max, everything approved)',
+    spike: "Spike — research & docs (Opus, max)",
+    sport: "Sport — lightweight (Sonnet, high)",
+    professional: "Professional — full rigor (all hooks, all guardrails)",
+    auto: "Auto — autonomous (max, everything approved)",
   };
   return labels[p] || p;
 }
 
-function ensureInstalled(persona) {
-  const hooksDir = path.resolve('.claude/hooks');
-  const personasDir = path.resolve('.claude/personas');
-  const needsInstall = !fs.existsSync(personasDir) || !fs.existsSync(hooksDir);
-
-  if (needsInstall) {
-    console.log('UV Suite not installed in this project. Installing core files...');
-    console.log('');
-
-    // Fast install: copy essential files directly (no pip, no brew, no slow stuff)
-    const srcDir = UV_SUITE_DIR;
-    const targetDir = path.resolve('.claude');
-
-    // Create directories
-    for (const dir of ['agents', 'skills', 'hooks', 'rules', 'personas']) {
-      fs.mkdirSync(path.join(targetDir, dir), { recursive: true });
-    }
+// Sync package-owned files (hooks, skills, personas, agents, optional guardrails)
+// from the installed npm package into the project's .claude/. Idempotent — runs
+// every launch so users on older versions pick up new hooks and slash commands
+// after `npm install -g uv-suite@latest` without needing `uvs install` again.
+// settings.json is preserved if it exists (user customizations).
+function syncPackageFiles(persona) {
+  const srcDir = UV_SUITE_DIR;
+  const targetDir = path.resolve(".claude");
+  const hooksDir = path.join(targetDir, "hooks");
+  const personasDir = path.join(targetDir, "personas");
+  const wasFreshInstall =
+    !fs.existsSync(personasDir) || !fs.existsSync(hooksDir);
+
+  for (const dir of ["agents", "skills", "hooks", "rules", "personas"]) {
+    fs.mkdirSync(path.join(targetDir, dir), { recursive: true });
+  }
 
-    // Copy agents
-    const agentsSrc = path.join(srcDir, 'agents', 'claude-code');
-    if (fs.existsSync(agentsSrc)) {
-      for (const f of fs.readdirSync(agentsSrc)) {
-        fs.copyFileSync(path.join(agentsSrc, f), path.join(targetDir, 'agents', f));
-      }
+  const agentsSrc = path.join(srcDir, "agents", "claude-code");
+  if (fs.existsSync(agentsSrc)) {
+    for (const f of fs.readdirSync(agentsSrc)) {
+      fs.copyFileSync(
+        path.join(agentsSrc, f),
+        path.join(targetDir, "agents", f),
+      );
     }
+  }
 
-    // Copy hooks
-    const hooksSrc = path.join(srcDir, 'hooks');
-    if (fs.existsSync(hooksSrc)) {
-      for (const f of fs.readdirSync(hooksSrc)) {
-        const dest = path.join(targetDir, 'hooks', f);
-        fs.copyFileSync(path.join(hooksSrc, f), dest);
-        fs.chmodSync(dest, 0o755);
-      }
+  const hooksSrc = path.join(srcDir, "hooks");
+  if (fs.existsSync(hooksSrc)) {
+    for (const f of fs.readdirSync(hooksSrc)) {
+      const dest = path.join(targetDir, "hooks", f);
+      fs.copyFileSync(path.join(hooksSrc, f), dest);
+      fs.chmodSync(dest, 0o755);
     }
+  }
 
-    // Copy skills
-    const skillsSrc = path.join(srcDir, 'skills');
-    if (fs.existsSync(skillsSrc)) {
-      for (const d of fs.readdirSync(skillsSrc)) {
-        const skillFile = path.join(skillsSrc, d, 'SKILL.md');
-        if (fs.existsSync(skillFile)) {
-          const destDir = path.join(targetDir, 'skills', d);
-          fs.mkdirSync(destDir, { recursive: true });
-          fs.copyFileSync(skillFile, path.join(destDir, 'SKILL.md'));
-        }
+  const skillsSrc = path.join(srcDir, "skills");
+  if (fs.existsSync(skillsSrc)) {
+    for (const d of fs.readdirSync(skillsSrc)) {
+      const skillFile = path.join(skillsSrc, d, "SKILL.md");
+      if (fs.existsSync(skillFile)) {
+        const destDir = path.join(targetDir, "skills", d);
+        fs.mkdirSync(destDir, { recursive: true });
+        fs.copyFileSync(skillFile, path.join(destDir, "SKILL.md"));
       }
     }
+  }
 
-    // Copy guardrails (for professional and auto)
-    if (persona === 'professional' || persona === 'auto') {
-      const guardSrc = path.join(srcDir, 'guardrails');
-      if (fs.existsSync(guardSrc)) {
-        for (const f of fs.readdirSync(guardSrc)) {
-          fs.copyFileSync(path.join(guardSrc, f), path.join(targetDir, 'rules', f));
-        }
+  if (persona === "professional" || persona === "auto") {
+    const guardSrc = path.join(srcDir, "guardrails");
+    if (fs.existsSync(guardSrc)) {
+      for (const f of fs.readdirSync(guardSrc)) {
+        fs.copyFileSync(
+          path.join(guardSrc, f),
+          path.join(targetDir, "rules", f),
+        );
       }
     }
+  }
 
-    // Copy personas
-    const personasSrc = path.join(srcDir, 'personas');
-    if (fs.existsSync(personasSrc)) {
-      for (const f of fs.readdirSync(personasSrc)) {
-        fs.copyFileSync(path.join(personasSrc, f), path.join(targetDir, 'personas', f));
-      }
+  const personasSrc = path.join(srcDir, "personas");
+  if (fs.existsSync(personasSrc)) {
+    for (const f of fs.readdirSync(personasSrc)) {
+      fs.copyFileSync(
+        path.join(personasSrc, f),
+        path.join(targetDir, "personas", f),
+      );
     }
+  }
 
-    // Set settings.json from persona
-    const personaFile = path.join(targetDir, 'personas', `${persona}.json`);
-    const settingsFile = path.join(targetDir, 'settings.json');
-    if (fs.existsSync(personaFile) && !fs.existsSync(settingsFile)) {
-      fs.copyFileSync(personaFile, settingsFile);
-    }
+  // settings.json is user-owned. Only seed it on fresh install.
+  const personaFile = path.join(targetDir, "personas", `${persona}.json`);
+  const settingsFile = path.join(targetDir, "settings.json");
+  if (
+    wasFreshInstall &&
+    fs.existsSync(personaFile) &&
+    !fs.existsSync(settingsFile)
+  ) {
+    fs.copyFileSync(personaFile, settingsFile);
+  }
 
+  if (wasFreshInstall) {
+    console.log(
+      "UV Suite not installed in this project. Installing core files...",
+    );
     console.log(`  Installed: agents, skills, hooks, guardrails, personas`);
-    console.log('');
+    console.log("");
+  }
+}
+
+function prompt(rl, question) {
+  return new Promise((resolve) => rl.question(question, resolve));
+}
+
+function normalizeKind(s) {
+  const v = (s || "").toLowerCase().trim();
+  if (["l", "long", "long-running"].includes(v)) return "long-running";
+  if (["o", "outcome"].includes(v)) return "outcome";
+  return "";
+}
+
+function normalizePriority(s) {
+  const v = (s || "").toLowerCase().trim();
+  if (["l", "low"].includes(v)) return "low";
+  if (["m", "med", "medium"].includes(v)) return "med";
+  if (["h", "high"].includes(v)) return "high";
+  return "";
+}
+
+// Generate a UVS_SESSION_ID, prompt for metadata (name/kind/purpose/priority),
+// write it to .uv-suite-state/sessions/<sid>.json, and return the id + name.
+// Skipping (Enter) leaves a field empty; the session-label-nag.sh hook will
+// remind the user to run /session-init mid-flight.
+async function setupSession(persona) {
+  const projectDir = process.cwd();
+  const stateDir = path.join(projectDir, ".uv-suite-state");
+  const sessionsDir = path.join(stateDir, "sessions");
+  fs.mkdirSync(sessionsDir, { recursive: true });
+
+  const sid = crypto.randomUUID();
+  let name = "";
+  let kind = "";
+  let purpose = "";
+  let priority = "";
+
+  if (process.stdin.isTTY && !process.env.UVS_NO_PROMPT) {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+    console.log("");
+    console.log("Label this session (Enter to skip — you'll be reminded):");
+    name = (await prompt(rl, "  name:                     ")).trim();
+    const kindRaw = await prompt(rl, "  kind [long/outcome]:      ");
+    purpose = (await prompt(rl, "  purpose:                  ")).trim();
+    const priorityRaw = await prompt(rl, "  priority [low/med/high]:  ");
+    rl.close();
+    kind = normalizeKind(kindRaw);
+    priority = normalizePriority(priorityRaw);
   }
+
+  const meta = {
+    uvs_session_id: sid,
+    name,
+    kind,
+    purpose,
+    priority,
+    persona,
+    cwd: projectDir,
+    started_at: Math.floor(Date.now() / 1000),
+  };
+  fs.writeFileSync(
+    path.join(sessionsDir, `${sid}.json`),
+    JSON.stringify(meta, null, 2),
+  );
+  fs.writeFileSync(path.join(stateDir, "current-session.txt"), sid);
+
+  return { sid, name };
+}
+
+// Backwards-compat shim — older code in this file still references this name.
+function ensureInstalled(persona) {
+  syncPackageFiles(persona);
 }
 
-function launchClaude(persona, extra) {
-  ensureInstalled(persona);
-  const settings = path.resolve('.claude/personas', `${persona}.json`);
+async function launchClaude(persona, extra) {
+  syncPackageFiles(persona);
+  const settings = path.resolve(".claude/personas", `${persona}.json`);
   if (!fs.existsSync(settings)) {
-    console.error(`Error: installation failed. Run 'uvs install --persona ${persona}' manually.`);
+    console.error(
+      `Error: installation failed. Run 'uvs install --persona ${persona}' manually.`,
+    );
     process.exit(1);
   }
+  const { sid, name } = await setupSession(persona);
+  console.log("");
   console.log(`UV Suite | Claude Code | ${personaLabel(persona)}`);
-  console.log('');
-  const child = spawn('claude', ['--settings', settings, ...extra], { stdio: 'inherit' });
-  child.on('exit', (code) => process.exit(code || 0));
+  console.log(`Session: ${sid.slice(0, 8)}${name ? " — " + name : ""}`);
+  console.log("");
+  const child = spawn("claude", ["--settings", settings, ...extra], {
+    stdio: "inherit",
+    env: { ...process.env, UVS_SESSION_ID: sid },
+  });
+  child.on("exit", (code) => process.exit(code || 0));
 }
 
-function launchCodex(persona, extra) {
+async function launchCodex(persona, extra) {
   const approvalMap = {
-    spike: ['--model', 'o3', '--approval-mode', 'suggest'],
-    sport: ['--approval-mode', 'auto-edit'],
-    professional: ['--approval-mode', 'suggest'],
-    auto: ['--approval-mode', 'full-auto'],
+    spike: ["--model", "o3", "--approval-mode", "suggest"],
+    sport: ["--approval-mode", "auto-edit"],
+    professional: ["--approval-mode", "suggest"],
+    auto: ["--approval-mode", "full-auto"],
   };
-  const codexArgs = approvalMap[persona] || ['--approval-mode', 'suggest'];
+  const codexArgs = approvalMap[persona] || ["--approval-mode", "suggest"];
+  const { sid, name } = await setupSession(persona);
+  console.log("");
   console.log(`UV Suite | Codex | ${personaLabel(persona)}`);
-  console.log('');
-  const child = spawn('codex', [...codexArgs, ...extra], { stdio: 'inherit' });
-  child.on('exit', (code) => process.exit(code || 0));
+  console.log(`Session: ${sid.slice(0, 8)}${name ? " — " + name : ""}`);
+  console.log("");
+  const child = spawn("codex", [...codexArgs, ...extra], {
+    stdio: "inherit",
+    env: { ...process.env, UVS_SESSION_ID: sid },
+  });
+  child.on("exit", (code) => process.exit(code || 0));
 }
 
 function watch() {
-  const serverScript = path.join(UV_SUITE_DIR, 'watchtower', 'server.js');
+  const serverScript = path.join(UV_SUITE_DIR, "watchtower", "server.js");
   if (!fs.existsSync(serverScript)) {
-    console.error('Error: watchtower server not found at', serverScript);
+    console.error("Error: watchtower server not found at", serverScript);
     process.exit(1);
   }
 
-  const bg = args.includes('--bg') || args.includes('--background');
-  console.log('UV Suite Watchtower starting...');
-  console.log('Dashboard: http://localhost:' + (process.env.UVS_WATCHTOWER_PORT || 4200));
-  console.log('');
+  const bg = args.includes("--bg") || args.includes("--background");
+  console.log("UV Suite Watchtower starting...");
+  console.log(
+    "Dashboard: http://localhost:" + (process.env.UVS_WATCHTOWER_PORT || 4200),
+  );
+  console.log("");
 
   if (bg) {
-    const child = spawn('node', [serverScript], {
-      stdio: 'ignore',
+    const child = spawn("node", [serverScript], {
+      stdio: "ignore",
       detached: true,
     });
     child.unref();
     console.log(`Running in background (PID: ${child.pid})`);
-    console.log('Stop with: kill ' + child.pid);
+    console.log("Stop with: kill " + child.pid);
 
     // Open browser
-    const opener = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
-    spawn(opener, ['http://localhost:' + (process.env.UVS_WATCHTOWER_PORT || 4200)], { stdio: 'ignore' });
+    const opener =
+      process.platform === "darwin"
+        ? "open"
+        : process.platform === "win32"
+          ? "start"
+          : "xdg-open";
+    spawn(
+      opener,
+      ["http://localhost:" + (process.env.UVS_WATCHTOWER_PORT || 4200)],
+      { stdio: "ignore" },
+    );
   } else {
     // Foreground — open browser after a short delay
     setTimeout(() => {
-      const opener = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
-      spawn(opener, ['http://localhost:' + (process.env.UVS_WATCHTOWER_PORT || 4200)], { stdio: 'ignore' });
+      const opener =
+        process.platform === "darwin"
+          ? "open"
+          : process.platform === "win32"
+            ? "start"
+            : "xdg-open";
+      spawn(
+        opener,
+        ["http://localhost:" + (process.env.UVS_WATCHTOWER_PORT || 4200)],
+        { stdio: "ignore" },
+      );
     }, 1000);
 
-    const child = spawn('node', [serverScript], { stdio: 'inherit' });
-    child.on('exit', (code) => process.exit(code || 0));
+    const child = spawn("node", [serverScript], { stdio: "inherit" });
+    child.on("exit", (code) => process.exit(code || 0));
   }
 }
 
 // --- Parse and route ---
 
-if (!command || command === '--help' || command === '-h') {
+if (!command || command === "--help" || command === "-h") {
   usage();
   process.exit(0);
 }
 
-if (command === 'watch') {
-  watch();
-} else if (command === 'install') {
-  install();
-} else if (command === 'info') {
-  info();
-} else if (TOOLS.includes(command)) {
-  // uv claude pro, uv codex auto
-  const persona = normPersona(args[1] || 'pro');
-  if (!persona) {
-    console.error(`Unknown persona: ${args[1]}`);
-    console.error('Available: spike, sport, pro, auto');
+(async () => {
+  if (command === "watch") {
+    watch();
+  } else if (command === "install") {
+    install();
+  } else if (command === "info") {
+    info();
+  } else if (TOOLS.includes(command)) {
+    // uvs claude pro, uvs codex auto
+    const persona = normPersona(args[1] || "pro");
+    if (!persona) {
+      console.error(`Unknown persona: ${args[1]}`);
+      console.error("Available: spike, sport, pro, auto");
+      process.exit(1);
+    }
+    const extra = args.slice(2);
+    if (command === "claude") await launchClaude(persona, extra);
+    else await launchCodex(persona, extra);
+  } else if (normPersona(command)) {
+    // uvs pro (shorthand for uvs claude pro)
+    const persona = normPersona(command);
+    const extra = args.slice(1);
+    await launchClaude(persona, extra);
+  } else {
+    console.error(`Unknown command: ${command}`);
+    usage();
     process.exit(1);
   }
-  const extra = args.slice(2);
-  if (command === 'claude') launchClaude(persona, extra);
-  else launchCodex(persona, extra);
-} else if (normPersona(command)) {
-  // uv pro (shorthand for uv claude pro)
-  const persona = normPersona(command);
-  const extra = args.slice(1);
-  launchClaude(persona, extra);
-} else {
-  console.error(`Unknown command: ${command}`);
-  usage();
+})().catch((err) => {
+  console.error(err);
   process.exit(1);
-}
+});

package/hooks/confirm-prompt.sh

@@ -40,8 +40,19 @@ WORDS=$(echo "$PROMPT" | wc -w | tr -d ' ')
 [ "$WORDS" -le "$THRESHOLD" ] && exit 0
 
 # Emit Claude Code hook output. additionalContext is appended to the system
-# context for this turn. Keep it terse — long instructions get tuned out.
-ADDITIONAL=$(printf '[uv-suite confirm-mode] The user prompt is %s words (threshold %s). Before doing any work or making tool calls, restate what you understood in 1-2 plain sentences and ask the user to confirm. Only proceed once they confirm. The user can disable this with /confirm off or change the threshold with /confirm <number>.' "$WORDS" "$THRESHOLD")
+# context for this turn. The instructions below shape the *style* of the
+# confirmation, not just whether one happens — the response should set
+# context, break the ask into bullets, and end with an explicit invitation
+# for the user to redirect before any work starts.
+ADDITIONAL=$(printf '[uv-suite confirm-mode] The user prompt is %s words (threshold %s). Before any work or tool calls, write a confirmation in this exact shape:
+
+1. Open with one short sentence that restates the goal in your own words — set the frame for what you think the user is asking for.
+2. Then a bulleted breakdown (3-7 bullets, one line each) covering: concrete deliverables, the key decisions or assumptions you intend to make, and any open questions or scope choices the user might want to redirect.
+3. End with a single explicit prompt: "Want me to change anything before I start, or should I go ahead?"
+
+Do not propose implementation steps, write code, or call tools yet. The point is to confirm understanding so the user can correct course cheaply. Only proceed once the user confirms.
+
+The user can disable this with /confirm off or change the threshold with /confirm <number>.' "$WORDS" "$THRESHOLD")
 
 if command -v jq >/dev/null 2>&1; then
   jq -nc --arg ctx "$ADDITIONAL" '{hookSpecificOutput:{hookEventName:"UserPromptSubmit",additionalContext:$ctx}}'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uv-suite",
-  "version": "0.26.3",
+  "version": "0.26.5",
   "description": "Portable framework for AI-assisted software development. 10 agents, 9 skills, 5 hooks, 4 personas. Works with Claude Code, Cursor, and Codex.",
   "author": "Utsav Anand",
   "license": "MIT",