prjct-cli 0.11.4 → 0.12.0

package/core/agentic/chain-of-thought.ts

@@ -0,0 +1,228 @@
+/**
+ * Chain of Thought Reasoning
+ * Implements step-by-step reasoning for complex commands
+ *
+ * @module agentic/chain-of-thought
+ * @version 1.0.0
+ */
+
+interface Context {
+  projectId?: string | null
+  projectPath: string
+  params: Record<string, unknown>
+}
+
+interface State {
+  now?: string | null
+  next?: string | null
+  shipped?: string | null
+  analysis?: string | null
+  [key: string]: unknown
+}
+
+interface ReasoningStep {
+  step: string
+  passed: boolean
+  details?: string
+}
+
+interface ReasoningResult {
+  commandName: string
+  reasoning: {
+    steps: ReasoningStep[]
+    allPassed: boolean
+    criticalIssues: string[]
+  } | null
+  plan: string[]
+  confidence: number
+}
+
+/**
+ * Commands that require chain of thought reasoning
+ */
+const REASONING_REQUIRED_COMMANDS = ['ship', 'feature', 'spec', 'cleanup', 'migrate']
+
+/**
+ * Check if command requires reasoning
+ */
+function requiresReasoning(commandName: string): boolean {
+  return REASONING_REQUIRED_COMMANDS.includes(commandName)
+}
+
+/**
+ * Reason through a command before execution
+ */
+async function reason(commandName: string, context: Context, state: State): Promise<ReasoningResult> {
+  const steps: ReasoningStep[] = []
+  const plan: string[] = []
+  const criticalIssues: string[] = []
+
+  switch (commandName) {
+    case 'ship':
+      // Check prerequisites
+      if (state.now && !state.now.includes('No current task')) {
+        steps.push({ step: 'Has active task', passed: true })
+      } else {
+        steps.push({ step: 'Has active task', passed: false, details: 'No active task to ship' })
+        criticalIssues.push('No active task')
+      }
+
+      // Check if there's content to ship
+      if (state.shipped) {
+        steps.push({ step: 'Shipped log accessible', passed: true })
+      } else {
+        steps.push({ step: 'Shipped log accessible', passed: false, details: 'shipped.md not found' })
+      }
+
+      // Plan
+      plan.push('Read current task from now.md')
+      plan.push('Calculate duration')
+      plan.push('Append to shipped.md')
+      plan.push('Clear now.md')
+      plan.push('Update metrics')
+      break
+
+    case 'feature':
+      // Check if description provided
+      if (context.params.description || context.params.feature) {
+        steps.push({ step: 'Has feature description', passed: true })
+      } else {
+        steps.push({ step: 'Has feature description', passed: false, details: 'No description provided' })
+        criticalIssues.push('Missing feature description')
+      }
+
+      // Check roadmap accessibility
+      if (state.analysis) {
+        steps.push({ step: 'Project analyzed', passed: true })
+      } else {
+        steps.push({ step: 'Project analyzed', passed: false, details: 'Run /p:sync first' })
+      }
+
+      // Plan
+      plan.push('Parse feature description')
+      plan.push('Generate tasks breakdown')
+      plan.push('Add to roadmap.md')
+      plan.push('Add tasks to next.md')
+      plan.push('Suggest starting first task')
+      break
+
+    case 'spec':
+      // Check if feature name provided
+      if (context.params.feature || context.params.name) {
+        steps.push({ step: 'Has spec name', passed: true })
+      } else {
+        steps.push({ step: 'Has spec name', passed: false, details: 'No spec name provided' })
+        criticalIssues.push('Missing spec name')
+      }
+
+      // Plan
+      plan.push('Generate spec template')
+      plan.push('Analyze requirements')
+      plan.push('Create spec file')
+      plan.push('Link to roadmap')
+      break
+
+    case 'cleanup':
+      // Check for analysis
+      if (state.analysis) {
+        steps.push({ step: 'Has code analysis', passed: true })
+      } else {
+        steps.push({ step: 'Has code analysis', passed: false, details: 'Run /p:analyze first' })
+      }
+
+      // Plan
+      plan.push('Scan for unused code')
+      plan.push('Identify dead imports')
+      plan.push('List files to clean')
+      plan.push('Show preview')
+      plan.push('Wait for approval')
+      plan.push('Execute cleanup')
+      break
+
+    case 'migrate':
+      // Always warn for migrate
+      steps.push({
+        step: 'Migration safety check',
+        passed: true,
+        details: 'Will require manual approval',
+      })
+
+      // Plan
+      plan.push('Analyze current state')
+      plan.push('Generate migration plan')
+      plan.push('Show affected files')
+      plan.push('Request approval')
+      plan.push('Execute migration')
+      plan.push('Verify results')
+      break
+
+    default:
+      // Generic plan
+      plan.push('Execute command')
+      break
+  }
+
+  // Calculate confidence
+  const passedSteps = steps.filter((s) => s.passed).length
+  const totalSteps = steps.length
+  const confidence = totalSteps > 0 ? passedSteps / totalSteps : 1
+
+  return {
+    commandName,
+    reasoning:
+      steps.length > 0
+        ? {
+            steps,
+            allPassed: criticalIssues.length === 0,
+            criticalIssues,
+          }
+        : null,
+    plan,
+    confidence,
+  }
+}
+
+/**
+ * Format reasoning plan for display
+ */
+function formatPlan(result: ReasoningResult): string {
+  const lines: string[] = []
+
+  lines.push(`📋 Chain of Thought: ${result.commandName}`)
+  lines.push('')
+
+  if (result.reasoning) {
+    lines.push('Steps:')
+    result.reasoning.steps.forEach((step) => {
+      const icon = step.passed ? '✅' : '❌'
+      lines.push(`  ${icon} ${step.step}`)
+      if (step.details) {
+        lines.push(`      ${step.details}`)
+      }
+    })
+    lines.push('')
+
+    if (result.reasoning.criticalIssues.length > 0) {
+      lines.push('Critical Issues:')
+      result.reasoning.criticalIssues.forEach((issue) => {
+        lines.push(`  ⚠️  ${issue}`)
+      })
+      lines.push('')
+    }
+  }
+
+  if (result.plan.length > 0) {
+    lines.push('Plan:')
+    result.plan.forEach((step, i) => {
+      lines.push(`  ${i + 1}. ${step}`)
+    })
+    lines.push('')
+  }
+
+  lines.push(`Confidence: ${Math.round(result.confidence * 100)}%`)
+
+  return lines.join('\n')
+}
+
+export { requiresReasoning, reason, formatPlan, REASONING_REQUIRED_COMMANDS }
+export default { requiresReasoning, reason, formatPlan }

