aiwcli 0.11.1 → 0.12.1

package/dist/templates/cc-native/_cc-native/hooks/plan_questions_early.ts

@@ -1,37 +1,37 @@
 #!/usr/bin/env bun
 /**
- * UserPromptSubmit hook — injects Phase A clarification prompt in plan mode.
+ * UserPromptSubmit hook — injects post-exploration clarification prompt in plan mode.
  *
- * On the first prompt in plan mode (before any code exploration), injects
- * a system-reminder telling Claude to ask clarification questions via
- * AskUserQuestion before exploring the codebase.
+ * After explore agents finish examining the codebase, injects a system-reminder
+ * telling Claude to ask clarification questions via AskUserQuestion to narrow
+ * the approach before drafting the plan.
  *
  * Skips if questions were already asked this session.
  */
 
 import { getProjectRoot } from "../../_shared/lib-ts/base/constants.js";
-import { emitContext, loadHookInput, logDebug, logInfo, runHook } from "../../_shared/lib-ts/base/hook-utils.js";
-import { wasQuestionsAsked } from "../lib-ts/cc-native-state.js";
+import { loadHookInput, runHook, logDebug, logInfo, emitContext } from "../../_shared/lib-ts/base/hook-utils.js";
+import { wasEarlyQuestionsAsked } from "../lib-ts/cc-native-state.js";
 
-const PHASE_A_PROMPT = `## Plan Mode: Clarify Before Exploring
+const PHASE_A_PROMPT = `## Plan Mode: Narrow the Approach After Exploration
 
-Use AskUserQuestion now — one call, 3-4 questions — before reading any code.
+After exploring the codebase, use AskUserQuestion — one call, 3-4 questions — before drafting the plan.
 
 ### Why This Matters
-Once you explore the codebase, you anchor on what you find. Questions asked after exploration confirm your assumptions instead of challenging them. Ask now, while your interpretation is still flexible.
+Once you've explored the codebase, you'll understand what exists — but not which direction the user prefers. That's a branch point: multiple viable approaches, and the user's priorities determine which is best. Questions asked after exploration have maximum steering value: they narrow your path before you commit to an implementation direction.
 
 ### What to Ask About
-Only ask about things you cannot discover from code — the user's intent, constraints, history, and priorities:
+Only ask about decisions that exploration will surface but can't resolve — where human judgment is needed to choose between viable options:
 
-- **Ambiguity:** If you can read this request two different ways, ask which interpretation is correct. Provide your top 2-3 readings as options.
-- **Invisible context:** What does the user assume "everyone knows" about this system that isn't documented? What's obvious to them but hidden to you?
-- **Success criteria:** What does "done well" look like beyond the literal request? What would make them rate this a 10?
-- **Constraints and history:** Has this been attempted before? Are there parts of the system that are off-limits or sensitive?
+- **Approach selection:** If exploration reveals 2-3 viable implementation paths, ask which the user prefers. Present each option with its trade-offs as concrete choices.
+- **Scope boundaries:** What's in scope vs. out of scope for this change? Which areas of the codebase should be left untouched? How far should the change ripple?
+- **Trade-off preferences:** Where exploration reveals tensions (simplicity vs. flexibility, speed vs. thoroughness, minimal change vs. full refactor), ask which side the user leans toward.
+- **Success criteria beyond the literal ask:** What would make this a 10? What non-obvious quality matters most — performance, readability, extensibility, consistency with existing patterns?
 
 ### How to Select Questions
