refactor(agents): user-friendly agent version handling — warn once, never block

docs/superpowers/tasks/2026-08-04-untested-agent-version-warning-non-blocking/actual-complexity.json

@@ -0,0 +1,112 @@
+{
+  "task": "Replace blocking per-agent supported-version checks with a one-time non-blocking untested-version warning (VersionWarningStore), remove pinned version constants from all four agent plugins, expose --reset-version-warnings on codemie doctor, and ensure ACP/non-interactive paths never block.",
+  "generated": "2026-08-04T00:00:00Z",
+  "dimensions": {
+    "component_scope": {
+      "score": 6,
+      "label": "XXL",
+      "affected": "BaseAgentAdapter, AgentAdapter interface (types.ts), ClaudePlugin, CodexPlugin, GeminiPlugin, KimiPlugin, install command, setup command, update command, AgentsCheck, doctor command, VersionWarningStore (new), isInteractive utility (new)",
+      "layers": "Core/Adapter, Plugin (4 agents), CLI commands (install/setup/update/doctor), State-persistence"
+    },
+    "requirements_clarity": {
+      "score": 3,
+      "label": "M",
+      "status": "Partially Clear",
+      "gaps": "Two design decisions were open at spec time: (1) what 'install --version supported' resolves to after metadata.supportedVersion removal — resolved as an alias for 'latest'; (2) the exact form of the reset mechanism — resolved as a --reset-version-warnings flag on doctor. A code-review fix-up round was needed to address blocking findings, confirming that clarity gaps led to some rework."
+    },
+    "technical_risk": {
+      "score": 4,
+      "label": "L",
+      "risk_factors": "Behavioral change on agent launch path (throw-on-version-mismatch replaced by log-and-proceed in warnOnceIfUntested); blocking code-review findings requiring a fix-up round (8 commits total, reviewed_head fae26e83 plus fix-up acc7b99); silentMode/non-TTY path must never produce inquirer prompts or process.exit; zero pre-existing unit-test coverage on the version-check branch of BaseAgentAdapter.run()",
+      "mitigation": "warnOnceIfUntested() is wrapped in a top-level try/catch so it can never throw; isInteractive() predicate gates chalk banner to TTY-only; 8 new test files added (BaseAgentAdapter.version-warning.test.ts, version-warnings.test.ts, tty.test.ts, AgentsCheck.status.test.ts, reset-version-warnings.test.ts, install.version-selection.test.ts, codex.plugin.version-support.test.ts, kimi.plugin.test.ts); agent-build-setup.ts fixed to remove CLAUDE_SUPPORTED_VERSION import from built dist"
+    },
+    "file_change_estimate": {
+      "score": 5,
+      "label": "XL",
+      "modified_files": 13,
+      "modified_file_list": [
+        "src/agents/core/BaseAgentAdapter.ts",
+        "src/agents/core/__tests__/BaseAgentAdapter.test.ts",
+        "src/agents/core/types.ts",
+        "src/agents/plugins/claude/claude.plugin.ts",
+        "src/agents/plugins/codex/codex.plugin.ts",
+        "src/agents/plugins/gemini/gemini.plugin.ts",
+        "src/agents/plugins/kimi/kimi.plugin.ts",
+        "src/cli/commands/install.ts",
+        "src/cli/commands/setup.ts",
+        "src/cli/commands/update.ts",
+        "src/cli/commands/doctor/checks/AgentsCheck.ts",
+        "src/cli/commands/doctor/index.ts",
+        "tests/setup/agent-build-setup.ts"
+      ],
+      "new_files": 10,
+      "new_file_list": [
+        "src/utils/version-warnings.ts",
+        "src/utils/tty.ts",
+        "src/agents/core/__tests__/BaseAgentAdapter.version-warning.test.ts",
+        "src/agents/plugins/codex/__tests__/codex.plugin.version-support.test.ts",
+        "src/agents/plugins/kimi/__tests__/kimi.plugin.test.ts",
+        "src/cli/commands/__tests__/install.version-selection.test.ts",
+        "src/cli/commands/doctor/__tests__/reset-version-warnings.test.ts",
+        "src/cli/commands/doctor/checks/__tests__/AgentsCheck.status.test.ts",
+        "src/utils/__tests__/tty.test.ts",
+        "src/utils/__tests__/version-warnings.test.ts"
+      ],
+      "affected_dirs": [
+        "src/agents/core",
+        "src/agents/plugins",
+        "src/cli/commands",
+        "src/cli/commands/doctor",
+        "src/utils",
+        "tests/setup",
+        "docs/superpowers/tasks"
+      ]
+    },
+    "dependencies": {
+      "score": 1,
+      "label": "XS",
+      "new_packages": [],
+      "version_changes": []
+    },
+    "affected_layers": {
+      "score": 4,
+      "label": "L",
+      "layers_changed": [
+        "CLI (install, setup, update, doctor commands)",
+        "Plugin/Agent-Tool (claude, codex, gemini, kimi plugins)",
+        "Core/Adapter (BaseAgentAdapter, AgentAdapter interface)",
+        "DB-Persistence (VersionWarningStore writing ~/.codemie/version-warnings.json)"
+      ],
+      "schema_migration": false,
+      "cross_system": false
+    }
+  },
+  "total": 23,
+  "size": "L",
+  "band_range": "21-26",
+  "files_changed": 30,
+  "routing": "brainstorming",
+  "key_reasoning": [
+    {
+      "dimension": "component_scope",
+      "reason": "Four distinct agent plugin files (claude, codex, gemini, kimi) each had pinned-version constants removed. BaseAgentAdapter — the shared launch gate for all agents — gained warnOnceIfUntested() and a restructured installVersion() method. The AgentAdapter interface in types.ts was extended with two new required methods. Three CLI commands (install, setup, update) and the doctor subsystem (index + AgentsCheck) were updated. A new VersionWarningStore abstraction was introduced. 'Affects multiple workflows or agents' red flag bumped Component Scope from XL (5) to XXL (6)."
+    },
+    {
+      "dimension": "file_change_estimate",
+      "reason": "23 source files changed in total (13 modified, 10 new). New file count of 10 exceeds the XL threshold of 4-6 new files; modified count of 13 sits firmly in the XL range (11-15). Changes span 7 distinct directory subtrees across agents, CLI, utils, and tests. Scores XL (5) — the high new-file count is primarily 8 new test files covering previously untested code paths."
+    },
+    {
+      "dimension": "technical_risk",
+      "reason": "The launch-path behavioral change (blocking version check replaced by silent warn-and-proceed) required a code-review fix-up round (final commit acc7b99 on top of reviewed head fae26e83, 8 commits total), confirming that technical risk was real. The silentMode/non-TTY contract (no chalk banner, no inquirer, no process.exit) is a correctness constraint on ACP consumers. The agent-build-setup.ts integration-test globalSetup imported CLAUDE_SUPPORTED_VERSION from built dist — removing the constant broke all agent integration tests and had to be fixed in the same branch."
+    },
+    {
+      "dimension": "affected_layers",
+      "reason": "Four distinct architectural layers: (1) CLI commands layer — install, setup, update, doctor surface changes; (2) Plugin/Agent-Tool — four agent plugin files, metadata cleanup; (3) Core/Adapter — BaseAgentAdapter and AgentAdapter interface, the shared base class; (4) DB-Persistence — new VersionWarningStore writing version-warnings.json at ~/.codemie/. No external service integration and no schema migration, placing the score at L (4) rather than XL."
+    }
+  ],
+  "red_flags_applied": [
+    "Component Scope bumped from XL (5) to XXL (6): 'Affects multiple workflows or agents' — implementation modifies four distinct agent plugin workflows (claude, codex, gemini, kimi) plus install, update, setup, and doctor command workflows.",
+    "Component Scope: 'Touches core shared utilities' (BaseAgentAdapter is the base class for all agent adapters) — would bump from XXL (6) to 7; capped at 6."
+  ],
+  "split_recommendation": null
+}

