aiwcli 0.12.7 → 0.12.8

package/dist/templates/cc-native/_cc-native/plan-review/agents/plan-review/VERIFY-COVERAGE.md

@@ -0,0 +1,74 @@
+---
+name: verify-coverage
+description: Test coverage mapper who ensures every implementation step has a corresponding verification step. Catches changes with no testing, verification gaps, and the common pattern of testing happy paths while ignoring error paths.
+model: sonnet
+focus: verification coverage mapping
+categories:
+  - code
+  - infrastructure
+  - documentation
+  - design
+  - research
+  - life
+  - business
+---
+
+# Verify Coverage - Plan Review Agent
+
+You map implementation steps to verification steps. Your question: "Is every change covered by a verification step?"
+
+## Your Core Principle
+
+A plan without adequate verification is a plan that assumes success. The most dangerous gap is not a missing feature — it is a missing test. Every implementation step that lacks a corresponding verification step is a step where failure will go undetected. Coverage mapping ensures 1:1 correspondence between "what we change" and "how we confirm it worked."
+
+## Your Expertise
+
+- **Coverage gap detection**: Implementation steps with no corresponding verification
+- **Happy path bias**: Verification that only tests the success case, ignoring error and edge cases
+- **Verification specificity**: Are verification steps concrete enough to execute without interpretation?
+- **Regression awareness**: Do verification steps confirm existing functionality still works after the change?
+- **Coverage completeness**: Does the verification plan cover all dimensions of the change (functionality, performance, security)?
+
+## Review Approach
+
+Build a coverage map between implementation and verification:
+
+1. **List all implementation steps**: Every change the plan makes
+2. **List all verification steps**: Every check the plan includes
+3. **Map 1:1**: For each implementation step, identify its verification step(s)
+4. **Find gaps**: Implementation steps with no verification
+5. **Assess coverage quality**: Do verification steps test the right things?
+
+## Verification Coverage Levels
+
+| Level | Description | Example |
+|-------|-------------|---------|
+| **Full** | Every change verified with specific criteria | "Run `pytest test_auth.py -k test_token_expiry` — 3 tests pass" |
+| **Partial** | Some changes verified, others assumed | "Run the auth tests" (misses schema change verification) |
+| **Minimal** | Only overall functionality checked | "Verify it works" |
+| **None** | Implementation step has no verification | Change with no corresponding check |
+
+## Key Distinction
+
+| Agent | Asks |
+|-------|------|
+| verify-strength | "Would these tests catch a subtle bug?" |
+| **verify-coverage** | **"Is every change covered by a verification step?"** |
+
+## CRITICAL: Single-Turn Review
+
+When reviewing a plan:
+1. Analyze the plan content provided directly (do not use Read, Glob, Grep, or any file tools)
+2. Call StructuredOutput immediately with your assessment
+3. Complete your entire review in one response
+
+Avoid querying external systems, reading codebase files, requesting additional information, or asking follow-up questions.
+
+## Required Output
+
+Call StructuredOutput with exactly these fields:
+- **verdict**: "pass" (verification covers all changes), "warn" (some gaps in verification coverage), or "fail" (critical changes without verification)
+- **summary**: 2-3 sentences explaining verification coverage assessment (minimum 20 characters)
+- **issues**: Array of coverage concerns, each with: severity (high/medium/low), category (e.g., "missing-verification", "happy-path-only", "weak-verification", "no-regression-check"), issue description, suggested_fix (specific verification step to add)
+- **missing_sections**: Verification gaps the plan should address (untested changes, missing edge cases, absent regression checks)
+- **questions**: Verification aspects that need clarification

package/dist/templates/cc-native/_cc-native/plan-review/agents/plan-review/VERIFY-STRENGTH.md

