prjct-cli 1.8.0 → 1.9.0

package/core/infrastructure/ai-provider.ts

@@ -21,6 +21,7 @@ import { exec } from 'node:child_process'
 import os from 'node:os'
 import path from 'node:path'
 import { promisify } from 'node:util'
+import { compareSemver } from '../schemas/model'
 import { fileExists } from '../utils/fs-helpers'
 import { readProviderCache, writeProviderCache } from '../utils/provider-cache'
 
@@ -58,6 +59,9 @@ export const ClaudeProvider: AIProviderConfig = {
   ignoreFile: '.claudeignore',
   websiteUrl: 'https://www.anthropic.com/claude',
   docsUrl: 'https://docs.anthropic.com/claude-code',
+  defaultModel: 'sonnet',
+  supportedModels: ['opus', 'sonnet', 'haiku'],
+  minCliVersion: '1.0.0',
 }
 
 /**
@@ -77,6 +81,9 @@ export const GeminiProvider: AIProviderConfig = {
   ignoreFile: '.geminiignore',
   websiteUrl: 'https://geminicli.com',
   docsUrl: 'https://geminicli.com/docs',
+  defaultModel: '2.5-flash',
+  supportedModels: ['2.5-pro', '2.5-flash', '2.0-flash'],
+  minCliVersion: '1.0.0',
 }
 
 /**
@@ -100,6 +107,9 @@ export const AntigravityProvider: AIProviderConfig = {
   ignoreFile: '.agentignore', // Assumed
   websiteUrl: 'https://gemini.google.com/app/antigravity',
   docsUrl: 'https://gemini.google.com/app/antigravity',
+  defaultModel: null, // Platform-managed
+  supportedModels: [],
+  minCliVersion: null,
 }
 
 /**
@@ -129,6 +139,9 @@ export const CursorProvider: AIProviderConfig = {
   isProjectLevel: true, // Config is project-level only
   websiteUrl: 'https://cursor.com',
   docsUrl: 'https://cursor.com/docs',
+  defaultModel: null, // Multi-model IDE, user selects
+  supportedModels: [],
+  minCliVersion: null,
 }
 
 /**
@@ -159,6 +172,9 @@ export const WindsurfProvider: AIProviderConfig = {
   isProjectLevel: true, // Config is project-level only
   websiteUrl: 'https://windsurf.com',
   docsUrl: 'https://docs.windsurf.com',
+  defaultModel: null, // Multi-model IDE, user selects
+  supportedModels: [],
+  minCliVersion: null,
 }
 
 /**
@@ -221,14 +237,33 @@ export async function detectProvider(provider: AIProviderName): Promise<Provider
   }
 
   const version = await getCliVersion(config.cliCommand)
+  const versionWarning = validateCliVersion(provider, version || undefined)
 
   return {
     installed: true,
     version: version || undefined,
     path: cliPath,
+    versionWarning: versionWarning || undefined,
   }
 }
 
+/**
+ * Validate that a detected CLI version meets the provider's minimum requirement.
+ * Returns a warning message if the version is below minimum, or null if OK.
+ */
+export function validateCliVersion(
+  provider: AIProviderName,
+  version: string | undefined
+): string | null {
+  const config = Providers[provider]
+  if (!config.minCliVersion || !version) return null
+
+  if (compareSemver(version, config.minCliVersion) < 0) {
+    return `⚠️ ${config.displayName} v${version} is below minimum v${config.minCliVersion}. Some features may not work correctly.`
+  }
+  return null
+}
+
 /**
  * Detect all available CLI-based providers
  * Results are cached to disk with a 10-minute TTL to avoid redundant shell spawns.

package/core/schemas/analysis.ts

@@ -4,6 +4,8 @@
  * Defines the structure for analysis.json - repository analysis.
  */
 