-1. Generate 5+ candidate questions across the lenses above
-2. For each, evaluate: "If they answered A vs B, would I explore different files or take a different approach?" If no — discard it.
-3. Keep the 3-4 where different answers lead to meaningfully different exploration strategies
+1. Generate 5+ candidate questions across the categories above
+2. For each, evaluate: "If they answered A vs B, would I take a different approach or write different code?" If no — discard it.
+3. Keep the 3-4 where different answers lead to meaningfully different implementation strategies
 4. Frame each with 2-3 concrete options so the user can react rather than generate from scratch`;
 
 function main(): void {
@@ -49,8 +49,8 @@ function main(): void {
 
   const projectRoot = getProjectRoot(payload.cwd);
 
-  if (wasQuestionsAsked(sessionId, projectRoot)) {
-    logDebug("plan_questions_early", "Questions already asked, skipping");
+  if (wasEarlyQuestionsAsked(sessionId, projectRoot)) {
+    logDebug("plan_questions_early", "Early questions already asked, skipping Phase A prompt");
     return;
   }
 

package/dist/templates/cc-native/_cc-native/lib-ts/aggregate-agents.ts

@@ -4,9 +4,10 @@
  */
 
 import * as fs from "node:fs";
-import * as path from "node:path";
-import { logDebug, logInfo, logWarn } from "../../_shared/lib-ts/base/logger.js";
+import * as path from "node:path";
+
 import type { AgentConfig } from "./types.js";
+import { logDebug, logInfo, logWarn } from "../../_shared/lib-ts/base/logger.js";
 
 /**
  * Extract simple YAML frontmatter from markdown content.
@@ -47,7 +48,7 @@ export function extractFrontmatter(
       value = value
         .slice(1, -1)
         .split(",")
-        .map((s) => s.trim().replace(/^["']|["']$/g, ""))
+        .map((s) => s.trim().replaceAll(/^["']|["']$/g, ""))
         .filter(Boolean);
     }
     // Handle booleans
@@ -114,8 +115,8 @@ export function aggregateAgents(agentsDir?: string): AgentConfig[] {
     let content: string;
     try {
       content = fs.readFileSync(filePath, "utf-8");
-    } catch (e: unknown) {
-      logWarn("aggregate", `Failed to read ${file}: ${e}`);
+    } catch (error: unknown) {
+      logWarn("aggregate", `Failed to read ${file}: ${error}`);
       continue;
     }
 

package/dist/templates/cc-native/_cc-native/lib-ts/artifacts.ts

@@ -4,11 +4,8 @@
  */
 
 import * as fs from "node:fs";
-import * as path from "node:path";
-import { atomicWrite } from "../../_shared/lib-ts/base/atomic-write.js";
-import { logDebug, logWarn, logError } from "../../_shared/lib-ts/base/logger.js";
-import { nowIso } from "../../_shared/lib-ts/base/utils.js";
-import { sanitizeFilename } from "../../_shared/lib-ts/base/constants.js";
+import * as path from "node:path";
+
 import { ENABLE_ROBUST_PLAN_WRITES } from "./constants.js";
 import type {
   CombinedReviewResult,
@@ -17,6 +14,10 @@ import type {
   CorroborationResult,
 } from "./types.js";
 import { DEFAULT_DISPLAY } from "./types.js";
+import { atomicWrite } from "../../_shared/lib-ts/base/atomic-write.js";
+import { sanitizeFilename } from "../../_shared/lib-ts/base/constants.js";
+import { logDebug, logWarn, logError } from "../../_shared/lib-ts/base/logger.js";
+import { nowIso } from "../../_shared/lib-ts/base/utils.js";
 
 // ---------------------------------------------------------------------------
 // Markdown Formatting
@@ -81,7 +82,7 @@ export function formatCombinedMarkdown(
     if (corroboration.blocking.length > 0) {
       lines.push("### Blocking Dimensions\n");
       for (const group of corroboration.blocking) {
-        lines.push(`- **${group.dimension}**: ${group.issues.length} issues from ${group.agentCount} agents (threshold: >${group.threshold})`);
+        lines.push(`- **${group.dimension}**: ${group.issues.length} issues from ${group.agentCount} agents (threshold: ≥${group.threshold})`);
       }
       lines.push("");
     }
@@ -99,22 +100,6 @@ export function formatCombinedMarkdown(
 
   lines.push("---\n");
 
-  // CLI Reviewers section
-  if (Object.keys(result.cli_reviewers).length > 0) {
-    lines.push("## CLI Reviewers\n");
-    for (const [name, r] of Object.entries(result.cli_reviewers)) {
-      lines.push(`### ${titleCase(name)}\n`);
-      lines.push(`- verdict: \`${r.verdict}\``);
-      if (r.data && Object.keys(r.data).length > 0) {
-        appendSummaryLine(lines, r.data);
-        appendReviewDetails(lines, r.data, display);
-      } else if (r.err) {
-        lines.push(`- error: ${r.err}`);
-      }
-      lines.push("");
-    }
-  }
-
   // Orchestration section
   if (result.orchestration) {
     lines.push("---\n");
@@ -170,10 +155,7 @@ export function buildInlineReviewSummary(
   maxChars = 800,
   corroboration?: CorroborationResult,
 ): string {
-  const allReviewers = [
-    ...Object.values(combined.cli_reviewers),
-    ...Object.values(combined.agents),
-  ];
+  const allReviewers = Object.values(combined.agents);
 
   // Build set of blocking dimensions for annotation
   const blockingDims = new Set(
@@ -257,10 +239,7 @@ export function extractTopIssuesText(
   maxCount = 3,
   severity = "high",
 ): string {
-  const allReviewers = [
-    ...Object.values(combined.cli_reviewers),
-    ...Object.values(combined.agents),
-  ];
+  const allReviewers = Object.values(combined.agents);
 
   const issues: string[] = [];
   for (const r of allReviewers) {
@@ -318,10 +297,7 @@ export function buildHighIssuesDocument(
 
   // Fallback: no corroboration data — show all high-severity issues
   const lines = ["# High-Severity Issues\n"];
-  const allReviewers = [
-    ...Object.values(combined.cli_reviewers),
-    ...Object.values(combined.agents),
-  ];
+  const allReviewers = Object.values(combined.agents);
 
   let foundAny = false;
   for (const r of allReviewers) {
@@ -406,11 +382,6 @@ export function generateReviewIndex(
     "| [plan.md](./plan.md) | Plan snapshot at review time |",
   );
 
-  for (const name of Object.keys(result.cli_reviewers)) {
-    lines.push(
-      `| [${name}.json](./reviewer-output/${name}.json) | ${titleCase(name)} reviewer output |`,
-    );
-  }
   for (const name of Object.keys(result.agents)) {
     const safeName = sanitizeFilename(name);
     lines.push(
@@ -426,9 +397,6 @@ export function generateReviewIndex(
     "|----------|---------|",
   );
 
-  for (const [name, r] of Object.entries(result.cli_reviewers)) {
-    lines.push(`| ${titleCase(name)} | \`${r.verdict}\` |`);
-  }
   for (const [name, r] of Object.entries(result.agents)) {
     lines.push(`| ${name} | \`${r.verdict}\` |`);
   }
@@ -457,26 +425,6 @@ export function buildCombinedJson(
     },
   };
 
-  // CLI reviewers
-  if (Object.keys(result.cli_reviewers).length > 0) {
-    const cliReviewers: Record<string, unknown> = {};
-    output.cliReviewers = cliReviewers;
-    for (const [name, r] of Object.entries(result.cli_reviewers)) {
-      cliReviewers[name] = {
-        verdict: r.verdict,
-        summary: r.data?.summary ?? null,
-        summarySource: r.data?.summary_source ?? null,
-        issues: r.data
-          ? ((r.data.issues as Array<Record<string, unknown>>) ?? []).filter(
-              (i) => i.severity !== "low",
-            )
-          : [],
-        ok: r.ok,
-        error: r.err || null,
-      };
-    }
-  }
-
   // Orchestration
   if (result.orchestration) {
     output.orchestration = {
@@ -543,9 +491,9 @@ export function writeCombinedArtifacts(
   // Create directory
   try {
     fs.mkdirSync(outDir, { recursive: true });
-  } catch (e: unknown) {
-    logError("utils", `Cannot create directory ${outDir}: ${e}`);
-    throw e;
+  } catch (error: unknown) {
+    logError("utils", `Cannot create directory ${outDir}: ${error}`);
+    throw error;
   }
 
   // JSON write
@@ -565,14 +513,6 @@ export function writeCombinedArtifacts(
   } catch {
     // Best-effort — non-critical
   }
-  for (const [name, r] of Object.entries(result.cli_reviewers)) {
-    if (r.data) {
-      writeFileNonCritical(
-        path.join(reviewerOutputDir, `${name}.json`),
-        JSON.stringify(r.data, null, 2),
-      );
-    }
-  }
   for (const [name, r] of Object.entries(result.agents)) {
     if (r.data) {
       writeFileNonCritical(
@@ -658,9 +598,9 @@ function writeFile(filePath: string, content: string): void {
     } else {
       fs.writeFileSync(filePath, content, "utf-8");
     }
-  } catch (e: unknown) {
-    logError("utils", `Failed to write ${path.basename(filePath)}: ${e}`);
-    throw e;
+  } catch (error: unknown) {
+    logError("utils", `Failed to write ${path.basename(filePath)}: ${error}`);
+    throw error;
   }
 }
 
@@ -674,8 +614,8 @@ function writeFileNonCritical(filePath: string, content: string): void {
     } else {
       fs.writeFileSync(filePath, content, "utf-8");
     }
-  } catch (e: unknown) {
-    logWarn("utils", `Failed to write ${path.basename(filePath)}: ${e}`);
+  } catch (error: unknown) {
+    logWarn("utils", `Failed to write ${path.basename(filePath)}: ${error}`);
   }
 }
 
@@ -731,13 +671,13 @@ export function writeReviewTracker(
   // Parse existing entries to detect plan changes
   const previousHashes = extractPreviousHashes(existingContent);
   const hashChanged = previousHashes.length > 0 &&
-    previousHashes[previousHashes.length - 1] !== entry.planHash;
+    previousHashes.at(-1) !== entry.planHash;
 
   // Build the new entry section
   const lines: string[] = [];
-  const verdictEmoji = entry.decision === "allow" ? "\u2705" : "\u274c";
+  const verdictEmoji = entry.decision === "allow" ? "\u2705" : "\u274C";
   const changeNote = previousHashes.length > 0
-    ? (hashChanged ? "\u2705 Plan was revised (hash changed)" : "\u26a0\ufe0f Plan unchanged since last review")
+    ? (hashChanged ? "\u2705 Plan was revised (hash changed)" : "\u26A0\uFE0F Plan unchanged since last review")
     : "Initial review";
 
   lines.push(`## Iteration ${entry.iteration} \u2014 ${entry.timestamp} \u2014 ${verdictEmoji} ${entry.verdict.toUpperCase()}`);
@@ -776,8 +716,8 @@ export function writeReviewTracker(
 
   try {
     fs.writeFileSync(trackerPath, output, "utf-8");
-  } catch (e) {
-    logWarn("artifacts", `Failed to write review tracker: ${e}`);
+  } catch (error) {
+    logWarn("artifacts", `Failed to write review tracker: ${error}`);
   }
 }
 
@@ -790,3 +730,94 @@ function extractPreviousHashes(content: string): string[] {
   }
   return hashes;
 }
+
+// ---------------------------------------------------------------------------
+// Corroboration Report
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a detailed markdown report of the corroboration analysis.
+ * Shows blocking vs solo findings with threshold comparison.
+ */
+export function buildCorroborationReport(
+  corroborationResult: CorroborationResult,
+): string {
+  const lines: string[] = [
+    "# Corroboration Analysis",
+    "",
+    "## Verdict: " + corroborationResult.verdict.toUpperCase(),
+    "",
+  ];
+
+  // Blocking groups table
+  if (corroborationResult.blocking.length > 0) {
+    lines.push("## Blocking Issues (Corroborated)");
+    lines.push("");
+    lines.push("| Dimension | Issues | Agents | Threshold | Status |");
+    lines.push("|-----------|--------|--------|-----------|--------|");
+
+    for (const group of corroborationResult.blocking) {
+      lines.push(
+        `| ${group.dimension} | ${group.issues.length} | ${group.agentCount} | ${group.threshold} | ⛔ EXCEEDED |`
+      );
+    }
+    lines.push("");
+
+    // Issue details
+    for (const group of corroborationResult.blocking) {
+      lines.push(`### ${group.dimension} (${group.issues.length} issues)`);
+      lines.push("");
+      for (const {agent, issue} of group.issues) {
+        lines.push(`- **[${agent}]** ${issue.description || issue.issue || "No description"}`);
+      }
+      lines.push("");
+    }
+  }
+
+  // Solo findings table
+  if (corroborationResult.solo.length > 0) {
+    lines.push("## Solo Findings (Below Threshold)");
+    lines.push("");
+    lines.push("| Dimension | Issues | Agents | Threshold | Status |");
+    lines.push("|-----------|--------|--------|-----------|--------|");
+
+    for (const group of corroborationResult.solo) {
+      lines.push(
+        `| ${group.dimension} | ${group.issues.length} | ${group.agentCount} | ${group.threshold} | ℹ️ SOLO |`
+      );
+    }
+    lines.push("");
+
+    // Issue details
+    for (const group of corroborationResult.solo) {
+      lines.push(`### ${group.dimension} (${group.issues.length} issues)`);
+      lines.push("");
+      for (const {agent, issue} of group.issues) {
+        lines.push(`- **[${agent}]** ${issue.description || issue.issue || "No description"}`);
+      }
+      lines.push("");
+    }
+  }
+
+  // Unclassified issues
+  if (corroborationResult.unclassified.length > 0) {
+    lines.push("## Unclassified Issues (No Dimension)");
+    lines.push("");
+    for (const {agent, issue} of corroborationResult.unclassified) {
+      lines.push(`- **[${agent}]** ${issue.description || issue.issue || "No description"}`);
+    }
+    lines.push("");
+  }
+
+  // Summary
+  lines.push("## Summary");
+  lines.push("");
+  lines.push(`- **Blocking groups**: ${corroborationResult.blocking.length}`);
+  lines.push(`- **Solo findings**: ${corroborationResult.solo.length}`);
+  lines.push(`- **Unclassified**: ${corroborationResult.unclassified.length}`);
+  lines.push(`- **Final verdict**: ${corroborationResult.verdict}`);
+  lines.push("");
+  lines.push("**Threshold rule**: Issues in a dimension block when count ≥ 2× distinct agents in that dimension.");
+
+  return lines.join("\n");
+}

package/dist/templates/cc-native/_cc-native/lib-ts/cc-native-state.ts

@@ -1,14 +1,15 @@
 /**
  * CC-native state accessor for context state.json.
- * Deduplicates state access patterns for cc-native hooks.
+ * Deduplicates state access patterns from utils.py and suggest-fresh-perspective.py.
  * See cc-native-plan-review-spec.md §4.5
  */
 
 import type {
   CcNativeState,
-  IterationState,
   PlanReviewState,
-  QuestionsAskedState as _QuestionsAskedState,
+  QuestionsAskedState,
+  IterationState,
+  StuckDetectionState,
 } from "./types.js";
 import { logInfo, logWarn } from "../../_shared/lib-ts/base/logger.js";
 import { nowIso } from "../../_shared/lib-ts/base/utils.js";
@@ -42,7 +43,6 @@ export function getCcNativeState(
   } catch {
     // Fail-safe: return null
   }
-
   return null;
 }
 
@@ -65,7 +65,6 @@ export function saveCcNativeState(
   } catch (error: unknown) {
     logWarn("utils", `Failed to save cc_native state: ${error}`);
   }
-
   return false;
 }
 
@@ -104,6 +103,22 @@ export function wasPlanPreviouslyDenied(
   return decision === "deny" || decision.startsWith("hook_deny");
 }
 
+/**
+ * Get the last plan review state for this session.
+ * Returns null if no review state exists or plan hash doesn't match.
+ */
+export function getLastPlanReview(
+  sessionId: string,
+  planHash: string,
+  projectRoot: string,
+): PlanReviewState | null {
+  const ccNative = getCcNativeState(sessionId, projectRoot);
+  if (!ccNative) return null;
+  const reviewState = ccNative.plan_review;
+  if (reviewState?.plan_hash !== planHash) return null;
+  return reviewState;
+}
+
 /**
  * Mark this plan as reviewed (stores hash and decision in state.json).
  */
@@ -175,20 +190,69 @@ export function wasQuestionsAsked(
 }
 
 /**
- * Mark that AskUserQuestion was called. Returns true on success.
+ * Check if early questions (Phase A: AskUserQuestion) were asked this session.
+ * Returns false on any error (fail-safe: allow feature to work).
+ */
+export function wasEarlyQuestionsAsked(
+  sessionId: string,
+  projectRoot: string,
+): boolean {
+  const ccNative = getCcNativeState(sessionId, projectRoot);
+  if (!ccNative) return false;
+  return ccNative.questions_asked?.early_questions_asked?.asked === true;
+}
+
+/**
+ * Check if plan questions agent (Phase B: independent question agent) ran this session.
+ * Returns false on any error (fail-safe: allow feature to work).
+ */
+export function wasPlanQuestionsAgentAsked(
+  sessionId: string,
+  projectRoot: string,
+): boolean {
+  const ccNative = getCcNativeState(sessionId, projectRoot);
+  if (!ccNative) return false;
+  return ccNative.questions_asked?.plan_questions_agent_asked?.asked === true;
+}
+
+/**
+ * Mark that questions were asked in a specific phase. Returns true on success.
  * Only stores timestamp, no user data.
+ * @param phase - 'early' for Phase A (AskUserQuestion), 'agent' for Phase B (independent question agent)
  */
 export function markQuestionsAsked(
   sessionId: string,
   projectRoot: string,
+  phase: "early" | "agent",
 ): boolean {
   try {
     const ccNative = getCcNativeState(sessionId, projectRoot) ?? {};
+    const timestamp = nowIso();
 
-    ccNative.questions_asked = {
-      asked: true,
-      asked_at: nowIso(),
-    };
+    // Initialize questions_asked if it doesn't exist
+    if (!ccNative.questions_asked) {
+      ccNative.questions_asked = {
+        asked: false,
+        asked_at: "",
+      };
+    }
+
+    // Mark phase-specific gate
+    if (phase === "early") {
+      ccNative.questions_asked.early_questions_asked = {
+        asked: true,
+        asked_at: timestamp,
+      };
+    } else {
+      ccNative.questions_asked.plan_questions_agent_asked = {
+        asked: true,
+        asked_at: timestamp,
+      };
+    }
+
+    // Update backward-compatible fields
+    ccNative.questions_asked.asked = true;
+    ccNative.questions_asked.asked_at = timestamp;
 
     return saveCcNativeState(sessionId, projectRoot, ccNative);
   } catch (error: unknown) {
@@ -197,3 +261,36 @@ export function markQuestionsAsked(
   }
 }
 
+// ---------------------------------------------------------------------------
+// Stuck Detection State
+// ---------------------------------------------------------------------------
+
+/**
+ * Get stuck detection state from cc_native.
+ */
+export function getStuckDetectionState(
+  sessionId: string,
+  projectRoot: string,
+): StuckDetectionState | null {
+  const ccNative = getCcNativeState(sessionId, projectRoot);
+  return ccNative?.stuck_detection ?? null;
+}
+
+/**
+ * Update stuck detection state.
+ */
+export function updateStuckDetectionState(
+  sessionId: string,
+  projectRoot: string,
+  stuckState: StuckDetectionState,
+): boolean {
+  try {
+    const ccNative = getCcNativeState(sessionId, projectRoot) ?? {};
+    ccNative.stuck_detection = stuckState;
+    return saveCcNativeState(sessionId, projectRoot, ccNative);
+  } catch (error: unknown) {
+    logWarn("utils", `Failed to update stuck detection state: ${error}`);
+    return false;
+  }
+}
+

package/dist/templates/cc-native/_cc-native/lib-ts/cli-output-parser.ts

@@ -1,6 +1,6 @@
 /**
  * Unified Claude CLI output parser.
- * Deduplicates identical logic from orchestrator.py and reviewers/agent.py.
+ * Deduplicates identical logic from orchestrator.ts and reviewers/agent.ts.
  * See cc-native-plan-review-spec.md §4.6
  */
 

package/dist/templates/cc-native/_cc-native/lib-ts/corroboration.ts

@@ -89,7 +89,7 @@ export function computeCorroboratedDecision(
     const agentCount = group.agentNames.size;
     const threshold = 2 * agentCount;
 
-    if (group.issues.length > threshold) {
+    if (group.issues.length >= threshold) {
       blocking.push({
         dimension,
         issues: group.issues,
@@ -110,6 +110,10 @@ export function computeCorroboratedDecision(
     blocking,
     solo,
     unclassified,
-    verdict: blocking.length > 0 ? "fail" : "pass",
+    verdict: blocking.length > 0
+      ? "fail"
+      : solo.length > 0
+        ? "warn"
+        : "pass",
   };
 }

package/dist/templates/cc-native/_cc-native/lib-ts/index.ts

@@ -64,11 +64,7 @@ export { buildOrchestratorSchema, runOrchestrator } from "./orchestrator.js";
 // Reviewers
 export {
   AgentReviewer,
-  CodexReviewer,
-  GeminiReviewer,
   runAgentReview,
-  runCodexReview,
-  runGeminiReview,
 } from "./reviewers/index.js";
 
 // Iteration state