@@ -0,0 +1,69 @@
+---
+name: verify-strength
+description: Test quality analyst who evaluates whether verification steps would catch subtle bugs, not just total failures. Uses mutation testing logic to assess whether tests distinguish correct from almost-correct implementations.
+model: sonnet
+focus: test quality and mutation analysis
+categories:
+  - code
+  - infrastructure
+---
+
+# Verify Strength - Plan Review Agent
+
+You evaluate the quality of verification steps. Your question: "Would these tests catch a subtle bug, or only a total failure?"
+
+## Your Core Principle
+
+Mutation testing (DeMillo et al. 1978) reveals test strength by asking: "If I introduced a small bug, would the tests catch it?" Weak tests pass on both correct and incorrect implementations. Strong tests fail when the implementation is wrong in any way. A plan with 100% coverage but weak assertions is less safe than a plan with 50% coverage but strong assertions.
+
+## Your Expertise
+
+- **Assertion strength evaluation**: Do verification steps check specific expected values, or just "no error"?
+- **Mutation sensitivity**: Would a small change to the implementation (off-by-one, wrong variable, swapped condition) be caught?
+- **Boundary testing**: Do tests exercise boundary conditions where bugs cluster?
+- **Negative testing**: Do tests verify that invalid inputs are rejected, not just that valid inputs succeed?
+- **State verification**: Do tests check the full resulting state, or just the return value?
+
+## Review Approach
+
+For each verification step in the plan, apply mutation logic:
+
+1. **Identify what is being verified**: What specific behavior does this test confirm?
+2. **Apply mental mutations**: If the implementation had an off-by-one error, wrong variable, or swapped condition, would this test catch it?
+3. **Evaluate assertion specificity**: Does the test check a specific expected value, or just "it runs without error"?
+4. **Check boundary coverage**: Are edge cases and boundary values tested?
+5. **Assess negative testing**: Are failure cases and invalid inputs covered?
+
+## Test Strength Levels
+
+| Level | Test Behavior | Example |
+|-------|---------------|---------|
+| **Strong** | Fails on any mutation to the implementation | Checks specific values, boundaries, and error cases |
+| **Moderate** | Catches major bugs but misses subtle ones | Checks return type and approximate value |
+| **Weak** | Only catches total failure | "Assert no error" or "assert result is not null" |
+| **Absent** | No verification at all | Implementation change with no test |
+
+## Key Distinction
+
+| Agent | Asks |
+|-------|------|
+| verify-coverage | "Is every change covered by a verification step?" |
+| **verify-strength** | **"Would these tests catch a subtle bug?"** |
+
+## CRITICAL: Single-Turn Review
+
+When reviewing a plan:
+1. Analyze the plan content provided directly (do not use Read, Glob, Grep, or any file tools)
+2. Call StructuredOutput immediately with your assessment
+3. Complete your entire review in one response
+
+Avoid querying external systems, reading codebase files, requesting additional information, or asking follow-up questions.
+
+## Required Output
+
+Call StructuredOutput with exactly these fields:
+- **verdict**: "pass" (tests would catch subtle bugs), "warn" (some weak assertions), or "fail" (tests would miss common bug patterns)
+- **summary**: 2-3 sentences explaining test strength assessment (minimum 20 characters)
+- **issues**: Array of strength concerns, each with: severity (high/medium/low), category (e.g., "weak-assertion", "no-boundary-test", "missing-negative-test", "mutation-survivor", "state-unchecked"), issue description, suggested_fix (strengthen specific assertion or add test case)
+- **missing_sections**: Test strength improvements the plan should address (boundary tests, negative tests, specific assertions)
+- **questions**: Test quality aspects that need clarification

package/dist/templates/cc-native/_cc-native/{lib-ts → plan-review/lib}/agent-selection.ts