docs/superpowers/tasks/2026-08-04-untested-agent-version-warning-non-blocking/code-review-check.json

@@ -0,0 +1,48 @@
+{
+  "decision": "approve",
+  "rationale": "Fix-up diff (8 files, +96/-48) targets exactly the six blocking findings from the final round and nothing else. Verified per finding: CR-001 update.ts now calls installVersion('latest') for Claude, invokes agent.warnOnceIfUntested() after every update path, and drops the 'verified version by CodeMie' wording. CR-002 BaseAgentAdapter.warnOnceIfUntested() returns early with logger.debug when getCurrentCliVersion() is null instead of persisting the 'unknown' fallback; a new test locks the behavior. CR-003 AgentsCheck.buildDetail() wraps VersionWarningStore.hasWarned() in try/catch that degrades to 'Untested' with logger.warn — a new test asserts doctor no longer rejects when hasWarned throws. CR-004 VersionWarningStore.clear() soft-fails on non-ENOENT unlink errors (logs and returns { removed: 0 }) so `codemie doctor --reset-version-warnings` cannot crash on EACCES/EROFS/EPERM. CR-005 setup.ts wraps warnOnceIfUntested() in a Promise.race with a 3-second timeout that resolves silently, matching the existing budget for the first getVersionInfo() call. CR-006 tests/setup/agent-build-setup.ts now installs claude --latest unconditionally at globalSetup, restoring predictable integration-test behavior. No new callers of removed symbols and no new high-risk surface — the confirmation pass was not required. Post-fix verification: typecheck PASS, lint PASS, unit suite PASS (2660 tests, 1 skipped).",
+  "confidence": "high",
+  "risk_flags": [],
+  "business_review": [
+    {"id": "AC-1", "criterion": "User is never prevented from launching a wrapped agent by a version check", "status": "pass"},
+    {"id": "AC-2", "criterion": "User warned at most once per (agent, agent-version, codemie-version) tuple", "status": "pass", "notes": "CR-002 fix removes the 'unknown' fallback tuple that previously broke the guarantee."},
+    {"id": "AC-3", "criterion": "All pinned per-agent supported-version constants removed", "status": "pass"},
+    {"id": "AC-4", "criterion": "Non-interactive/ACP/silent: logger.warn + proceed, never throw, never inquirer.prompt", "status": "pass"},
+    {"id": "AC-5", "criterion": "codemie doctor surfaces per-agent verification status", "status": "pass"},
+    {"id": "AC-6", "criterion": "Banner format for first launch", "status": "partial", "notes": "Minor spec deviation (single guidance line vs two in the spec example) not addressed — non-blocking, deferred."},
+    {"id": "AC-7", "criterion": "Repeat launch with already-acknowledged tuple is silent", "status": "pass"},
+    {"id": "AC-8", "criterion": "Non-interactive contexts: logger.warn only, no stderr/stdout prose", "status": "pass"},
+    {"id": "AC-9", "criterion": "codemie install: one-time warning emitted via shared helper after successful install", "status": "pass"},
+    {"id": "AC-10", "criterion": "--supported flag routes to 'latest'; default routing no longer uses supported version", "status": "pass"},
+    {"id": "AC-11", "criterion": "codemie update: use getVersionInfo(); emit one-time warning via shared helper", "status": "pass", "notes": "CR-001 fix wires warnOnceIfUntested() into updateAgent() for all agent paths."},
+    {"id": "AC-12", "criterion": "codemie setup: replace isNewer/compatible block with shared helper; preserve 3-second timeout", "status": "pass", "notes": "CR-005 fix extends the 3-second budget to warnOnceIfUntested() as well."},
+    {"id": "AC-13", "criterion": "codemie doctor --reset-version-warnings", "status": "pass"},
+    {"id": "AC-14", "criterion": "Doctor state colors: Acknowledged=green, Untested=yellow, Not installed=gray", "status": "partial", "notes": "Formatter maps status:'info' → chalk.white for 'Not installed' vs spec's chalk.gray — minor visual deviation, non-blocking, deferred."},
+    {"id": "AC-15", "criterion": "Deprecation warning for legacy npm-global installs preserved", "status": "pass"},
+    {"id": "AC-16", "criterion": "isInteractive() predicate matches spec", "status": "pass"},
+    {"id": "AC-17", "criterion": "ACP silentMode 'throw' removed — log-and-proceed only", "status": "pass"},
+    {"id": "AC-18", "criterion": "VersionWarningStore file path, schema, ordering, corrupt/missing fallback", "status": "pass"},
+    {"id": "AC-19", "criterion": "Store read/write failures are non-fatal; version-check never blocks launch", "status": "pass"},
+    {"id": "AC-20", "criterion": "VersionWarningStore unit tests: empty/record/read/dedup/clear/corrupt", "status": "pass"},
+    {"id": "AC-21", "criterion": "BaseAgentAdapter.warnOnceIfUntested tests: all branches covered", "status": "pass", "notes": "Now covers null-codemieVersion early return too."},
+    {"id": "AC-22", "criterion": "AgentsCheck + reset-version-warnings tests", "status": "pass", "notes": "Now covers hasWarned-throws graceful-degradation path."},
+    {"id": "AC-23", "criterion": "codex.plugin.version-support.test.ts rewritten", "status": "pass"},
+    {"id": "AC-24", "criterion": "agent-build-setup.ts does not import CLAUDE_SUPPORTED_VERSION", "status": "pass", "notes": "CR-006 fix reintroduces predictable version behavior via unconditional --latest install."},
+    {"id": "AC-25", "criterion": "hasUpdate && compatible prompt removed from run()", "status": "pass"}
+  ],
+  "standards_review": [
+    {"category": "git-workflow", "status": "pass", "notes": "Fix-up commit uses `fix(agents): address CR-001 through CR-006 from code-review-final` — allowed type, allowed scope, subject <100 chars."},
+    {"category": "code-quality", "status": "pass", "notes": "ES modules, .js import extensions, logger for diagnostics, no console.log for debug."},
+    {"category": "security", "status": "pass", "notes": "No new secrets, no shell injection, no unsafe file handling introduced by the fix-up."},
+    {"category": "development-practices", "status": "pass", "notes": "Error boundaries now correctly wrap the VersionWarningStore read/clear paths in the doctor code — the gap flagged in the final round is closed."}
+  ],
+  "findings": [],
+  "finding_status": [
+    {"id": "CR-001", "status": "resolved", "evidence": "src/cli/commands/update.ts:130 installVersion('latest'), :165-167 warnOnceIfUntested() call, :176 wording change"},
+    {"id": "CR-002", "status": "resolved", "evidence": "src/agents/core/BaseAgentAdapter.ts:288-293 early return with logger.debug; new test in BaseAgentAdapter.version-warning.test.ts:159-173"},
+    {"id": "CR-003", "status": "resolved", "evidence": "src/cli/commands/doctor/checks/AgentsCheck.ts:66-76 try/catch around hasWarned; new test in AgentsCheck.status.test.ts:76-86"},
+    {"id": "CR-004", "status": "resolved", "evidence": "src/utils/version-warnings.ts:118-125 non-ENOENT errors caught, logged, return { removed: 0 }"},
+    {"id": "CR-005", "status": "resolved", "evidence": "src/cli/commands/setup.ts:113-119 Promise.race wraps warnOnceIfUntested with 3-second budget"},
+    {"id": "CR-006", "status": "resolved", "evidence": "tests/setup/agent-build-setup.ts:251-256 unconditional installVersion('latest') at globalSetup"}
+  ]
+}