prjct-cli 1.7.5 → 1.9.0

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/command-context.ts

@@ -0,0 +1,29 @@
+/**
+ * Command Context Schema
+ *
+ * Zod schemas for command-context.config.json.
+ * Controls which context sections (agents, patterns, checklists, modules)
+ * get injected into prompts for each command.
+ *
+ * @see PRJ-298
+ */
+
+import { z } from 'zod'
+
+export const CommandContextEntrySchema = z.object({
+  agents: z.boolean(),
+  patterns: z.boolean(),
+  checklist: z.boolean(),
+  modules: z.array(z.string()),
+})
+
+export const CommandContextConfigSchema = z.object({
+  version: z.string(),
+  description: z.string().optional(),
+  commands: z.record(z.string(), CommandContextEntrySchema).refine((commands) => '*' in commands, {
+    message: 'Config must include a "*" wildcard entry for unknown commands',
+  }),
+})
+
+export type CommandContextEntry = z.infer<typeof CommandContextEntrySchema>
+export type CommandContextConfig = z.infer<typeof CommandContextConfigSchema>

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/performance.ts

@@ -0,0 +1,128 @@
+/**
+ * Performance Schema
+ *
+ * Defines metric types for the PerformanceTracker service.
+ * Uses JSONL storage (append-only) with rotation at 5MB.
+ *
+ * @see PRJ-297
+ */
+
+import { z } from 'zod'
+
+// =============================================================================
+// Metric Schemas
+// =============================================================================
+
+export const MetricNameSchema = z.enum([
+  'startup_time',
+  'heap_used',
+  'heap_total',
+  'rss',
+  'external_memory',
+  'context_correctness',
+  'subtask_handoff',
+  'analysis_state',
+  'token_usage',
+  'command_duration',
+])
+
+export const MemorySnapshotSchema = z.object({
+  heapUsed: z.number(),
+  heapTotal: z.number(),
+  rss: z.number(),
+  external: z.number(),
+})
+
+export const PerformanceMetricSchema = z.object({
+  timestamp: z.string(),
+  metric: MetricNameSchema,
+  value: z.number(),
+  unit: z.string(),
+  context: z.record(z.string(), z.unknown()).optional(),
+})
+
+export const ContextCorrectnessSchema = z.object({
+  timestamp: z.string(),
+  metric: z.literal('context_correctness'),
+  taskId: z.string(),
+  receivedSync: z.boolean(),
+  syncFieldsInjected: z.array(z.string()).optional(),
+  tokensBudgetUsed: z.number().optional(),
+  tokensBudgetTotal: z.number().optional(),
+})
+
+export const SubtaskHandoffSchema = z.object({
+  timestamp: z.string(),
+  metric: z.literal('subtask_handoff'),
+  taskId: z.string(),
+  subtaskId: z.string(),
+  outputPopulated: z.boolean(),
+})
+
+export const AnalysisStateSchema = z.object({
+  timestamp: z.string(),
+  metric: z.literal('analysis_state'),
+  state: z.enum(['draft', 'verified', 'sealed']),
+  commitHash: z.string(),
+})
+
+/** Union of all metric entry types stored in performance.jsonl */
+export const PerformanceEntrySchema = z.union([
+  PerformanceMetricSchema,
+  ContextCorrectnessSchema,
+  SubtaskHandoffSchema,
+  AnalysisStateSchema,
+])
+
+// =============================================================================
+// Report Schemas
+// =============================================================================
+
+export const MetricSummarySchema = z.object({
+  avg: z.number(),
+  min: z.number(),
+  max: z.number(),
+  count: z.number(),
+  unit: z.string(),
+})
+
+export const PerformanceReportSchema = z.object({
+  period: z.string(),
+  startup: MetricSummarySchema.optional(),
+  memory: z
+    .object({
+      avgHeapMB: z.number(),
+      peakHeapMB: z.number(),
+      avgRssMB: z.number(),
+    })
+    .optional(),
+  contextCorrectness: z
+    .object({
+      total: z.number(),
+      receivedSync: z.number(),
+      rate: z.number(),
+    })
+    .optional(),
+  subtaskHandoff: z
+    .object({
+      total: z.number(),
+      outputPopulated: z.number(),
+      rate: z.number(),
+    })
+    .optional(),
+  commandDurations: z.record(z.string(), MetricSummarySchema).optional(),
+})
+
+// =============================================================================
+// Inferred Types
+// =============================================================================
+
+export type MetricName = z.infer<typeof MetricNameSchema>
+export type MemorySnapshot = z.infer<typeof MemorySnapshotSchema>
+export type PerformanceMetric = z.infer<typeof PerformanceMetricSchema>
+export type ContextCorrectness = z.infer<typeof ContextCorrectnessSchema>
+export type SubtaskHandoff = z.infer<typeof SubtaskHandoffSchema>
+export type AnalysisState = z.infer<typeof AnalysisStateSchema>
+export type PerformanceEntry = z.infer<typeof PerformanceEntrySchema>
+export type MetricSummary = z.infer<typeof MetricSummarySchema>
+export type PerformanceReport = z.infer<typeof PerformanceReportSchema>

package/core/schemas/state.ts

@@ -9,6 +9,7 @@
  */
 
 import { z } from 'zod'
+import { ModelMetadataSchema } from './model'
 
 // =============================================================================
 // Zod Schemas - Source of Truth
@@ -62,6 +63,9 @@ export const SubtaskSchema = z.object({
   summary: SubtaskSummarySchema.optional(), // Full summary for context handoff
   skipReason: z.string().optional(), // Why this subtask was skipped
   blockReason: z.string().optional(), // What is blocking this subtask
+  // Fibonacci estimation
+  estimatedPoints: z.number().optional(), // Fibonacci: 1,2,3,5,8,13,21
+  estimatedMinutes: z.number().optional(), // Derived from points
 })
 
 // Subtask progress tracking
@@ -84,6 +88,11 @@ export const CurrentTaskSchema = z.object({
   // Linear integration - bidirectional sync
   linearId: z.string().optional(), // "PRJ-123" - Linear identifier
   linearUuid: z.string().optional(), // Linear internal UUID for API calls
+  // 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/storage/state-storage.ts

@@ -196,6 +196,27 @@ class StateStorage extends StorageManager<StateJson> {
     return currentTask
   }
 
+  /**
+   * Update fields on the current task (partial update)
+   */
+  async updateCurrentTask(
+    projectId: string,
+    fields: Partial<CurrentTask>
+  ): Promise<CurrentTask | null> {
+    const state = await this.read(projectId)
+    if (!state.currentTask) return null
+
+    const updated: CurrentTask = { ...state.currentTask, ...fields }
+
+    await this.update(projectId, (s) => ({
+      ...s,
+      currentTask: updated,
+      lastUpdated: getTimestamp(),
+    }))
+
+    return updated
+  }
+
   /**
    * Complete current task
    */

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
 }
 
 /**