aiwcli 0.10.3 → 0.11.1

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

@@ -0,0 +1,240 @@
+/**
+ * Iteration state management for plan review cycles.
+ * State files are stored adjacent to plan files (e.g., foo.md → foo.state.json).
+ * See cc-native-plan-review-spec.md §4.7
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { atomicWrite } from "../../_shared/lib-ts/base/atomic-write.js";
+import { logInfo, logWarn, logError } from "../../_shared/lib-ts/base/logger.js";
+import { nowIso } from "../../_shared/lib-ts/base/utils.js";
+import { validatePlanPath } from "./constants.js";
+import type { IterationState, IterationEntry } from "./types.js";
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const STATE_SCHEMA_VERSION = "1.0.0";
+
+export const DEFAULT_REVIEW_ITERATIONS: Record<string, number> = {
+  simple: 1,
+  medium: 3,
+  high: 5,
+};
+
+// ---------------------------------------------------------------------------
+// State File Management
+// ---------------------------------------------------------------------------
+
+/**
+ * Derive state file path from plan file path with security validation.
+ * Example: ~/.claude/plans/foo.md → ~/.claude/plans/foo.state.json
+ *
+ * @throws Error if planPath is invalid or insecure
+ */
+export function getStateFilePath(planPath: string): string {
+  const validated = validatePlanPath(planPath);
+  const parsed = path.parse(validated);
+  return path.join(parsed.dir, `${parsed.name}.state.json`);
+}
+
+/**
+ * Load state file with schema validation and migration.
+ */
+export function loadState(planPath: string): Record<string, unknown> | null {
+  try {
+    const stateFile = getStateFilePath(planPath);
+
+    if (!fs.existsSync(stateFile)) {
+      return null;
+    }
+
+    const state = JSON.parse(
+      fs.readFileSync(stateFile, "utf-8"),
+    ) as Record<string, unknown>;
+
+    // Handle schema version (backward compatible)
+    const schemaVersion = state.schema_version as string | undefined;
+
+    if (schemaVersion === undefined) {
+      state.schema_version = STATE_SCHEMA_VERSION;
+      logInfo(
+        "state",
+        `Migrated state file to schema v${STATE_SCHEMA_VERSION}`,
+      );
+    } else if (schemaVersion !== STATE_SCHEMA_VERSION) {
+      logWarn(
+        "state",
+        `Schema mismatch (expected ${STATE_SCHEMA_VERSION}, got ${schemaVersion})`,
+      );
+    }
+
+    return state;
+  } catch (e: unknown) {
+    if (e instanceof Error && e.message.includes("Invalid plan path")) {
+      logError("state", `SECURITY: Invalid plan path: ${e}`);
+    } else {
+      logError("state", `Failed to load state: ${e}`);
+    }
+    return null;
+  }
+}
+
+/**
+ * Save state file with schema version and validation.
+ * Returns true on success, false on failure.
+ */
+export function saveStateToPlan(
+  planPath: string,
+  state: Record<string, unknown>,
+): boolean {
+  try {
+    const stateFile = getStateFilePath(planPath);
+
+    const stateWithVersion = {
+      schema_version: STATE_SCHEMA_VERSION,
+      ...state,
+    };
+
+    const [success, error] = atomicWrite(
+      stateFile,
+      JSON.stringify(stateWithVersion, null, 2),
+    );
+
+    if (!success) {
+      logError("state", `Failed to save state: ${error}`);
+      return false;
+    }
+
+    return true;
+  } catch (e: unknown) {
+    if (e instanceof Error && e.message.includes("Invalid plan path")) {
+      logError("state", `SECURITY: Invalid plan path: ${e}`);
+    } else {
+      logError("state", String(e));
+    }
+    return false;
+  }
+}
+
+/**
+ * Delete state file after successful archive.
+ * Returns true if deleted or didn't exist, false on error.
+ */
+export function deleteState(planPath: string): boolean {
+  try {
+    const stateFile = getStateFilePath(planPath);
+    if (fs.existsSync(stateFile)) {
+      fs.unlinkSync(stateFile);
+      logInfo("state", `Deleted state file: ${stateFile}`);
+    }
+    return true;
+  } catch (e: unknown) {
+    if (e instanceof Error && e.message.includes("Invalid plan path")) {
+      logError("state", `SECURITY: Invalid plan path in delete: ${e}`);
+      return false;
+    }
+    logWarn("state", `Failed to delete state file: ${e}`);
+    return false;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Iteration State Management
+// ---------------------------------------------------------------------------
+
+/**
+ * Get or initialize iteration state based on complexity.
+ */
+export function getIterationState(
+  state: Record<string, unknown>,
+  complexity: string,
+  config?: Record<string, unknown>,
+): IterationState {
+  if (state.iteration) {
+    return state.iteration as IterationState;
+  }
+
+  // Initialize new iteration state
+  const reviewIterations = { ...DEFAULT_REVIEW_ITERATIONS };
+  if (config) {
+    const overrides = config.reviewIterations as
+      | Record<string, number>
+      | undefined;
+    if (overrides) {
+      Object.assign(reviewIterations, overrides);
+    }
+  }
+
+  return {
+    current: 1,
+    max: reviewIterations[complexity] ?? 1,
+    complexity,
+    history: [],
+    graduated: [],
+    passStreaks: {},
+    lastPlanHash: "",
+  };
+}
+
+/**
+ * Record review result in iteration history and update state.
+ */
+export function updateIterationState(
+  state: Record<string, unknown>,
+  iteration: IterationState,
+  planHash: string,
+  verdict: string,
+): Record<string, unknown> {
+  const entry: IterationEntry = {
+    hash: planHash,
+    verdict,
+    timestamp: nowIso(),
+  };
+
+  iteration.history.push(entry);
+  state.iteration = iteration;
+  return state;
+}
+
+/**
+ * Determine if more review iterations are needed.
+ */
+export function shouldContinueIterating(
+  iteration: IterationState,
+  verdict: string,
+  config?: Record<string, unknown>,
+): boolean {
+  const current = iteration.current;
+  const maxIter = iteration.max;
+
+  // At or past max iterations
+  if (current >= maxIter) {
+    logInfo(
+      "state",
+      `At max iterations (${current}/${maxIter}), no more iterations`,
+    );
+    return false;
+  }
+
+  // Check early exit on all pass
+  let earlyExit = true;
+  if (config) {
+    earlyExit = (config.earlyExitOnAllPass as boolean) ?? true;
+  }
+  if (earlyExit && verdict === "pass") {
+    logInfo(
+      "state",
+      "All reviewers passed and earlyExitOnAllPass=true, exiting early",
+    );
+    return false;
+  }
+
+  logInfo(
+    "state",
+    `Continuing to next iteration (${current + 1}/${maxIter}), verdict=${verdict}`,
+  );
+  return true;
+}

package/dist/templates/cc-native/_cc-native/lib-ts/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "es2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noFallthroughCasesInSwitch": true,
+    "outDir": "dist",
+    "rootDir": "../..",
+    "declaration": true,
+    "noEmit": true,
+    "types": ["bun-types"],
+    "skipLibCheck": true
+  },
+  "include": ["./**/*.ts", "../../_shared/lib-ts/**/*.ts"],
+  "exclude": ["../../_shared/lib-ts/__tests__/**"]
+}

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