package/core/agentic/command-executor/command-executor.ts

@@ -0,0 +1,384 @@
+/**
+ * Command Executor Class
+ * Orchestrates command execution with agentic delegation.
+ */
+
+import path from 'path'
+import os from 'os'
+import templateLoader from '../template-loader'
+import contextBuilder from '../context-builder'
+import promptBuilder from '../prompt-builder'
+import toolRegistry from '../tool-registry'
+import { validate, formatError } from '../validation-rules'
+import loopDetector from '../loop-detector'
+import chainOfThought from '../chain-of-thought'
+import semanticCompression from '../semantic-compression'
+import responseTemplates from '../response-templates'
+import memorySystem from '../memory-system'
+import groundTruth from '../ground-truth'
+import thinkBlocks from '../think-blocks'
+import parallelTools from '../parallel-tools'
+import planMode from '../plan-mode'
+import { signalStart, signalEnd } from './status-signal'
+import type { ExecutionResult, SimpleExecutionResult, ExecutionToolsFn } from './types'
+
+export class CommandExecutor {
+  /**
+   * Signal that a command is running (for status line)
+   */
+  signalStart(commandName: string): void {
+    signalStart(commandName)
+  }
+
+  /**
+   * Signal that command has finished (for status line)
+   */
+  signalEnd(): void {
+    signalEnd()
+  }
+
+  /**
+   * Execute a prjct command with full agentic delegation
+   */
+  async execute(
+    commandName: string,
+    params: Record<string, unknown>,
+    projectPath: string
+  ): Promise<ExecutionResult> {
+    // Signal start for status line
+    this.signalStart(commandName)
+
+    // Context for loop detection
+    const loopContext = (params.task as string) || (params.description as string) || ''
+
+    // Check if we're in a loop BEFORE attempting
+    if (loopDetector.shouldEscalate(commandName, loopContext)) {
+      const escalation = loopDetector.getEscalationInfo(commandName, loopContext)
+      this.signalEnd()
+      return {
+        success: false,
+        error: escalation?.message,
+        escalation,
+        isLoopDetected: true,
+        suggestion: escalation?.suggestion,
+      }
+    }
+
+    try {
+      // 1. Load template
+      const template = await templateLoader.load(commandName)
+
+      // 2. Build METADATA context only (lazy loading - no file reads yet)
+      const metadataContext = await contextBuilder.build(projectPath, params)
+
+      // 2.5. VALIDATE: Pre-flight checks with specific errors
+      const validation = await validate(commandName, metadataContext as unknown as Parameters<typeof validate>[1])
+      if (!validation.valid) {
+        this.signalEnd()
+        return {
+          success: false,
+          error: formatError(validation),
+          validation,
+          isValidationError: true,
+        }
+      }
+
+      // 2.55. P3.4 PLAN MODE: Check if command requires planning
+      const requiresPlanning = planMode.requiresPlanning(commandName)
+      const isDestructive = planMode.isDestructive(commandName)
+      const isInPlanningMode = planMode.isInPlanningMode(metadataContext.projectId!)
+
+      // Start planning mode if required and not already in it
+      let activePlan = null
+      if (requiresPlanning && !isInPlanningMode && !params.skipPlanning) {
+        activePlan = planMode.startPlanning(metadataContext.projectId!, commandName, params)
+      } else if (isInPlanningMode) {
+        activePlan = planMode.getActivePlan(metadataContext.projectId!)
+      }
+
+      // 2.6. GROUND TRUTH: Verify actual state before critical operations
+      let groundTruthResult = null
+      if (groundTruth.requiresVerification(commandName)) {
+        const preState = await contextBuilder.loadStateForCommand(metadataContext, commandName)
+        groundTruthResult = await groundTruth.verify(
+          commandName,
+          metadataContext as unknown as Parameters<typeof groundTruth.verify>[1],
+          preState
+        )
+
+        // Log warnings but don't block (user can override)
+        if (!groundTruthResult.verified && groundTruthResult.warnings.length > 0) {
+          console.log(groundTruth.formatWarnings(groundTruthResult))
+        }
+      }
+
+      // 2.7. THINK BLOCKS (P3.1): Dynamic reasoning based on triggers
+      let thinkBlock = null
+      const preThinkState =
+        groundTruthResult?.actual || (await contextBuilder.loadStateForCommand(metadataContext, commandName))
+      const thinkTrigger = thinkBlocks.detectTrigger(
+        commandName,
+        metadataContext as unknown as Parameters<typeof thinkBlocks.detectTrigger>[1],
+        preThinkState as Parameters<typeof thinkBlocks.detectTrigger>[2]
+      )
+      if (thinkTrigger) {
+        thinkBlock = await thinkBlocks.generate(
+          thinkTrigger,
+          commandName,
+          metadataContext as unknown as Parameters<typeof thinkBlocks.generate>[2],
+          preThinkState as Parameters<typeof thinkBlocks.generate>[3]
+        )
+
+        // Log think block if in debug mode
+        if (process.env.PRJCT_DEBUG === 'true') {
+          console.log(thinkBlocks.format(thinkBlock, true))
+        }
+      }
+
+      // 2.8. CHAIN OF THOUGHT: Reasoning for critical commands
+      let reasoning = null
+      if (chainOfThought.requiresReasoning(commandName)) {
+        const reasoningState = await contextBuilder.loadStateForCommand(metadataContext, commandName)
+        reasoning = await chainOfThought.reason(
+          commandName,
+          metadataContext as unknown as Parameters<typeof chainOfThought.reason>[1],
+          reasoningState as Parameters<typeof chainOfThought.reason>[2]
+        )
+
+        // If reasoning shows critical issues, warn but continue
+        if (reasoning.reasoning && !reasoning.reasoning.allPassed) {
+          console.log('⚠️  Chain of Thought detected issues:')
+          console.log(chainOfThought.formatPlan(reasoning))
+        }
+      }
+
+      // 3. AGENTIC: Claude decides agent assignment via templates
+      let context: Record<string, unknown> = metadataContext as unknown as Record<string, unknown>
+
+      // Provide agent info to context so Claude can delegate
+      context = {
+        ...context,
+        agentsPath: path.join(os.homedir(), '.prjct-cli', 'projects', metadataContext.projectId || '', 'agents'),
+        agentRoutingPath: path.join(__dirname, '..', '..', '..', 'templates', 'agentic', 'agent-routing.md'),
+        agenticDelegation: true,
+      }
+
+      // 6. Load state with filtered context
+      const rawState = await contextBuilder.loadState(metadataContext)
+
+      // 6.5. SEMANTIC COMPRESSION: Compress state for reduced token usage
+      const compressedState: Record<string, unknown> = {}
+      for (const [key, content] of Object.entries(rawState)) {
+        if (content) {
+          const compressed = semanticCompression.compress(content, key)
+          compressedState[key] = {
+            raw: content,
+            summary: compressed.summary,
+            compressed,
+          }
+        } else {
+          compressedState[key] = { raw: null, summary: 'Empty', compressed: null }
+        }
+      }
+
+      // Use compressed summaries for prompt, keep raw for tool execution
+      const state = {
+        ...rawState,
+        _compressed: compressedState,
+        _compressionMetrics: semanticCompression.getMetrics(),
+      }
+
+      // 7. MEMORY: Load learned patterns AND relevant memories for this command
+      let learnedPatterns = null
+      let relevantMemories = null
+      if (metadataContext.projectId) {
+        learnedPatterns = {
+          commit_footer: await memorySystem.getSmartDecision(metadataContext.projectId, 'commit_footer'),
+          branch_naming: await memorySystem.getSmartDecision(metadataContext.projectId, 'branch_naming'),
+          test_before_ship: await memorySystem.getSmartDecision(metadataContext.projectId, 'test_before_ship'),
+          preferred_agent: await memorySystem.getSmartDecision(
+            metadataContext.projectId,
+            `preferred_agent_${commandName}`
+          ),
+        }
+
+        // P3.3: Get relevant memories for context
+        relevantMemories = await memorySystem.getRelevantMemories(
+          metadataContext.projectId,
+          { commandName, params },
+          5
+        )
+      }
+
+      // 9. Build prompt - NO agent assignment here, Claude decides via templates
+      const planInfo = {
+        isPlanning: requiresPlanning || isInPlanningMode,
+        requiresApproval: isDestructive && !params.approved,
+        active: activePlan,
+        allowedTools: planMode.getAllowedTools(isInPlanningMode, template.frontmatter['allowed-tools'] || []),
+      }
+      // Agent is null - Claude assigns via Task tool using agent-routing.md
+      const prompt = promptBuilder.build(
+        template,
+        context as Parameters<typeof promptBuilder.build>[1],
+        state,
+        null,
+        learnedPatterns,
+        thinkBlock,
+        relevantMemories,
+        planInfo
+      )
+
+      // Log agentic mode
+      console.log(`🤖 Agentic delegation enabled - Claude will assign agent via Task tool`)
+
+      // Record successful attempt
+      loopDetector.recordSuccess(commandName, loopContext)
+
+      // Signal end for status line
+      this.signalEnd()
+
+      return {
+        success: true,
+        template,
+        context,
+        state,
+        prompt,
+        agenticDelegation: true,
+        agentsPath: context.agentsPath as string,
+        agentRoutingPath: context.agentRoutingPath as string,
+        reasoning,
+        thinkBlock,
+        groundTruth: groundTruthResult,
+        compressionMetrics: state._compressionMetrics,
+        learnedPatterns,
+        relevantMemories,
+        formatResponse: (data: unknown) => responseTemplates.format(commandName, data as Parameters<typeof responseTemplates.format>[1]),
+        formatThinkBlock: (verbose: boolean) => thinkBlocks.format(thinkBlock, verbose),
+        parallel: {
+          execute: (toolCalls: unknown[]) => parallelTools.execute(toolCalls as Parameters<typeof parallelTools.execute>[0]),
+          readAll: (paths: string[]) => parallelTools.readAll(paths),
+          canParallelize: (tools: string[]) => parallelTools.canParallelize(tools),
+          getMetrics: () => parallelTools.getMetrics(),
+        },
+        memory: {
+          create: (memory: unknown) =>
+            memorySystem.createMemory(metadataContext.projectId!, memory as Parameters<typeof memorySystem.createMemory>[1]),
+          autoRemember: (type: string, value: string, ctx?: string) =>
+            memorySystem.autoRemember(metadataContext.projectId!, type, value, ctx),
+          search: (query: string) => memorySystem.searchMemories(metadataContext.projectId!, query),
+          findByTags: (tags: string[]) => memorySystem.findByTags(metadataContext.projectId!, tags),
+          getStats: () => memorySystem.getMemoryStats(metadataContext.projectId!),
+        },
+        plan: {
+          active: activePlan,
+          isPlanning: requiresPlanning || isInPlanningMode,
+          isDestructive,
+          requiresApproval: isDestructive && !params.approved,
+          recordInfo: (info: unknown) =>
+            planMode.recordGatheredInfo(metadataContext.projectId!, info as Parameters<typeof planMode.recordGatheredInfo>[1]),
+          setAnalysis: (analysis: unknown) => planMode.setAnalysis(metadataContext.projectId!, analysis),
+          propose: (plan: unknown) =>
+            planMode.proposePlan(metadataContext.projectId!, plan as Parameters<typeof planMode.proposePlan>[1]),
+          approve: (feedback?: string | null) => planMode.approvePlan(metadataContext.projectId!, feedback),
+          reject: (reason?: string | null) => planMode.rejectPlan(metadataContext.projectId!, reason),
+          getApprovalPrompt: () =>
+            planMode.generateApprovalPrompt(commandName, context as Parameters<typeof planMode.generateApprovalPrompt>[1]),
+          startExecution: () => planMode.startExecution(metadataContext.projectId!),
+          getNextStep: () => planMode.getNextStep(metadataContext.projectId!),
+          completeStep: (result?: unknown) => planMode.completeStep(metadataContext.projectId!, result),
+          failStep: (error: string) => planMode.failStep(metadataContext.projectId!, error),
+          abort: (reason?: string) => planMode.abortPlan(metadataContext.projectId!, reason),
+          getStatus: () => planMode.formatStatus(metadataContext.projectId!),
+          getAllowedTools: () =>
+            planMode.getAllowedTools(isInPlanningMode, template.frontmatter['allowed-tools'] || []),
+        },
+      }
+    } catch (error) {
+      // Signal end for status line
+      this.signalEnd()
+
+      // Record failed attempt for loop detection
+      const attemptInfo = loopDetector.recordAttempt(commandName, loopContext, {
+        success: false,
+        error: (error as Error).message,
+      })
+
+      // Check if we should escalate after this failure
+      if (attemptInfo.shouldEscalate) {
+        const escalation = loopDetector.getEscalationInfo(commandName, loopContext)
+        return {
+          success: false,
+          error: escalation?.message,
+          escalation,
+          isLoopDetected: true,
+          suggestion: escalation?.suggestion,
+        }
+      }
+
+      return {
+        success: false,
+        error: (error as Error).message,
+        attemptNumber: attemptInfo.attemptNumber,
+        isLooping: attemptInfo.isLooping,
+      }
+    }
+  }
+
+  /**
+   * Execute tool with permission check
+   */
+  async executeTool(toolName: string, args: unknown[], allowedTools: string[]): Promise<unknown> {
+    // Check if tool is allowed
+    if (!toolRegistry.isAllowed(toolName, allowedTools)) {
+      throw new Error(`Tool ${toolName} not allowed for this command`)
+    }
+
+    // Get tool function
+    const tool = toolRegistry.get(toolName)
+    if (!tool) {
+      throw new Error(`Tool ${toolName} not found`)
+    }
+
+    // Execute tool
+    return await tool(...args)
+  }
+
+  /**
+   * Simple execution for direct tool access (legacy migration helper)
+   */
+  async executeSimple(
+    commandName: string,
+    executionFn: ExecutionToolsFn,
+    projectPath: string
+  ): Promise<SimpleExecutionResult> {
+    try {
+      // Load template to get allowed tools
+      const template = await templateLoader.load(commandName)
+      const allowedTools = template.frontmatter['allowed-tools'] || []
+
+      // Build context
+      const context = await contextBuilder.build(projectPath)
+
+      // Create tools proxy that checks permissions
+      const tools = {
+        read: async (filePath: string) => this.executeTool('Read', [filePath], allowedTools),
+        write: async (filePath: string, content: string) => this.executeTool('Write', [filePath, content], allowedTools),
+        bash: async (command: string) => this.executeTool('Bash', [command], allowedTools),
+      }
+
+      // Execute user function with tools
+      const result = await executionFn(tools, context)
+
+      return {
+        success: true,
+        result,
+      }
+    } catch (error) {
+      return {
+        success: false,
+        error: (error as Error).message,
+      }
+    }
+  }
+}

