viepilot 2.50.1 → 3.7.2

package/CHANGELOG.md

@@ -7,6 +7,210 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+---
+
+## [3.7.2] - 2026-05-23
+
+### Added — ENH-097: vp-auto Full Orchestrator Delegation (Phase 142)
+- **agents/claude-code/vp-git-agent.md** — new agent for phase-level git ops: create-tag, push-branch, push-tags, push-all, git-status; orchestrator spawns instead of running git inline
+- **agents/claude-code/tracker-agent.md** — new ops: `update-handoff` (HANDOFF.json patch), `update-roadmap-phase` (ROADMAP.md phase status update); Write tool added
+
+### Changed — ENH-097
+- **workflows/autonomous.md** — ENH-096 whitelist tightened: orchestrator Bash = read-only git checks only; all state writes and git ops now go through tracker-agent / vp-git-agent / changelog-agent
+- **workflows/autonomous.md** — §4 Update State: full tracker-agent spawn patterns for task-status, handoff, roadmap sync
+- **workflows/autonomous.md** — §5 Phase Complete: git tagging and push delegated to vp-git-agent; TRACKER.md sync to tracker-agent
+
+---
+
+## [3.7.1] - 2026-05-23
+
+### Changed — ENH-096: vp-auto Orchestrator Enforcement (Phase 141)
+- **workflows/autonomous.md** — ⛔ hard stop block: explicit prohibition on inline implementation in orchestrator context; lists forbidden ops (Edit/Write on lib/bin/tests/agents/skills); enforces delegation even for single-task phases
+- **workflows/autonomous.md** — orchestrator-only whitelist: Read (state files), Bash (git/vp-tools), Agent (spawn workers), Edit/Write (.viepilot/ state only)
+- **workflows/autonomous.md** — concrete `Agent(vp-task-executor)` spawn template with exact prompt text and all placeholder fields ({task_path}, {phase_dir}, {cwd}, {projectPrefix})
+
+---
+
+## [3.7.0] - 2026-05-23
+
+### Added — ENH-095: AI-Driven Intake Intelligence — Manifest + Post-task Write-back (Phase 140)
+- **lib/intake/manifest.cjs** — new manifest module: `saveManifest`, `loadManifest`, `isManifestFresh` (TTL-based), `getColumnMap`, `getWriteBackConfig`, `manifestPath`, `slugify`; manifest stored at `.viepilot/intake/{channel_id}-manifest.json`
+- **agents/claude-code/excel-intake-agent.md** — new `Op: analyze_structure` section: AI reads all sheets, determines purpose/header rows/column semantics/write_back config, outputs structured JSON manifest; no hardcoded IDs
+- **agents/claude-code/sheets-intake-agent.md** — matching `Op: analyze_structure` parity section
+- **skills/vp-intake/SKILL.md** — manifest lifecycle workflow (check TTL → `--analyze` op → save manifest → use `getColumnMap`); new `## Intake Source` block embedded in accepted-ticket request files for post-task traceability
+- **lib/intake/writeback.cjs** — new `writebackIntakeResponse(channel, sourceRow, response, projectRoot, sheetName, responseCol)`: writes status back to source row after PASS; `sharing_url` = read-only skip; `workbook_id` = Graph API PATCH; CSV/browser = silent skip
+- **workflows/autonomous.md** — Post-PASS Intake Write-back hook (ENH-095): reads `## Intake Source` block from task.md, loads manifest, calls `writebackIntakeResponse`; non-fatal on failure
+
+---
+
+## [3.6.2] - 2026-05-23
+
+### Fixed
+- **BUG-030** `lib/intake/adapters/excel-m365.cjs` — `parseRowsWithColumnMap` now handles missing `column_map` gracefully: auto-detects columns from header row using Vietnamese/English aliases (`HEADER_ALIASES`), warns to stderr with detected mapping, falls back to empty map instead of crashing with `TypeError`
+- **BUG-030** Export `autoDetectColumnMap` + `HEADER_ALIASES` for testing and external use
+- **ENH-094** `lib/intake/adapters/browser.cjs` — add `sharepoint-xlsx` pattern (`/sharepoint\.com\/:[a-z]:\/r\//`) to `URL_PATTERNS`; SharePoint xlsx sharing URLs now detected correctly instead of falling through as `generic-table`
+- **ENH-094** `skills/vp-intake/SKILL.md` — browser channel dispatch now routes `sharepoint-xlsx` URLs to `excel-intake-agent` (sharing_url mode) instead of `browser-intake-agent`
+
+---
+
+## [3.6.0] - 2026-05-23
+
+### Added
+- **ENH-090** `browser-intake-agent` (agents/claude-code/) — reads publicly shared URLs (Google Sheets, GitHub Issues, Jira, Trello, Notion) for vp-intake via `vercel-labs/agent-browser`
+- **ENH-090** `lib/intake/adapters/browser.cjs` — URL type detector + browser channel dispatcher; supports google-sheets / github-issues / jira / trello / notion / generic
+- **ENH-090** `skills/vp-intake/SKILL.md` — new `browser` channel type with `url` field; fallback chain: agent-browser → WebFetch → manual
+- **ENH-091** `browser-audit-agent` (agents/claude-code/) — visual + functional dev server audit ops: audit_routes, visual_check, accessibility_check
+- **ENH-091** `lib/audit/browser-runner.cjs` — browser audit orchestrator; writes `.viepilot/audit/visual-report-{timestamp}.md`; baseline save/compare
+- **ENH-091** `skills/vp-audit/SKILL.md` — `--visual` / `--browser <url>` flags for runtime browser audit
+- **ENH-092** `agents/claude-code/research-agent.md` upgraded — new ops: `browse_url`, `compare_products`, `extract_pricing` for JS-rendered competitor/doc research
+- **ENH-092** `workflows/brainstorm.md` Step 3 — URL research block: dispatch research-agent with browse_url when reference URL provided
+- **ENH-093** `lib/request/url-enricher.cjs` — URL auto-enricher; routes GitHub/Linear/Jira/Trello/Notion URLs to browser-intake-agent for pre-fill extraction
+- **ENH-093** `workflows/request.md` — URL detection pre-step before Step 1; shows extracted fields with confirm/edit prompt
+- **ENH-093** `skills/vp-request/SKILL.md` — URL auto-enrichment documentation with examples for all 5 tracker sources
+
+---
+
+## [3.5.0] - 2026-05-23
+
+### Added — ENH-088: `--schedule`/`--unschedule` flags + `--auto` headless intake mode (Phase 138)
+### Added — lib/intake/auto-intake.cjs: `runAutoIntake`, `createSchedule`, `deleteSchedule`, `appendPendingReview`
+### Added — vp-intake SKILL.md: pending-review queue check at manual run start
+### Changed — lib/intake/classifier.cjs: returns `{ classified, confidence: 0.0–1.0 }` (was plain string)
+
+---
+
+## [3.4.0] - 2026-05-23
+
+### Added — ENH-087: parallel codebase validation (Step 4.5) before triage in vp-intake (Phase 137)
+### Added — lib/intake/validator.cjs: `validateTickets`, `extractKeywords`, `validateTicket` (fan-out + duplicate detection)
+### Changed — triage-ux.cjs: `_validation` badge shown per ticket in AUQ display
+
+---
+
+## [3.3.0] - 2026-05-23
+
+### Added — ENH-089: `excel-intake-agent` + `sheets-intake-agent` native CC agents (Phase 136)
+### Fixed — BUG-029: Excel M365 write-back stub replaced with Graph API PATCH implementation
+### Changed — vp-intake SKILL.md: Excel/Sheets dispatch via native agents on CC adapter (Step 4 + Step 6)
+
+---
+
+## [3.2.0] - 2026-05-22
+
+### Added — ENH-086: 6 workflow agents promoted to native Claude Code agents (Phase 135)
+- `agents/claude-code/changelog-agent.md`, `tracker-agent.md`, `research-agent.md`,
+  `file-scanner-agent.md`, `test-generator-agent.md`, `doc-sync-agent.md` — all 6 now
+  installed to `~/.claude/agents/` and visible in Claude Code's `/agents` dialog
+- `research-agent` uses `claude-sonnet-4-6`; other 5 use `claude-haiku-4-5`
+- 11 new tests: `tests/unit/phase135-enh086-native-agents.test.js`
+
+### Fixed — BUG-028: test-generator-agent + file-scanner-agent wired (Phase 135)
+- `workflows/autonomous.md`: `test-generator-agent` invocation block added before
+  git-persistence gate, triggered on last task of phase when `## Acceptance Criteria` present
+- `skills/vp-audit/SKILL.md`: Tier 1 + Tier 2 scan steps invoke `file-scanner-agent`
+  (subagent_type) for repo-wide Glob+Grep; non-Claude-Code fallback retained
+
+### Changed
+- `workflows/autonomous.md`: tracker-agent, changelog-agent, doc-sync-agent invocations
+  use `subagent_type: "X-agent"` directly (no prompt-injection "Load agents/X.md" preamble)
+- `workflows/request.md`: research-agent feasibility gate uses `subagent_type: "research-agent"`
+- `docs/dev/agents.md`: architecture diagram updated to show all 9 native agents in
+  `~/.claude/agents/`; adapter table updated; invocation pattern updated
+
+### Fixed — BUG-027 tracking (Phase 135)
+- TRACKER.md and ROADMAP.md updated to reflect BUG-027 as done (code fix shipped in v3.1.1)
+
+---
+
+## [3.1.1] - 2026-05-22
+
+### Fixed — BUG-027: claudeAgentsDir wired into install plan (Phase 134)
+- `lib/viepilot-install.cjs`: `buildInstallPlan` now reads `adapter.claudeAgentsSrc` +
+  `adapter.claudeAgentsDir` and adds copy steps for each `.md` in `agents/claude-code/`
+  to `~/.claude/agents/` (native Claude Code agents directory)
+- After install: `~/.claude/agents/vp-task-executor.md`, `vp-phase-planner.md`,
+  `vp-quality-gate.md` are present and the fan-out orchestration in `autonomous.md` works
+- 5 new tests: `tests/unit/phase134-bug027-claude-agents-install.test.js`
+
+---
+
+## [3.1.0] - 2026-05-22
+
+### v3.1.0 — vp-auto Orchestration Refactor (FEAT-021 Phase 133)
+
+#### Phase 133 — vp-auto Orchestration Refactor ✅
+- `autonomous.md`: orchestration mode selection — `ADAPTER_PARALLEL` flag gates fan-out vs sequential
+- `autonomous.md`: dependency resolution via `vp-phase-planner` agent → `clusters` JSON (can_parallel, sequential_fallback)
+- `autonomous.md`: fan-out dispatch — parallel `Agent(vp-task-executor)` calls per cluster; simultaneous execution
+- `autonomous.md`: model tiering — Haiku workers for routine file edits, Sonnet for planner + quality gate
+- `autonomous.md`: Agent Teams mode for large phases (task count ≥ 8 + `orchestration.teams == true`)
+- `autonomous.md`: sequential fallback for Cursor/Antigravity/Codex/Copilot (`orchestration.parallel == false`)
+- `autonomous.md`: quality gate after each cluster via `Agent(vp-quality-gate)` — PASS/FAIL/PARTIAL routing
+- 13 new tests: `tests/unit/phase133-feat021-vp-auto-orchestration.test.js`
+
+---
+
+## [3.0.0] - 2026-05-22
+
+### v3.0.0 — Per-Adapter Intelligence Refactor (FEAT-021)
+
+**Milestone**: v3.0 — Phases 127–132 → v3.0.0, Phase 133 → v3.1.0
+**Breaking changes**: `cursor_skill_adapter` removed from all SKILL.md; new `<adapter id="...">` 5-block standard
+
+#### Phase 127 — Adapter Detection + ADAPTER_CONTEXT + Validate ✅
+- `vp-tools detect-adapter`: heuristic adapter detection at session start (env vars + process parent)
+- `lib/adapter-context.cjs`: ADAPTER_CONTEXT schema with tools{}, interactive, subagent, orchestration{} per adapter (5 adapters)
+- `vp-tools validate --adapter <id>`: checks tool availability, warns on limitations
+- ADAPTER_CONTEXT injection at session start in autonomous.md
+
+#### Phase 128 — SKILL.md 5-Block Adapter Standard ✅
+- Replace `<cursor_skill_adapter>` with `<adapter id="claude-code|cursor-agent|antigravity|codex|copilot">` in all 21 SKILL.md files
+- Claude Code now has correct tool names: `Bash` (not Shell), `Read` (not ReadFile), `Grep` (not rg), `Edit`/`Write` (not ApplyPatch), `Agent` (not Subagent)
+- Documented in `docs/dev/adapter-blocks.md`
+
+#### Phase 129 — Workflow Adapter-Aware Execution Paths ✅
+- All 4 core workflows (autonomous, brainstorm, crystallize, design) read ADAPTER_CONTEXT
+- Unified fallback chains: AUQ → text list → defaults (interactive); Bash/run_terminal_cmd/shell/container.exec (shell)
+- No more per-workflow inline compat tables
+
+#### Phase 130 — Claude Code Agent Definitions + Hooks ✅
+- `.claude/agents/vp-task-executor.md`: Haiku model worker (Read/Edit/Write/Bash/Glob/Grep, maxTurns=30)
+- `.claude/agents/vp-phase-planner.md`: Sonnet dependency resolver
+- `.claude/agents/vp-quality-gate.md`: Sonnet test runner + output checker
+- PreToolUse/PostToolUse hooks as workflow gates via `vp-tools hooks install --adapter claude-code`
+
+#### Phase 131 — Antigravity Path Fix + Deprecation Notice ✅
+- Antigravity adapter adds `projectSkillsDir: '.agents/skills'` for project-level skill installs alongside global `~/.gemini/antigravity/skills/`
+- `vp-tools install --target antigravity` shows Gemini CLI deprecation notice (Gemini CLI deprecated June 18, 2026; successor: Antigravity CLI)
+- `isAvailable()` now also detects `.agents/` directory in cwd for project-scoped setups
+- Deprecation notice links to both project (`.agents/skills/`) and global (`~/.gemini/antigravity/skills/`) skill paths
+- 8 new tests: `tests/unit/phase131-feat021-antigravity-path-fix.test.js`
+
+#### Phase 132 — Tests + CHANGELOG + v3.0.0 Bump ✅
+- 25 new integration + contract tests covering: ADAPTER_CONTEXT completeness, adapter tool mappings, 5-block standard across all SKILL.md, workflow adapter-aware paths, claude-code agent definitions, antigravity Phase 131 additions
+- `tests/unit/phase132-feat021-integration.test.js`: 13 integration tests (adapter detection, ADAPTER_CONTEXT schema, detect-adapter --json, validate --adapter)
+- `tests/unit/phase132-feat021-contracts.test.js`: 12 contract tests (5-block standard, workflow adapter refs, adapter property contracts)
+- Version bump: 2.51.0 → 3.0.0; CHANGELOG [3.0.0] finalized
+
+#### Phase 133 — vp-auto Orchestration Refactor (planned → v3.1.0)
+- autonomous.md: task dependency graph + runnable cluster identification
+- Fan-out dispatch: parallel `Agent` tool calls for independent tasks within a cluster
+- Agent Teams mode for large homogeneous phases (task count ≥8 + ADAPTER_CONTEXT.orchestration.teams)
+- Model tiering: Haiku workers for routine file edits, Sonnet for orchestrator + quality gate
+- Adapter fallback: sequential mode when `orchestration.parallel == false` (Cursor/Copilot/Antigravity/Codex)
+- Target: ≥60% token reduction vs. single-agent for typical 7-task phase
+
+## [2.51.0] - 2026-05-22
+
+### Added — ENH-085: Mobile UI Direction Breakdown Quality (Phase 126)
+- `design.md` schema: `screens` breakpoints (mobile/tablet/desktop/wide) + `strategy` field + `## Responsive Components` table; `--sync` maps screens → Tailwind `theme.extend.screens`
+- Brainstorm: **Mobile Design Direction sub-phase** — AUQ 1 (viewport strategy: mobile-first/desktop-first/mobile-only/desktop-only) + AUQ 2 multi-select device scope (phone/tablet/desktop/wide), fires when mobile/responsive/breakpoint/viewport/touch keywords detected
+- Brainstorm: Per-breakpoint `<details>` sections in `pages/*.html` — Phone/Tablet/Desktop layout + navigation strategy (lookup table by page type), CSS block for `.responsive-breakdown`
+- Brainstorm: **Component Responsive Map** table auto-generated in `notes.md` (≥7 rows: Nav/Grid/Table/Modal/Forms/Buttons/Images + Navigation Pattern Detail + Tailwind utility reference); guard against duplicate generation
+- Sub-scan A (crystallize): Extracts `theme.screens` / `theme.extend.screens` from `tailwind.config.js` (fallback to Tailwind defaults); scans JSX/TSX/Vue/Svelte for `sm:/md:/lg:/xl:/2xl:` patterns; infers mobile-first vs. desktop-first strategy; emits RESPONSIVE SUMMARY block
+- Crystallize: **Step 1A-iv** — consumes responsive metadata from 4 sources (notes.md Component Responsive Map, session context, pages/*.html breakpoint sections, Sub-scan A); emits `## Responsive Implementation Notes` in ARCHITECTURE.md with per-page responsive target table and high-priority component list
+- 27 tests in `tests/unit/phase126-enh085-mobile-ui-direction.test.js`
+
 ## [2.50.1] - 2026-05-17
 
 ### Fixed

package/README.md

@@ -2,7 +2,7 @@
 
 **Autonomous Vibe Coding Framework / Bộ khung phát triển tự động có kiểm soát**
 
-[![Version](https://img.shields.io/badge/version-2.31.0-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-3.1.1-blue.svg)](CHANGELOG.md)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
 [![Skills](https://img.shields.io/badge/skills-18-purple.svg)](#skills-reference)
 [![Workflows](https://img.shields.io/badge/workflows-13-orange.svg)](#workflows)

package/bin/viepilot.cjs

@@ -383,6 +383,7 @@ async function installCommand(rawArgs) {
     const a = adapterMap[target];
     if (a && !seenAdapters.has(a.id)) {
       seenAdapters.add(a.id);
+      if (a.deprecationNotice) console.log(`\n${a.deprecationNotice}`);
       console.log(`- ${a.name}: ${a.postInstallHint || 'run /vp-status'}`);
     }
   }

package/bin/vp-tools.cjs

@@ -1303,6 +1303,126 @@ ${colors.cyan}Examples:${colors.reset}
     console.log('\nEdit .viepilot/intake/channels.json to configure your ticket channels.');
   },
 
+  /**
+   * Detect active adapter from environment heuristics (FEAT-021 Phase 127)
+   * Usage: vp-tools detect-adapter [--json]
+   */
+  'detect-adapter': (args) => {
+    const { detectAdapter, getAdapterContext } = require('../lib/adapter-context.cjs');
+    const jsonMode = args.includes('--json');
+    const adapterId = detectAdapter();
+    const ctx = getAdapterContext(adapterId);
+
+    if (jsonMode) {
+      const output = {
+        adapter: adapterId,
+        name: ctx.name,
+        interactive_mode: ctx.interactive,
+        subagent: ctx.subagent,
+        orchestration: ctx.orchestration,
+        hooks_count: ctx.hooks.count,
+        mcp: ctx.mcp,
+        capabilities: Object.entries(ctx.tools)
+          .filter(([, v]) => v !== null)
+          .map(([k]) => k),
+      };
+      console.log(JSON.stringify(output, null, 2));
+      return;
+    }
+
+    console.log(`\n${colors.bold}Active Adapter:${colors.reset} ${ctx.name} (${adapterId})`);
+    console.log(`\n${colors.cyan}Interactive:${colors.reset}    ${ctx.interactive}`);
+    console.log(`${colors.cyan}Subagent:${colors.reset}       ${ctx.subagent}`);
+    console.log(`${colors.cyan}Parallel exec:${colors.reset}  ${ctx.orchestration.parallel}`);
+    console.log(`${colors.cyan}Agent Teams:${colors.reset}    ${ctx.orchestration.teams}`);
+    console.log(`${colors.cyan}Hooks:${colors.reset}          ${ctx.hooks.count} events`);
+    console.log(`${colors.cyan}MCP limit:${colors.reset}      ${ctx.mcp.tool_limit !== null ? ctx.mcp.tool_limit + ' tools' : 'none'}`);
+    console.log(`\n${colors.cyan}Tool names:${colors.reset}`);
+    Object.entries(ctx.tools)
+      .filter(([, v]) => v !== null)
+      .forEach(([k, v]) => console.log(`  ${k.padEnd(14)} → ${v}`));
+    console.log();
+  },
+
+  /**
+   * Validate adapter capability requirements (FEAT-021 Phase 127)
+   * Usage: vp-tools validate --adapter <id>
+   */
+  validate: (args) => {
+    const { getAdapterContext, listAdapterIds } = require('../lib/adapter-context.cjs');
+    const adapterIdx = args.indexOf('--adapter');
+    const adapterId = adapterIdx !== -1 ? args[adapterIdx + 1] : null;
+
+    if (!adapterId) {
+      console.error(formatError('--adapter <id> is required', `Known adapters: ${listAdapterIds().join(', ')}`));
+      process.exitCode = 1;
+      return;
+    }
+
+    let ctx;
+    try {
+      ctx = getAdapterContext(adapterId);
+    } catch (e) {
+      console.error(formatError(e.message));
+      process.exitCode = 1;
+      return;
+    }
+
+    const warnings = [];
+    const errors = [];
+
+    // Critical tool checks
+    if (!ctx.tools.shell) errors.push('No shell/command execution tool — vp-auto cannot run bash commands');
+    if (!ctx.tools.read && !ctx.tools.write) errors.push('No file read or write tool — skill execution will be severely limited');
+    if (!ctx.tools.edit && !ctx.tools.write) errors.push('No file edit/write tool — cannot implement code changes');
+
+    // AUQ interactive check
+    if (ctx.interactive === 'none') {
+      warnings.push('No interactive prompts (AUQ/AskQuestion) — all prompts will be skipped or use defaults');
+    } else if (ctx.interactive === 'text-plan-only' || ctx.interactive === 'text') {
+      warnings.push(`Interactive mode is "${ctx.interactive}" — AUQ not available; text list fallback will be used`);
+    }
+
+    // Orchestration
+    if (!ctx.orchestration.parallel) {
+      warnings.push('Parallel task execution not supported — vp-auto will run in sequential mode (higher token usage)');
+    }
+
+    // MCP limit
+    if (ctx.mcp.tool_limit !== null) {
+      warnings.push(`MCP tool limit: ${ctx.mcp.tool_limit} tools — verify your MCP server count stays within limit`);
+    }
+
+    // Hooks
+    if (ctx.hooks.count === 0) {
+      warnings.push('No hook events supported — PreToolUse/PostToolUse gates will not fire');
+    }
+
+    // Antigravity deprecation
+    if (ctx.deprecation_notice) {
+      warnings.push(`DEPRECATION: ${ctx.deprecation_notice}`);
+    }
+
+    // Output
+    console.log(`\n${colors.bold}ViePilot Capability Validation${colors.reset}`);
+    console.log(`${colors.cyan}Adapter:${colors.reset} ${ctx.name} (${adapterId})\n`);
+
+    if (errors.length === 0 && warnings.length === 0) {
+      console.log(formatSuccess('All capability checks passed — adapter fully supported'));
+      return;
+    }
+
+    errors.forEach(e => console.log(formatError(`CRITICAL: ${e}`)));
+    warnings.forEach(w => console.log(formatWarning(`WARN: ${w}`)));
+
+    if (errors.length > 0) {
+      console.log(`\n${colors.red}${errors.length} critical gap(s) detected. Some ViePilot features will not work on this adapter.${colors.reset}`);
+      process.exitCode = 1;
+    } else {
+      console.log(`\n${colors.yellow}${warnings.length} warning(s). ViePilot will work with limitations on this adapter.${colors.reset}`);
+    }
+  },
+
   /**
    * Help
    */
@@ -1501,6 +1621,8 @@ ${colors.cyan}Commands:${colors.reset}
   ${colors.bold}scan-skills${colors.reset}               Scan installed skills → ~/.viepilot/skill-registry.json
   ${colors.bold}check-update${colors.reset} [--silent]   Check for latest ViePilot version on npm (24h cached)
   ${colors.bold}persona${colors.reset} <op>              Manage user personas (get|infer|list|set|auto-switch|context)
+  ${colors.bold}detect-adapter${colors.reset} [--json]   Detect active adapter (claude-code/cursor/antigravity/codex/copilot)
+  ${colors.bold}validate${colors.reset} --adapter <id>   Validate adapter capability requirements; exits 1 on critical gaps
   ${colors.bold}help${colors.reset} [command]           Show help (optionally for specific command)
 
 ${colors.cyan}Examples:${colors.reset}
@@ -1517,7 +1639,7 @@ ${colors.gray}Run 'vp-tools help <command>' for detailed help on a specific comm
 
 // Helper function for progress bars
 function createProgressBar(percent, width = 10) {
-  const filled = Math.round(percent / (100 / width));
+  const filled = Math.min(Math.round(percent / (100 / width)), width);
   const empty = width - filled;
   return `[${colors.green}${'█'.repeat(filled)}${colors.gray}${'░'.repeat(empty)}${colors.reset}]`;
 }