+import type { ModelMetadata } from './model'
+
 export interface CodePattern {
   name: string
   description: string
@@ -28,6 +30,8 @@ export interface AnalysisSchema {
   patterns: CodePattern[]
   antiPatterns: AntiPattern[]
   analyzedAt: string // ISO8601
+  /** Which AI model was used for this analysis (PRJ-265) */
+  modelMetadata?: ModelMetadata
 }
 
 export const DEFAULT_ANALYSIS: Omit<AnalysisSchema, 'projectId'> = {

package/core/schemas/classification.ts

@@ -0,0 +1,91 @@
+/**
+ * Task Classification Schema
+ *
+ * Defines the structure for LLM-based domain classification results.
+ * Replaces hardcoded keyword lists with structured classification output.
+ *
+ * @see PRJ-299
+ */
+
+import { z } from 'zod'
+
+// =============================================================================
+// Classification Schemas
+// =============================================================================
+
+export const ClassificationDomainSchema = z.enum([
+  'frontend',
+  'backend',
+  'database',
+  'devops',
+  'testing',
+  'docs',
+  'uxui',
+  'general',
+])
+
+export const TaskClassificationSchema = z.object({
+  /** Primary domain for this task */
+  primaryDomain: ClassificationDomainSchema,
+  /** Secondary domains that are also relevant */
+  secondaryDomains: z.array(ClassificationDomainSchema),
+  /** Confidence in the classification (0-1) */
+  confidence: z.number().min(0).max(1),
+  /** Glob patterns for relevant files */
+  filePatterns: z.array(z.string()),
+  /** Agent names that should handle this task */
+  relevantAgents: z.array(z.string()),
+})
+
+export const ClassificationCacheEntrySchema = z.object({
+  /** The classification result */
+  classification: TaskClassificationSchema,
+  /** When this was classified */
+  classifiedAt: z.string(),
+  /** How this was classified */
+  source: z.enum(['cache', 'history', 'llm', 'heuristic']),
+  /** Hash of the task description for cache lookup */
+  descriptionHash: z.string(),
+  /** Project ID this classification belongs to */
+  projectId: z.string(),
+})
+
+export const ClassificationCacheSchema = z.object({
+  /** Cached classifications keyed by descriptionHash */
+  entries: z.record(z.string(), ClassificationCacheEntrySchema),
+  /** Confirmed patterns from successful task completions */
+  confirmedPatterns: z.array(
+    z.object({
+      descriptionHash: z.string(),
+      classification: TaskClassificationSchema,
+      confirmedAt: z.string(),
+      taskDescription: z.string(),
+    })
+  ),
+})
+
+// =============================================================================
+// Inferred Types
+// =============================================================================
+
+export type ClassificationDomain = z.infer<typeof ClassificationDomainSchema>
+export type TaskClassification = z.infer<typeof TaskClassificationSchema>
+export type ClassificationCacheEntry = z.infer<typeof ClassificationCacheEntrySchema>
+export type ClassificationCache = z.infer<typeof ClassificationCacheSchema>
+
+// =============================================================================
+// Defaults
+// =============================================================================
+
+export const DEFAULT_CLASSIFICATION_CACHE: ClassificationCache = {
+  entries: {},
+  confirmedPatterns: [],
+}
+
+export const GENERAL_CLASSIFICATION: TaskClassification = {
+  primaryDomain: 'general',
+  secondaryDomains: [],
+  confidence: 0.3,
+  filePatterns: ['**/*.ts', '**/*.js'],
+  relevantAgents: [],
+}

package/core/schemas/index.ts

@@ -16,10 +16,16 @@
 export * from './agents'
 // Analysis
 export * from './analysis'
+// Classification (LLM-based domain detection)
+export * from './classification'
 // Ideas
 export * from './ideas'
 // Issues (local cache of issue tracker issues)
 export * from './issues'
+// LLM output schemas (structured response validation)
+export * from './llm-output'
+// Model specification (AI provider model tracking)
+export * from './model'
 // Outcomes
 export * from './outcomes'
 // Permissions

package/core/schemas/llm-output.ts

@@ -0,0 +1,170 @@
+/**
+ * LLM Output Schemas
+ *
+ * Zod schemas for all LLM prompt response types.
+ * These schemas are:
+ * 1. Injected into prompts as explicit format instructions
+ * 2. Used to validate LLM responses before storage or use
+ * 3. Define the contract between prompts and response handling
+ *
+ * @see PRJ-264
+ */
+
+import { z } from 'zod'
+import { ClassificationDomainSchema, TaskClassificationSchema } from './classification'
+
+// =============================================================================
+// Re-export classification schema (it IS an LLM output schema)
+// =============================================================================
+
+export { TaskClassificationSchema } from './classification'
+
+// =============================================================================
+// Agent Assignment Schema
+// =============================================================================
+
+/** LLM response when selecting which agent should handle a task */
+export const AgentAssignmentSchema = z.object({
+  /** Agent file name (e.g., "backend.md", "frontend.md") */
+  agentName: z.string(),
+  /** Why this agent was selected */
+  reasoning: z.string(),
+  /** Confidence in the assignment (0-1) */
+  confidence: z.number().min(0).max(1),
+})
+
+// =============================================================================
+// Subtask Breakdown Schema
+// =============================================================================
+
+/** LLM response when breaking a task into subtasks */
+export const SubtaskBreakdownSchema = z.object({
+  /** Subtasks in execution order */
+  subtasks: z.array(
+    z.object({
+      /** Short description of the subtask */
+      description: z.string(),
+      /** Domain this subtask belongs to */
+      domain: ClassificationDomainSchema,
+      /** Suggested agent for this subtask */
+      agent: z.string(),
+      /** IDs of subtasks this depends on (by index, 0-based) */
+      dependsOn: z.array(z.number()),
+    })
+  ),
+  /** Estimated total effort */
+  effort: z.enum(['low', 'medium', 'high']),
+})
+
+// =============================================================================
+// Schema-to-Prompt Serializer
+// =============================================================================
+
+/**
+ * Registry of output schemas keyed by prompt type.
+ * Used by prompt-builder to inject the correct schema into each prompt.
+ */
+export const OUTPUT_SCHEMAS: Record<string, { schema: z.ZodTypeAny; example: string }> = {
+  classification: {
+    schema: TaskClassificationSchema,
+    example: JSON.stringify(
+      {
+        primaryDomain: 'backend',
+        secondaryDomains: ['database'],
+        confidence: 0.9,
+        filePatterns: ['src/api/**'],
+        relevantAgents: ['backend.md'],
+      },
+      null,
+      2
+    ),
+  },
+  agentAssignment: {
+    schema: AgentAssignmentSchema,
+    example: JSON.stringify(
+      {
+        agentName: 'backend.md',
+        reasoning: 'Task involves API endpoint creation',
+        confidence: 0.85,
+      },
+      null,
+      2
+    ),
+  },
+  subtaskBreakdown: {
+    schema: SubtaskBreakdownSchema,
+    example: JSON.stringify(
+      {
+        subtasks: [
+          {
+            description: 'Add schema validation',
+            domain: 'backend',
+            agent: 'backend.md',
+            dependsOn: [],
+          },
+          {
+            description: 'Add unit tests',
+            domain: 'testing',
+            agent: 'testing.md',
+            dependsOn: [0],
+          },
+        ],
+        effort: 'medium',
+      },
+      null,
+      2
+    ),
+  },
+}
+
+/**
+ * Render a schema as prompt instructions.
+ * Returns a markdown block that tells the LLM exactly what format to use.
+ */
+export function renderSchemaForPrompt(schemaType: string): string | null {
+  const entry = OUTPUT_SCHEMAS[schemaType]
+  if (!entry) return null
+
+  return `## OUTPUT FORMAT
+
+Return ONLY valid JSON matching this schema (no markdown, no explanation):
+
+\`\`\`json
+${entry.example}
+\`\`\`
+
+Fields:
+${describeSchema(entry.schema)}`
+}
+
+/**
+ * Extract field descriptions from a Zod object schema.
+ */
+function describeSchema(schema: z.ZodTypeAny): string {
+  if (schema instanceof z.ZodObject) {
+    const shape = schema.shape as Record<string, z.ZodTypeAny>
+    return Object.entries(shape)
+      .map(([key, field]) => `- \`${key}\`: ${describeField(field)}`)
+      .join('\n')
+  }
+  return '(see example above)'
+}
+
+/**
+ * Describe a single Zod field type for prompt injection.
+ */
+function describeField(field: z.ZodTypeAny): string {
+  if (field instanceof z.ZodString) return 'string'
+  if (field instanceof z.ZodNumber) return 'number'
+  if (field instanceof z.ZodEnum) return `one of: ${(field.options as string[]).join(', ')}`
+  if (field instanceof z.ZodArray) return `array of ${describeField(field.element)}`
+  if (field instanceof z.ZodObject) return 'object'
+  return 'any'
+}
+
+// =============================================================================
+// Inferred Types
+// =============================================================================
+
+export type AgentAssignment = z.infer<typeof AgentAssignmentSchema>
+export type SubtaskBreakdown = z.infer<typeof SubtaskBreakdownSchema>

package/core/schemas/model.ts

@@ -0,0 +1,153 @@
+/**
+ * Model Schema
+ *
+ * Defines model specification types for AI providers.
+ * Records which model was used for each analysis and task,
+ * enabling consistency tracking and mismatch warnings.
+ *
+ * @see PRJ-265
+ */
+
+import { z } from 'zod'
+
+// =============================================================================
+// Provider-Specific Model Identifiers
+// =============================================================================
+
+/** Claude model identifiers (short names matching agent frontmatter convention) */
+export const ClaudeModelSchema = z.enum(['opus', 'sonnet', 'haiku'])
+
+/** Gemini model identifiers */
+export const GeminiModelSchema = z.enum(['2.5-pro', '2.5-flash', '2.0-flash'])
+
+/** Generic model identifier - allows any string for future providers */
+export const AIModelSchema = z.string().min(1)
+
+// =============================================================================
+// Supported Models Per Provider
+// =============================================================================
+
+export const SUPPORTED_MODELS: Record<string, readonly string[]> = {
+  claude: ['opus', 'sonnet', 'haiku'],
+  gemini: ['2.5-pro', '2.5-flash', '2.0-flash'],
+  cursor: [], // Multi-model IDE, user selects model
+  windsurf: [], // Multi-model IDE, user selects model
+  antigravity: [], // Platform-managed
+} as const
+
+export const DEFAULT_MODELS: Record<string, string> = {
+  claude: 'sonnet',
+  gemini: '2.5-flash',
+} as const
+
+// =============================================================================
+// Minimum CLI Versions
+// =============================================================================
+
+export const MIN_CLI_VERSIONS: Record<string, string> = {
+  claude: '1.0.0',
+  gemini: '1.0.0',
+} as const
+
+// =============================================================================
+// Model Metadata - Recorded Per Operation
+// =============================================================================
+
+/** Model metadata recorded with each analysis or task */
+export const ModelMetadataSchema = z.object({
+  /** Provider name (e.g., 'claude', 'gemini') */
+  provider: z.string(),
+  /** Model identifier (e.g., 'opus', 'sonnet', '2.5-pro') */
+  model: z.string(),
+  /** CLI version used */
+  cliVersion: z.string().optional(),
+  /** When this was recorded */
+  recordedAt: z.string(),
+})
+
+// =============================================================================
+// Model Configuration - Per Project
+// =============================================================================
+
+/** Per-project model preference */
+export const ModelPreferenceSchema = z.object({
+  /** Preferred model for this project */
+  preferredModel: z.string().optional(),
+  /** Model used for last analysis (for mismatch detection) */
+  lastAnalysisModel: ModelMetadataSchema.optional(),
+})
+
+// =============================================================================
+// Inferred Types
+// =============================================================================
+
+export type ClaudeModel = z.infer<typeof ClaudeModelSchema>
+export type GeminiModel = z.infer<typeof GeminiModelSchema>
+export type ModelMetadata = z.infer<typeof ModelMetadataSchema>
+export type ModelPreference = z.infer<typeof ModelPreferenceSchema>
+
+// =============================================================================
+// Validation Helpers
+// =============================================================================
+
+/** Check if a model is valid for a given provider */
+export function isValidModelForProvider(provider: string, model: string): boolean {
+  const supported = SUPPORTED_MODELS[provider]
+  if (!supported || supported.length === 0) return true // No restriction for multi-model IDEs
+  return supported.includes(model)
+}
+
+/** Get the default model for a provider */
+export function getDefaultModel(provider: string): string | null {
+  return DEFAULT_MODELS[provider] ?? null
+}
+
+/** Get supported models for a provider */
+export function getSupportedModels(provider: string): readonly string[] {
+  return SUPPORTED_MODELS[provider] ?? []
+}
+
+/** Get minimum CLI version for a provider */
+export function getMinCliVersion(provider: string): string | null {
+  return MIN_CLI_VERSIONS[provider] ?? null
+}
+
+/**
+ * Compare semver versions. Returns:
+ *  -1 if a < b
+ *   0 if a == b
+ *   1 if a > b
+ */
+export function compareSemver(a: string, b: string): -1 | 0 | 1 {
+  const pa = a.split('.').map(Number)
+  const pb = b.split('.').map(Number)
+  for (let i = 0; i < 3; i++) {
+    const va = pa[i] ?? 0
+    const vb = pb[i] ?? 0
+    if (va < vb) return -1
+    if (va > vb) return 1
+  }
+  return 0
+}
+
+/** Check if a CLI version meets minimum requirements */
+export function meetsMinVersion(provider: string, version: string): boolean {
+  const min = MIN_CLI_VERSIONS[provider]
+  if (!min) return true // No minimum defined
+  return compareSemver(version, min) >= 0
+}
+
+/**
+ * Check for model mismatch between analysis and current task.
+ * Returns a warning message if the models differ, or null if they match.
+ */
+export function checkModelMismatch(
+  analysisModel: ModelMetadata | undefined,
+  taskModel: ModelMetadata | undefined
+): string | null {
+  if (!analysisModel || !taskModel) return null
+  if (analysisModel.provider !== taskModel.provider || analysisModel.model !== taskModel.model) {
+    return `⚠️ Model mismatch: analysis used ${analysisModel.provider}/${analysisModel.model}, but task is using ${taskModel.provider}/${taskModel.model}. Results may differ.`
+  }
+  return null
+}

package/core/schemas/state.ts

@@ -9,6 +9,7 @@
  */
 
 import { z } from 'zod'
+import { ModelMetadataSchema } from './model'
 
 // =============================================================================
 // Zod Schemas - Source of Truth
@@ -90,6 +91,8 @@ export const CurrentTaskSchema = z.object({
   // Fibonacci estimation
   estimatedPoints: z.number().optional(), // Fibonacci: 1,2,3,5,8,13,21
   estimatedMinutes: z.number().optional(), // Derived from points
+  // Model specification - which AI model was used (PRJ-265)
+  modelMetadata: ModelMetadataSchema.optional(),
 })
 
 export const PreviousTaskSchema = z.object({

package/core/types/config.ts

@@ -78,6 +78,8 @@ export interface ProjectSettings {
   autoCommit?: boolean
   commitFooter?: string
   branchNaming?: string
+  /** Preferred AI model for this project (e.g., 'opus', 'sonnet', '2.5-pro') */
+  preferredModel?: string
 }
 
 /**

package/core/types/provider.ts

@@ -78,6 +78,15 @@ export interface AIProviderConfig {
 
   /** URL for provider documentation */
   docsUrl: string
+
+  /** Default model for this provider (e.g., 'sonnet', '2.5-flash'). Null for multi-model IDEs */
+  defaultModel: string | null
+
+  /** Supported model identifiers. Empty array for multi-model IDEs (user selects model) */
+  supportedModels: readonly string[]
+
+  /** Minimum CLI version required. Null for non-CLI providers */
+  minCliVersion: string | null
 }
 
 /**
@@ -92,6 +101,9 @@ export interface ProviderDetectionResult {
 
   /** Path to the CLI executable */
   path?: string
+
+  /** Warning if CLI version is below minimum requirement */
+  versionWarning?: string
 }
 
 /**