package/core/agentic/command-executor/index.ts

@@ -0,0 +1,16 @@
+/**
+ * Command Executor
+ * Orchestrates command execution with agentic delegation.
+ *
+ * @module agentic/command-executor
+ * @version 3.4
+ */
+
+export type { ExecutionResult, SimpleExecutionResult, ExecutionToolsFn } from './types'
+export { signalStart, signalEnd } from './status-signal'
+export { CommandExecutor } from './command-executor'
+
+import { CommandExecutor } from './command-executor'
+
+const commandExecutor = new CommandExecutor()
+export default commandExecutor

package/core/agentic/command-executor/status-signal.ts

@@ -0,0 +1,38 @@
+/**
+ * Status Signal
+ * Running file for status line integration
+ */
+
+import fs from 'fs'
+import path from 'path'
+import os from 'os'
+
+const RUNNING_FILE = path.join(os.homedir(), '.prjct-cli', '.running')
+
+/**
+ * Signal that a command is running (for status line)
+ */
+export function signalStart(commandName: string): void {
+  try {
+    const dir = path.dirname(RUNNING_FILE)
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true })
+    }
+    fs.writeFileSync(RUNNING_FILE, `/p:${commandName}`)
+  } catch {
+    // Silently ignore - status line is optional
+  }
+}
+
+/**
+ * Signal that command has finished (for status line)
+ */
+export function signalEnd(): void {
+  try {
+    if (fs.existsSync(RUNNING_FILE)) {
+      fs.unlinkSync(RUNNING_FILE)
+    }
+  } catch {
+    // Silently ignore - status line is optional
+  }
+}