aiwcli 0.10.2 → 0.11.0

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

@@ -0,0 +1,310 @@
+/**
+ * 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 = "error" | "fail" | "pass" | "skip" | "warn";
+
+/** Decision after aggregating all verdicts */
+export type ReviewDecision = "allow" | "deny";
+
+/** Complexity level assigned by orchestrator */
+export type ComplexityCategory = "high" | "medium" | "simple";
+
+// ---------------------------------------------------------------------------
+// Review Data Structures
+// ---------------------------------------------------------------------------
+
+/** A single issue found during review */
+export interface ReviewIssue {
+  category: string;
+  issue: string;
+  severity: "high" | "low" | "medium";
+  suggested_fix: string;
+}
+
+/** Normalized review data from any reviewer */
+export interface ReviewData {
+  issues: ReviewIssue[];
+  missing_sections: string[];
+  questions: string[];
+  summary: string;
+  summary_source: "default" | "reviewer";
+  verdict: Verdict;
+}
+
+/** Result from a single plan reviewer (Codex, Gemini, or Claude agent) */
+export interface ReviewerResult {
+  data: Record<string, unknown>;
+  err: string;
+  name: string;
+  ok: boolean;
+  raw: string;
+  verdict: Verdict;
+}
+
+/** Result from the plan orchestrator */
+export interface OrchestratorResult {
+  category: string;
+  complexity: ComplexityCategory;
+  error?: string;
+  reasoning: string;
+  selected_agents: string[];
+  skip_reason?: string;
+}
+
+/** Combined result from all review phases */
+export interface CombinedReviewResult {
+  agents: Record<string, ReviewerResult>;
+  cli_reviewers: Record<string, ReviewerResult>;
+  orchestration: null | OrchestratorResult;
+  overall_verdict: Verdict;
+  plan_hash: string;
+  timestamp: string;
+}
+
+/** Result from verdict aggregation */
+export interface ReviewDecisionResult {
+  reason: string; // "fail_veto" | "acceptable" | "no_signal"
+  score: number;
+  should_deny: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Agent & Orchestrator Configuration
+// ---------------------------------------------------------------------------
+
+/** Configuration for a Claude Code review agent */
+export interface AgentConfig {
+  categories: string[];
+  description: string;
+  enabled: boolean;
+  focus: string;
+  model: string;
+  name: string;
+  system_prompt: string; // Markdown body content for --system-prompt
+}
+
+/** Configuration for the plan orchestrator */
+export interface OrchestratorConfig {
+  enabled: boolean;
+  model: string;
+  timeout: number;
+}
+
+// ---------------------------------------------------------------------------
+// State Interfaces
+// ---------------------------------------------------------------------------
+
+/** A single iteration history entry */
+export interface IterationEntry {
+  hash: string;
+  timestamp: string;
+  verdict: string;
+}
+
+/** Iteration tracking state (stored adjacent to plan file) */
+export interface IterationState {
+  complexity: string;
+  current: number;
+  graduated: string[];
+  history: IterationEntry[];
+  max: number;
+}
+
+/** CC-native state stored in context state.json under cc_native key */
+export interface CcNativeState {
+  [key: string]: unknown;
+  plan_review?: PlanReviewState;
+  questions_asked?: QuestionsAskedState;
+}
+
+/** Plan review state within cc_native */
+export interface PlanReviewState {
+  decision: string;
+  iteration?: {
+    complexity: string;
+    current: number;
+    latest_verdict?: string;
+    max: number;
+  };
+  plan_hash: string;
+  reviewed_at: string;
+}
+
+/** Questions-asked tracking state */
+export interface QuestionsAskedState {
+  asked: boolean;
+  asked_at: string;
+}
+
+// ---------------------------------------------------------------------------
+// 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 {
+  [key: string]: unknown;
+  display?: Partial<DisplaySettings>;
+  planReview?: {
+    agentReview?: {
+      agentSelection?: Record<string, unknown>;
+      complexityCategories?: string[];
+      enabled?: boolean;
+      orchestrator?: { enabled?: boolean; model?: string; timeout?: number };
+      timeout?: number;
+    };
+    display?: Partial<DisplaySettings>;
+    earlyExitOnAllPass?: boolean;
+    enabled?: boolean;
+    reviewers?: {
+      codex?: { enabled?: boolean; model?: string; timeout?: number; };
+      gemini?: { enabled?: boolean; model?: string; timeout?: number; };
+    };
+    reviewIterations?: Record<string, number>;
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Reviewer Interface
+// ---------------------------------------------------------------------------
+
+/** Options passed to reviewer implementations */
+export interface ReviewOptions {
+  context_path?: string;
+  session_name?: string;
+  timeout: number;
+}
+
+/** 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" },
+        },
+        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": "..."}
+- **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
+`;
+
+// ---------------------------------------------------------------------------
+// Display Defaults
+// ---------------------------------------------------------------------------
+
+export const DEFAULT_DISPLAY: DisplaySettings = {
+  maxIssues: 12,
+  maxMissingSections: 12,
+  maxQuestions: 12,
+};
+
+export const DEFAULT_SANITIZATION = {
+  maxSessionIdLength: 32,
+  maxTitleLength: 50,
+};

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

@@ -0,0 +1,72 @@
+/**
+ * Pure verdict aggregation logic.
+ * See cc-native-plan-review-spec.md §4.2
+ */
+
+import type { ReviewDecisionResult, Verdict } from "./types.js";
+
+/**
+ * Return the worst verdict from a list.
+ * Order: pass < warn < fail. skip→pass, error→warn.
+ */
+export function worstVerdict(verdicts: Verdict[]): Verdict {
+  const order: Record<Verdict, number> = {
+    pass: 0,
+    warn: 1,
+    fail: 2,
+    skip: 0,
+    error: 1,
+  };
+
+  let worst: Verdict = "pass";
+  for (const v of verdicts) {
+    if ((order[v] ?? 1) > (order[worst] ?? 0)) {
+      worst = v;
+    }
+  }
+
+  // Normalize error → warn
+  if (worst === "error") return "warn";
+  return worst;
+}
+
+/**
+ * Verdict aggregation: fail veto triggers a block.
+ *
+ * Priority order:
+ * 1. Fail Veto: Any fail → deny (ISO 61508 zero-tolerance)
+ * 2. Acceptable: warns are informational only
+ *
+ * Error exclusion: Detectors that produce no signal (error/skip) are excluded
+ * from the denominator.
+ *
+ * @param allVerdicts - List of verdict strings from all reviewers
+ * @returns ReviewDecisionResult with should_deny, reason, and score
+ */
+export function computeReviewDecision(
+  allVerdicts: Verdict[],
+): ReviewDecisionResult {
+  // Exclude non-signal verdicts
+  const signalVerdicts = allVerdicts.filter(
+    (v) => v === "pass" || v === "warn" || v === "fail",
+  );
+
+  if (signalVerdicts.length === 0) {
+    return { should_deny: false, reason: "no_signal", score: 0.0 };
+  }
+
+  // Fail blocks unconditionally
+  const failCount = signalVerdicts.filter((v) => v === "fail").length;
+  if (failCount > 0) {
+    return { should_deny: true, reason: "fail_veto", score: 1.0 };
+  }
+
+  // Warn also blocks — reviewers flagged concerns worth addressing
+  const warnCount = signalVerdicts.filter((v) => v === "warn").length;
+  const warnRatio = warnCount / signalVerdicts.length;
+  if (warnCount > 0) {
+    return { should_deny: true, reason: "warn_block", score: warnRatio };
+  }
+
+  return { should_deny: false, reason: "acceptable", score: 0.0 };
+}

package/dist/templates/cc-native/_cc-native/plan-review.config.json

@@ -4,7 +4,7 @@
     "reviewers": {
       "codex": {
         "enabled": true,
-        "model": "o4-mini",
+        "model": "gpt-5.1-codex-mini",
         "timeout": 120
       },
       "gemini": {
@@ -25,21 +25,25 @@
     "warnThreshold": 0.01,
     "orchestrator": {
       "enabled": true,
-      "model": "haiku",
-      "timeout": 30
+      "model": "opus",
+      "timeout": 60
     },
     "legacyMode": false,
-    "mandatoryAgents": ["handoff-readiness", "clarity-auditor", "skeptic"],
+    "mandatoryAgents": {
+      "always": ["handoff-readiness", "clarity-auditor", "skeptic"],
+      "medium+": ["documentation-philosophy"]
+    },
     "fallbackByComplexity": {
       "simple": 0,
-      "medium": 5,
-      "high": 9
+      "medium": 12,
+      "high": 6
     },
     "reviewIterations": {
       "simple": 1,
       "medium": 1,
       "high": 2
     },
+    "highIssueThreshold": 2,
     "earlyExitOnAllPass": true,
     "display": {
       "maxIssues": 12,
@@ -49,8 +53,8 @@
   },
   "agentSelection": {
     "simple": { "min": 3, "max": 3 },
-    "medium": { "min": 8, "max": 8 },
-    "high": { "min": 12, "max": 12 },
+    "medium": { "min": 12, "max": 12 },
+    "high": { "min": 6, "max": 6 },
     "fallbackCount": 3
   },
   "agentDefaults": {
@@ -67,13 +71,5 @@
   "planContext": {
     "enabled": true,
     "offerClarifyingQuestions": true
-  },
-  "stuckDetection": {
-    "enabled": true,
-    "errorThreshold": 3,
-    "fileEditThreshold": 4,
-    "testFailureThreshold": 3,
-    "cooldown": 10,
-    "maxSuggestions": 3
   }
 }

package/oclif.manifest.json

@@ -416,5 +416,5 @@
       ]
     }
   },
-  "version": "0.10.2"
+  "version": "0.11.0"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "aiwcli",
   "description": "AI Workflow CLI - Command-line interface for AI-powered workflows",
-  "version": "0.10.2",
+  "version": "0.11.0",
   "author": "jofu-tofu",
   "bin": {
     "aiw": "./bin/run.js"

package/dist/lib/template-merger.d.ts

@@ -1,47 +0,0 @@
-/**
- * Content folder types that should be recursively merged rather than skipped.
- * These are the canonical folder names used in templates for organizing content.
- */
-export declare const CONTENT_FOLDER_TYPES: readonly ["agents", "commands", "workflows", "tasks"];
-/**
- * Result of merging content folders
- */
-export interface MergeResult {
-    /** Files that were copied */
-    copiedFiles: string[];
-    /** Directories that were created */
-    createdDirs: string[];
-    /** Files that were skipped (already exist) */
-    skippedFiles: string[];
-}
-/**
- * Recursively find folders matching the method name within a directory tree.
- * This finds folders like `.claude/commands/bmad/` when methodName is 'bmad'.
- *
- * @param dir - Directory to search
- * @param methodName - Method name to look for (e.g., 'bmad', 'gsd')
- * @returns Array of paths to matching folders
- */
-export declare function findMethodFolders(dir: string, methodName: string): Promise<string[]>;
-/**
- * Merge template content into an existing IDE folder.
- * Recursively finds folders matching the method name and merges their content.
- *
- * This enables adding new agents, commands, workflows, and tasks from a template
- * even when the IDE folder (e.g., .claude) already exists.
- *
- * @param templateIdePath - Path to the template's IDE folder (e.g., template/.claude)
- * @param targetIdePath - Path to the target's IDE folder (e.g., project/.claude)
- * @param methodName - Method name to look for (e.g., 'bmad', 'gsd')
- * @returns Merge results
- */
-export declare function mergeTemplateContent(templateIdePath: string, targetIdePath: string, methodName: string): Promise<MergeResult>;
-/**
- * Merge content type folders (agents, commands, workflows, tasks) from template to target.
- * This is an alternative approach that looks for specific folder types rather than method names.
- *
- * @param templateIdePath - Path to the template's IDE folder
- * @param targetIdePath - Path to the target's IDE folder
- * @returns Merge results
- */
-export declare function mergeContentTypeFolders(templateIdePath: string, targetIdePath: string): Promise<MergeResult>;

package/dist/lib/template-merger.js

@@ -1,162 +0,0 @@
-import { promises as fs } from 'node:fs';
-import { join } from 'node:path';
-import { pathExists } from './paths.js';
-/**
- * Content folder types that should be recursively merged rather than skipped.
- * These are the canonical folder names used in templates for organizing content.
- */
-export const CONTENT_FOLDER_TYPES = ['agents', 'commands', 'workflows', 'tasks'];
-/**
- * Recursively find folders matching the method name within a directory tree.
- * This finds folders like `.claude/commands/bmad/` when methodName is 'bmad'.
- *
- * @param dir - Directory to search
- * @param methodName - Method name to look for (e.g., 'bmad', 'gsd')
- * @returns Array of paths to matching folders
- */
-export async function findMethodFolders(dir, methodName) {
-    const results = [];
-    async function scan(currentDir) {
-        try {
-            const entries = await fs.readdir(currentDir, { withFileTypes: true });
-            const directories = entries.filter((entry) => entry.isDirectory());
-            // Process all directories in parallel
-            await Promise.all(directories.map(async (entry) => {
-                const entryPath = join(currentDir, entry.name);
-                if (entry.name === methodName) {
-                    results.push(entryPath);
-                }
-                // Recursively scan subdirectories
-                await scan(entryPath);
-            }));
-        }
-        catch {
-            // Ignore errors (permission issues, etc.)
-        }
-    }
-    await scan(dir);
-    return results;
-}
-/**
- * Recursively merge a source directory into a target directory.
- * Only copies files that don't already exist in the target.
- * Creates directories as needed.
- *
- * @param srcDir - Source directory to copy from
- * @param destDir - Destination directory to copy to
- * @param result - Accumulator for merge results
- */
-async function mergeDirectory(srcDir, destDir, result) {
-    // Create destination directory if it doesn't exist
-    if (!(await pathExists(destDir))) {
-        await fs.mkdir(destDir, { recursive: true });
-        result.createdDirs.push(destDir);
-    }
-    const entries = await fs.readdir(srcDir, { withFileTypes: true });
-    // Process all entries in parallel
-    await Promise.all(entries.map(async (entry) => {
-        const srcPath = join(srcDir, entry.name);
-        const destPath = join(destDir, entry.name);
-        if (entry.isDirectory()) {
-            // Recursively merge subdirectories
-            await mergeDirectory(srcPath, destPath, result);
-            return;
-        }
-        // Copy file if it doesn't exist
-        const exists = await pathExists(destPath);
-        if (exists) {
-            result.skippedFiles.push(destPath);
-        }
-        else {
-            await fs.copyFile(srcPath, destPath);
-            result.copiedFiles.push(destPath);
-        }
-    }));
-}
-/**
- * Merge template content into an existing IDE folder.
- * Recursively finds folders matching the method name and merges their content.
- *
- * This enables adding new agents, commands, workflows, and tasks from a template
- * even when the IDE folder (e.g., .claude) already exists.
- *
- * @param templateIdePath - Path to the template's IDE folder (e.g., template/.claude)
- * @param targetIdePath - Path to the target's IDE folder (e.g., project/.claude)
- * @param methodName - Method name to look for (e.g., 'bmad', 'gsd')
- * @returns Merge results
- */
-export async function mergeTemplateContent(templateIdePath, targetIdePath, methodName) {
-    const result = {
-        copiedFiles: [],
-        createdDirs: [],
-        skippedFiles: [],
-    };
-    // First, copy root-level files from the template IDE folder (e.g., settings.json)
-    // These are files directly in .claude/ that aren't in method-specific subfolders
-    try {
-        const entries = await fs.readdir(templateIdePath, { withFileTypes: true });
-        const rootFiles = entries.filter((entry) => entry.isFile());
-        await Promise.all(rootFiles.map(async (file) => {
-            const srcPath = join(templateIdePath, file.name);
-            const destPath = join(targetIdePath, file.name);
-            // Only copy if it doesn't exist (skip existing behavior)
-            const exists = await pathExists(destPath);
-            if (exists) {
-                result.skippedFiles.push(destPath);
-            }
-            else {
-                await fs.copyFile(srcPath, destPath);
-                result.copiedFiles.push(destPath);
-            }
-        }));
-    }
-    catch {
-        // Ignore errors (permission issues, missing directory, etc.)
-    }
-    // Find all folders matching the method name in the template
-    const methodFolders = await findMethodFolders(templateIdePath, methodName);
-    // Merge all method folders in parallel
-    await Promise.all(methodFolders.map(async (srcMethodFolder) => {
-        // Calculate the relative path from the template IDE folder
-        const relativePath = srcMethodFolder.slice(templateIdePath.length);
-        const destMethodFolder = join(targetIdePath, relativePath);
-        // Merge this method folder into the target
-        await mergeDirectory(srcMethodFolder, destMethodFolder, result);
-    }));
-    return result;
-}
-/**
- * Merge content type folders (agents, commands, workflows, tasks) from template to target.
- * This is an alternative approach that looks for specific folder types rather than method names.
- *
- * @param templateIdePath - Path to the template's IDE folder
- * @param targetIdePath - Path to the target's IDE folder
- * @returns Merge results
- */
-export async function mergeContentTypeFolders(templateIdePath, targetIdePath) {
-    const result = {
-        copiedFiles: [],
-        createdDirs: [],
-        skippedFiles: [],
-    };
-    async function scanAndMerge(srcDir, destDir) {
-        try {
-            const entries = await fs.readdir(srcDir, { withFileTypes: true });
-            const directories = entries.filter((entry) => entry.isDirectory());
-            // Process all directories in parallel
-            await Promise.all(directories.map(async (entry) => {
-                const srcPath = join(srcDir, entry.name);
-                const destPath = join(destDir, entry.name);
-                // Check if this is a content type folder
-                const isContentType = CONTENT_FOLDER_TYPES.includes(entry.name);
-                // Merge content folders, recursively scan other directories
-                await (isContentType ? mergeDirectory(srcPath, destPath, result) : scanAndMerge(srcPath, destPath));
-            }));
-        }
-        catch {
-            // Ignore errors
-        }
-    }
-    await scanAndMerge(templateIdePath, targetIdePath);
-    return result;
-}

package/dist/templates/_shared/hooks/__init__.py

@@ -1,16 +0,0 @@
-"""Shared hooks for AIW CLI templates.
-
-These hooks integrate with Claude Code's hook system to provide:
-- UserPromptSubmit: Context enforcement (ensures work happens in tracked context)
-- PostToolUse: Context monitoring and handoff warnings
-- ExitPlanMode: Plan archival to context
-
-Hooks read JSON input from stdin and output instructions to stdout.
-
-Available hooks:
-- user_prompt_submit.py: Runs on user prompt, enforces context tracking
-- context_monitor.py: Runs on PostToolUse, monitors context and warns when low
-- archive_plan.py: Runs on ExitPlanMode, archives plan to context
-- task_create_capture.py: Runs on TaskCreate, captures task events
-- task_update_capture.py: Runs on TaskUpdate, captures task updates
-"""