@@ -1,163 +1,163 @@
-/**
- * Agent selection: mandatory resolution, orchestrator-based selection, model assignment.
- * Extracted from cc-native-plan-review.ts.
- */
-
-import { logDebug, logInfo, logWarn } from "../../_shared/lib-ts/base/logger.js";
-import { findExecutable } from "../../_shared/lib-ts/base/subprocess-utils.js";
-
-import type {
-  AgentConfig,
-  ModelsConfig,
-  OrchestratorResult,
-  AgentSelectionResult,
-} from "./types.js";
-
-const HOOK = "agent-selection";
-
-// ---------------------------------------------------------------------------
-// Mandatory Agent Resolution
-// ---------------------------------------------------------------------------
-
-/**
- * Resolve mandatory agent names from config. Supports flat arrays or
- * complexity-tiered objects with `always`, `medium+`, and `high` keys.
- */
-export function resolveMandatoryAgents(
-  configValue: unknown,
-  complexity: string,
-): Set<string> {
-  if (Array.isArray(configValue)) {
-    return new Set(configValue as string[]);
-  }
-  if (!configValue || typeof configValue !== "object") {
-    return new Set(["handoff-readiness", "clarity-auditor", "skeptic"]);
-  }
-  const cfg = configValue as Record<string, string[]>;
-  const names = new Set(cfg.always ?? []);
-  if (complexity === "medium" || complexity === "high") {
-    for (const n of cfg["medium+"] ?? []) names.add(n);
-  }
-  if (complexity === "high") {
-    for (const n of cfg.high ?? []) names.add(n);
-  }
-  return names;
-}
-
-// ---------------------------------------------------------------------------
-// Model Assignment
-// ---------------------------------------------------------------------------
-
-/**
- * Randomly assign enabled providers and models to agents.
- * Filters to providers whose CLI is available on PATH.
- */
-export function assignModelsToAgents(
-  agents: AgentConfig[],
-  modelsConfig: ModelsConfig,
-): AgentConfig[] {
-  const enabledProviders = Object.entries(modelsConfig.providers)
-    .filter(([name, config]) => {
-      if (!config.enabled || config.models.length === 0) return false;
-      const cliName = name === "claude" ? "claude" : name;
-      const found = findExecutable(cliName);
-      if (!found) {
-        logWarn(HOOK, `Provider '${name}' enabled but CLI '${cliName}' not found on PATH — skipping`);
-      }
-      return !!found;
-    });
-
-  if (enabledProviders.length === 0) {
-    logWarn(HOOK, "No providers with available CLI found, falling back to Claude with agent defaults");
-    return agents.map(a => ({ ...a, provider: "claude" }));
-  }
-
-  return agents.map(agent => {
-    const idx = Math.floor(Math.random() * enabledProviders.length);
-    const entry = enabledProviders[idx];
-    if (!entry) return { ...agent, provider: "claude" };
-    const [providerName, providerConfig] = entry;
-    const modelIdx = Math.floor(Math.random() * providerConfig.models.length);
-    const model = providerConfig.models[modelIdx] ?? providerConfig.models[0] ?? agent.model;
-    return { ...agent, provider: providerName, model };
-  });
-}
-
-// ---------------------------------------------------------------------------
-// Agent Selection
-// ---------------------------------------------------------------------------
-
-export interface AgentSelectionInput {
-  enabledAgents: AgentConfig[];
-  orchResult: OrchestratorResult | null;
-  mandatoryConfig: unknown;
-  agentSettings: Record<string, unknown>;
-  legacyMode: boolean;
-}
-
-/**
- * Select agents based on orchestrator result and mandatory config.
- */
-export function selectAgents(input: AgentSelectionInput): AgentSelectionResult {
-  const { enabledAgents, orchResult, mandatoryConfig, agentSettings, legacyMode } = input;
-
-  let detectedComplexity = "medium";
-  let mandatoryNames = resolveMandatoryAgents(mandatoryConfig, "simple");
-
-  if (enabledAgents.length === 0) {
-    return { selectedAgents: [], mandatoryNames, detectedComplexity };
-  }
-
-  let mandatoryAgents = enabledAgents.filter(a => mandatoryNames.has(a.name));
-  let nonMandatory = enabledAgents.filter(a => !mandatoryNames.has(a.name));
-
-  logDebug(HOOK, `Mandatory agents: ${mandatoryAgents.map(a => a.name)}`);
-  logDebug(HOOK, `Non-mandatory pool: ${nonMandatory.length} agents`);
-
-  if (orchResult && !legacyMode) {
-    detectedComplexity = orchResult.complexity;
-
-    // Recompute mandatory with actual complexity
-    mandatoryNames = resolveMandatoryAgents(mandatoryConfig, detectedComplexity);
-    mandatoryAgents = enabledAgents.filter(a => mandatoryNames.has(a.name));
-    nonMandatory = enabledAgents.filter(a => !mandatoryNames.has(a.name));
-
-    const orchSelectedNames = new Set(
-      orchResult.selected_agents.filter(n => !mandatoryNames.has(n)),
-    );
-    let orchSelected = nonMandatory.filter(a => orchSelectedNames.has(a.name));
-
-    logDebug(HOOK, `Orchestrator selected (non-mandatory): ${orchSelected.map(a => a.name)}`);
-
-    // Warn if orchestrator returned unknown names
-    const knownNames = new Set(nonMandatory.map(a => a.name));
-    const unmatched = [...orchSelectedNames].filter(n => !knownNames.has(n));
-    if (unmatched.length > 0) {
-      logWarn(HOOK, `Orchestrator selected unknown agents: ${unmatched}`);
-    }
-
-    // Enforce minimum agent count
-    const fallbackByComplexity = agentSettings.fallbackByComplexity ?? { simple: 0, medium: 2, high: 4 };
-    const minAdditional = fallbackByComplexity[detectedComplexity] ?? 5;
-    if (orchSelected.length < minAdditional && nonMandatory.length > 0) {
-      const remaining = nonMandatory.filter(a => !orchSelected.includes(a));
-      const topUpCount = Math.min(minAdditional - orchSelected.length, remaining.length);
-      if (topUpCount > 0) {
-        const shuffled = [...remaining].sort(() => Math.random() - 0.5);
-        const topUp = shuffled.slice(0, topUpCount);
-        orchSelected = [...orchSelected, ...topUp];
-        logDebug(HOOK, `Topped up ${topUpCount} agents to meet ${detectedComplexity} minimum: ${topUp.map(a => a.name)}`);
-      }
-    }
-
-    const selectedAgents = [...mandatoryAgents, ...orchSelected];
-    logInfo(HOOK, `Final selection: ${selectedAgents.length} agents (${mandatoryAgents.length} mandatory + ${orchSelected.length} additional)`);
-    return { selectedAgents, mandatoryNames, detectedComplexity };
-  }
-
-  // Legacy mode: all enabled agents
-  logInfo(HOOK, "Running in legacy mode (all enabled agents)");
-  detectedComplexity = "medium";
-  mandatoryNames = resolveMandatoryAgents(mandatoryConfig, detectedComplexity);
-  return { selectedAgents: enabledAgents, mandatoryNames, detectedComplexity };
-}
+/**
+ * Agent selection: mandatory resolution, orchestrator-based selection, model assignment.
+ * Extracted from cc-native-plan-review.ts.
+ */
+
+import { logDebug, logInfo, logWarn } from "../../../_shared/lib-ts/base/logger.js";
+import { findExecutable } from "../../../_shared/lib-ts/base/subprocess-utils.js";
+
+import type {
+  AgentConfig,
+  ModelsConfig,
+  OrchestratorResult,
+  AgentSelectionResult,
+} from "../../lib-ts/types.js";
+
+const HOOK = "agent-selection";
+
+// ---------------------------------------------------------------------------
+// Mandatory Agent Resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve mandatory agent names from config. Supports flat arrays or
+ * complexity-tiered objects with `always`, `medium+`, and `high` keys.
+ */
+export function resolveMandatoryAgents(
+  configValue: unknown,
+  complexity: string,
+): Set<string> {
+  if (Array.isArray(configValue)) {
+    return new Set(configValue as string[]);
+  }
+  if (!configValue || typeof configValue !== "object") {
+    return new Set(["handoff-readiness", "clarity-auditor", "skeptic"]);
+  }
+  const cfg = configValue as Record<string, string[]>;
+  const names = new Set(cfg.always ?? []);
+  if (complexity === "medium" || complexity === "high") {
+    for (const n of cfg["medium+"] ?? []) names.add(n);
+  }
+  if (complexity === "high") {
+    for (const n of cfg.high ?? []) names.add(n);
+  }
+  return names;
+}
+
+// ---------------------------------------------------------------------------
+// Model Assignment
+// ---------------------------------------------------------------------------
+
+/**
+ * Randomly assign enabled providers and models to agents.
+ * Filters to providers whose CLI is available on PATH.
+ */
+export function assignModelsToAgents(
+  agents: AgentConfig[],
+  modelsConfig: ModelsConfig,
+): AgentConfig[] {
+  const enabledProviders = Object.entries(modelsConfig.providers)
+    .filter(([name, config]) => {
+      if (!config.enabled || config.models.length === 0) return false;
+      const cliName = name === "claude" ? "claude" : name;
+      const found = findExecutable(cliName);
+      if (!found) {
+        logWarn(HOOK, `Provider '${name}' enabled but CLI '${cliName}' not found on PATH — skipping`);
+      }
+      return !!found;
+    });
+
+  if (enabledProviders.length === 0) {
+    logWarn(HOOK, "No providers with available CLI found, falling back to Claude with agent defaults");
+    return agents.map(a => ({ ...a, provider: "claude" }));
+  }
+
+  return agents.map(agent => {
+    const idx = Math.floor(Math.random() * enabledProviders.length);
+    const entry = enabledProviders[idx];
+    if (!entry) return { ...agent, provider: "claude" };
+    const [providerName, providerConfig] = entry;
+    const modelIdx = Math.floor(Math.random() * providerConfig.models.length);
+    const model = providerConfig.models[modelIdx] ?? providerConfig.models[0] ?? agent.model;
+    return { ...agent, provider: providerName, model };
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Agent Selection
+// ---------------------------------------------------------------------------
+
+export interface AgentSelectionInput {
+  enabledAgents: AgentConfig[];
+  orchResult: OrchestratorResult | null;
+  mandatoryConfig: unknown;
+  agentSettings: Record<string, unknown>;
+  legacyMode: boolean;
+}
+
+/**
+ * Select agents based on orchestrator result and mandatory config.
+ */
+export function selectAgents(input: AgentSelectionInput): AgentSelectionResult {
+  const { enabledAgents, orchResult, mandatoryConfig, agentSettings, legacyMode } = input;
+
+  let detectedComplexity = "medium";
+  let mandatoryNames = resolveMandatoryAgents(mandatoryConfig, "simple");
+
+  if (enabledAgents.length === 0) {
+    return { selectedAgents: [], mandatoryNames, detectedComplexity };
+  }
+
+  let mandatoryAgents = enabledAgents.filter(a => mandatoryNames.has(a.name));
+  let nonMandatory = enabledAgents.filter(a => !mandatoryNames.has(a.name));
+
+  logDebug(HOOK, `Mandatory agents: ${mandatoryAgents.map(a => a.name)}`);
+  logDebug(HOOK, `Non-mandatory pool: ${nonMandatory.length} agents`);
+
+  if (orchResult && !legacyMode) {
+    detectedComplexity = orchResult.complexity;
+
+    // Recompute mandatory with actual complexity
+    mandatoryNames = resolveMandatoryAgents(mandatoryConfig, detectedComplexity);
+    mandatoryAgents = enabledAgents.filter(a => mandatoryNames.has(a.name));
+    nonMandatory = enabledAgents.filter(a => !mandatoryNames.has(a.name));
+
+    const orchSelectedNames = new Set(
+      orchResult.selected_agents.filter(n => !mandatoryNames.has(n)),
+    );
+    let orchSelected = nonMandatory.filter(a => orchSelectedNames.has(a.name));
+
+    logDebug(HOOK, `Orchestrator selected (non-mandatory): ${orchSelected.map(a => a.name)}`);
+
+    // Warn if orchestrator returned unknown names
+    const knownNames = new Set(nonMandatory.map(a => a.name));
+    const unmatched = [...orchSelectedNames].filter(n => !knownNames.has(n));
+    if (unmatched.length > 0) {
+      logWarn(HOOK, `Orchestrator selected unknown agents: ${unmatched}`);
+    }
+
+    // Enforce minimum agent count
+    const fallbackByComplexity = agentSettings.fallbackByComplexity ?? { simple: 0, medium: 2, high: 4 };
+    const minAdditional = fallbackByComplexity[detectedComplexity] ?? 5;
+    if (orchSelected.length < minAdditional && nonMandatory.length > 0) {
+      const remaining = nonMandatory.filter(a => !orchSelected.includes(a));
+      const topUpCount = Math.min(minAdditional - orchSelected.length, remaining.length);
+      if (topUpCount > 0) {
+        const shuffled = [...remaining].sort(() => Math.random() - 0.5);
+        const topUp = shuffled.slice(0, topUpCount);
+        orchSelected = [...orchSelected, ...topUp];
+        logDebug(HOOK, `Topped up ${topUpCount} agents to meet ${detectedComplexity} minimum: ${topUp.map(a => a.name)}`);
+      }
+    }
+
+    const selectedAgents = [...mandatoryAgents, ...orchSelected];
+    logInfo(HOOK, `Final selection: ${selectedAgents.length} agents (${mandatoryAgents.length} mandatory + ${orchSelected.length} additional)`);
+    return { selectedAgents, mandatoryNames, detectedComplexity };
+  }
+
+  // Legacy mode: all enabled agents
+  logInfo(HOOK, "Running in legacy mode (all enabled agents)");
+  detectedComplexity = "medium";
+  mandatoryNames = resolveMandatoryAgents(mandatoryConfig, detectedComplexity);
+  return { selectedAgents: enabledAgents, mandatoryNames, detectedComplexity };
+}