@@ -0,0 +1,385 @@
+/**
+ * CC-Native plan review type definitions.
+ * All interfaces, schemas, and prompt constants for the plan review engine.
+ * See cc-native-plan-review-spec.md §3
+ */
+
+// Re-export shared types used by cc-native consumers
+export type { ContextState, HookInput, HookOutput } from "../../_shared/lib-ts/types.js";
+
+// ---------------------------------------------------------------------------
+// Verdict & Decision Types
+// ---------------------------------------------------------------------------
+
+/** Verdict from a single reviewer */
+export type Verdict = "pass" | "warn" | "fail" | "error" | "skip";
+
+/** Decision after aggregating all verdicts */
+export type ReviewDecision = "allow" | "deny";
+
+/** Complexity level assigned by orchestrator */
+export type ComplexityCategory = "simple" | "medium" | "high";
+
+// ---------------------------------------------------------------------------
+// Review Data Structures
+// ---------------------------------------------------------------------------
+
+/** Dimension classification for corroboration-based verdict */
+export type IssueDimension =
+  | "completeness"
+  | "simplicity"
+  | "security"
+  | "performance"
+  | "reliability"
+  | "maintainability"
+  | "testability"
+  | "scope"
+  | "feasibility"
+  | "clarity";
+
+/** A single issue found during review */
+export interface ReviewIssue {
+  severity: "high" | "medium" | "low";
+  category: string;
+  issue: string;
+  suggested_fix: string;
+  dimension?: IssueDimension;
+}
+
+/** A group of issues in one dimension, classified as blocking or solo */
+export interface DimensionGroup {
+  dimension: IssueDimension;
+  issues: Array<{ agent: string; issue: ReviewIssue }>;
+  agentCount: number;
+  threshold: number; // 2 × agentCount
+}
+
+/** Corroborated (blocking) group — threshold exceeded */
+export type CorroboratedGroup = DimensionGroup;
+
+/** Solo finding — below threshold, informational only */
+export type SoloFinding = DimensionGroup;
+
+/** Result of corroboration-based verdict computation */
+export interface CorroborationResult {
+  blocking: CorroboratedGroup[];
+  solo: SoloFinding[];
+  unclassified: Array<{ agent: string; issue: ReviewIssue }>;
+  verdict: "pass" | "fail";
+}
+
+/** Normalized review data from any reviewer */
+export interface ReviewData {
+  verdict: Verdict;
+  summary: string;
+  summary_source: "reviewer" | "default";
+  issues: ReviewIssue[];
+  missing_sections: string[];
+  questions: string[];
+}
+
+/** Result from a single plan reviewer (Codex, Gemini, or Claude agent) */
+export interface ReviewerResult {
+  name: string;
+  ok: boolean;
+  verdict: Verdict;
+  data: Record<string, unknown>;
+  raw: string;
+  err: string;
+}
+
+/** Result from the plan orchestrator */
+export interface OrchestratorResult {
+  complexity: ComplexityCategory;
+  category: string;
+  selected_agents: string[];
+  reasoning: string;
+  skip_reason?: string;
+  error?: string;
+}
+
+/** Combined result from all review phases */
+export interface CombinedReviewResult {
+  plan_hash: string;
+  overall_verdict: Verdict;
+  cli_reviewers: Record<string, ReviewerResult>;
+  orchestration: OrchestratorResult | null;
+  agents: Record<string, ReviewerResult>;
+  timestamp: string;
+}
+
+/** Result from verdict aggregation */
+export interface ReviewDecisionResult {
+  should_deny: boolean;
+  reason: string; // "fail_veto" | "acceptable" | "no_signal"
+  score: number;
+}
+
+// ---------------------------------------------------------------------------
+// Agent & Orchestrator Configuration
+// ---------------------------------------------------------------------------
+
+/** Configuration for a Claude Code review agent */
+export interface AgentConfig {
+  name: string;
+  model: string;
+  provider: string; // e.g. "claude" | "codex" — assigned at runtime by assignModelsToAgents()
+  focus: string;
+  enabled: boolean;
+  categories: string[];
+  description: string;
+  system_prompt: string; // Markdown body content for --system-prompt
+}
+
+/** Configuration for the plan orchestrator */
+export interface OrchestratorConfig {
+  enabled: boolean;
+  model: string;
+  timeout: number;
+}
+
+/** Configuration for a model provider (Claude, Codex, etc.) */
+export interface ProviderConfig {
+  enabled: boolean;
+  models: string[];
+}
+
+/** Model provider pool configuration */
+export interface ModelsConfig {
+  providers: Record<string, ProviderConfig>;
+}
+
+// ---------------------------------------------------------------------------
+// State Interfaces
+// ---------------------------------------------------------------------------
+
+/** A single iteration history entry */
+export interface IterationEntry {
+  hash: string;
+  verdict: string;
+  timestamp: string;
+}
+
+/** Iteration tracking state (stored adjacent to plan file) */
+export interface IterationState {
+  current: number;
+  max: number;
+  complexity: string;
+  history: IterationEntry[];
+  graduated: string[];
+  passStreaks: Record<string, number>;
+  lastPlanHash: string;
+}
+
+/** CC-native state stored in context state.json under cc_native key */
+export interface CcNativeState {
+  plan_review?: PlanReviewState;
+  questions_asked?: QuestionsAskedState;
+  stuck_detection?: StuckDetectionState;
+  [key: string]: unknown;
+}
+
+/** Plan review state within cc_native */
+export interface PlanReviewState {
+  plan_hash: string;
+  reviewed_at: string;
+  decision: string;
+  iteration?: {
+    current: number;
+    max: number;
+    complexity: string;
+    latest_verdict?: string;
+  };
+}
+
+/** Questions-asked tracking state */
+export interface QuestionsAskedState {
+  asked: boolean;
+  asked_at: string;
+}
+
+/** Stuck detection state — tracks repeated errors, file edits, and test failures */
+export interface StuckDetectionState {
+  error_hashes: Record<string, number>;
+  file_edits: Record<string, number>;
+  test_failures: number;
+  tool_calls_since_suggestion: number;
+  suggestion_count: number;
+}
+
+// ---------------------------------------------------------------------------
+// Configuration
+// ---------------------------------------------------------------------------
+
+/** Display settings for review output formatting */
+export interface DisplaySettings {
+  maxIssues: number;
+  maxMissingSections: number;
+  maxQuestions: number;
+}
+
+/** Full plan review configuration (from plan-review.config.json) */
+export interface PlanReviewConfig {
+  planReview?: {
+    enabled?: boolean;
+    reviewers?: {
+      codex?: { enabled?: boolean; timeout?: number; model?: string };
+      gemini?: { enabled?: boolean; timeout?: number; model?: string };
+    };
+    agentReview?: {
+      enabled?: boolean;
+      timeout?: number;
+      orchestrator?: { enabled?: boolean; model?: string; timeout?: number };
+      agentSelection?: Record<string, unknown>;
+      complexityCategories?: string[];
+    };
+    display?: Partial<DisplaySettings>;
+    reviewIterations?: Record<string, number>;
+    earlyExitOnAllPass?: boolean;
+  };
+  display?: Partial<DisplaySettings>;
+  [key: string]: unknown;
+}
+
+// ---------------------------------------------------------------------------
+// Reviewer Interface
+// ---------------------------------------------------------------------------
+
+/** Options passed to reviewer implementations */
+export interface ReviewOptions {
+  timeout: number;
+  context_path?: string;
+  session_name?: string;
+}
+
+/** Interface all reviewers must implement */
+export interface Reviewer {
+  review(
+    plan: string,
+    schema: Record<string, unknown>,
+    options: ReviewOptions,
+  ): Promise<ReviewerResult>;
+}
+
+// ---------------------------------------------------------------------------
+// JSON Schemas
+// ---------------------------------------------------------------------------
+
+/** JSON schema for review structured output */
+export const REVIEW_SCHEMA: Record<string, unknown> = {
+  type: "object",
+  properties: {
+    verdict: { type: "string", enum: ["pass", "warn", "fail"] },
+    summary: { type: "string", minLength: 20 },
+    issues: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          severity: { type: "string", enum: ["high", "medium", "low"] },
+          category: { type: "string" },
+          issue: { type: "string" },
+          suggested_fix: { type: "string" },
+          dimension: {
+            type: "string",
+            enum: [
+              "completeness", "simplicity", "security", "performance",
+              "reliability", "maintainability", "testability", "scope",
+              "feasibility", "clarity",
+            ],
+          },
+        },
+        required: ["severity", "category", "issue", "suggested_fix"],
+        additionalProperties: false,
+      },
+    },
+    missing_sections: { type: "array", items: { type: "string" } },
+    questions: { type: "array", items: { type: "string" } },
+  },
+  required: ["verdict", "summary", "issues", "missing_sections", "questions"],
+  additionalProperties: false,
+};
+
+/** JSON schema for orchestrator structured output */
+export const ORCHESTRATOR_SCHEMA: Record<string, unknown> = {
+  type: "object",
+  properties: {
+    complexity: { type: "string", enum: ["simple", "medium", "high"] },
+    category: {
+      type: "string",
+      enum: [
+        "code",
+        "infrastructure",
+        "documentation",
+        "life",
+        "business",
+        "design",
+        "research",
+      ],
+    },
+    selectedAgents: { type: "array", items: { type: "string" } },
+    reasoning: { type: "string" },
+    skipReason: { type: "string" },
+  },
+  required: ["complexity", "category", "selectedAgents", "reasoning"],
+  additionalProperties: false,
+};
+
+// ---------------------------------------------------------------------------
+// Prompt Constants
+// ---------------------------------------------------------------------------
+
+export const REVIEW_PROMPT_PREFIX = `You are a senior staff software engineer acting as a strict plan reviewer.
+
+Review the PLAN below. Focus on:
+- missing steps, unclear assumptions, edge cases
+- security/privacy concerns
+- testing/rollout/rollback completeness
+- operational concerns (observability, failure modes)
+`;
+
+export const AGENT_REVIEW_PROMPT_PREFIX = `# SINGLE-TURN PLAN REVIEW
+
+## CRITICAL: ONE TURN ONLY
+You have exactly ONE response to complete this review. Do NOT attempt multi-step workflows, context queries, or phased analysis. Analyze the plan and output your review immediately.
+
+## YOUR TASK
+Review the plan below from your area of expertise. Then call StructuredOutput with your assessment.
+
+## REQUIRED OUTPUT (all fields must have content)
+Call StructuredOutput with:
+- **verdict**: "pass" (no concerns), "warn" (some concerns), or "fail" (critical issues)
+- **summary**: 2-3 sentences with your overall assessment and key findings (REQUIRED)
+- **issues**: Array of concerns found. Format each as:
+  {"severity": "high/medium/low", "category": "...", "issue": "...", "suggested_fix": "...", "dimension": "..."}
+- **dimension**: Classify each issue into exactly one dimension:
+  completeness, simplicity, security, performance, reliability,
+  maintainability, testability, scope, feasibility, or clarity.
+  Examples: "missing error handling" → reliability, "excessive abstraction" → simplicity,
+  "no test strategy" → testability, "missing deployment steps" → completeness,
+  "unclear interaction between components" → clarity.
+- **missing_sections**: Topics the plan should address but doesn't
+- **questions**: Things that need clarification before implementation
+
+## IMPORTANT RULES
+1. A "warn" verdict MUST include at least one issue explaining why
+2. Summary MUST explain your reasoning, not just "looks good" or empty
+3. Focus on your expertise area (architecture, security, performance, etc.)
+4. Output StructuredOutput NOW - no other tools, no questions, no delays
+5. Return ONLY your top 3 most critical issues. Prioritize high-severity over medium/low. Quality over quantity.
+`;
+
+// ---------------------------------------------------------------------------
+// Display Defaults
+// ---------------------------------------------------------------------------
+
+export const DEFAULT_DISPLAY: DisplaySettings = {
+  maxIssues: 12,
+  maxMissingSections: 12,
+  maxQuestions: 12,
+};
+
+export const DEFAULT_SANITIZATION = {
+  maxSessionIdLength: 32,
+  maxTitleLength: 50,
+};