prjct-cli 1.22.0 → 1.23.0

package/core/agentic/agent-router.ts

@@ -1,150 +0,0 @@
-/**
- * Agent Router
- * Orchestrates agent loading and context building for Claude delegation.
- *
- * Loads agents from global storage:
- * ~/.prjct-cli/projects/{id}/agents/
- *
- * Agents are dynamically generated by /p:sync based on project tech stack.
- *
- * @module agentic/agent-router
- * @version 4.0.0
- */
-
-import fs from 'node:fs/promises'
-import path from 'node:path'
-import configManager from '../infrastructure/config-manager'
-import pathManager from '../infrastructure/path-manager'
-import type { Agent, AssignmentContext } from '../types'
-import { getErrorMessage, isNotFoundError } from '../types/fs'
-
-// Re-export types for convenience
-export type { Agent, AssignmentContext } from '../types'
-
-/**
- * Routes tasks to specialized agents based on Claude's decisions.
- * Handles agent loading, context building, and usage logging.
- */
-class AgentRouter {
-  projectId: string | null = null
-  projectPath: string | null = null
-  agentsPath: string | null = null
-
-  /**
-   * Initialize router with project context
-   */
-  async initialize(projectPath: string): Promise<void> {
-    this.projectId = await configManager.getProjectId(projectPath)
-    this.projectPath = projectPath
-    this.agentsPath = pathManager.getFilePath(this.projectId!, 'agents', '')
-  }
-
-  /**
-   * Load all available agents from global storage
-   */
-  async loadAvailableAgents(): Promise<Agent[]> {
-    if (!this.agentsPath) return []
-
-    try {
-      const files = await fs.readdir(this.agentsPath)
-      const agents: Agent[] = []
-
-      for (const file of files) {
-        if (file.endsWith('.md')) {
-          const name = file.replace('.md', '')
-          const content = await fs.readFile(path.join(this.agentsPath, file), 'utf-8')
-          agents.push({ name, content })
-        }
-      }
-
-      return agents
-    } catch (error) {
-      // Agents directory doesn't exist yet - expected for new projects
-      if (!isNotFoundError(error)) {
-        console.error(`Agent loading error: ${getErrorMessage(error)}`)
-      }
-      return []
-    }
-  }
-
-  /**
-   * Get list of available agent names
-   */
-  async getAgentNames(): Promise<string[]> {
-    const agents = await this.loadAvailableAgents()
-    return agents.map((a) => a.name)
-  }
-
-  /**
-   * Load a specific agent by name from global storage
-   */
-  async loadAgent(name: string): Promise<Agent | null> {
-    if (!this.agentsPath) return null
-
-    try {
-      const filePath = path.join(this.agentsPath, `${name}.md`)
-      const content = await fs.readFile(filePath, 'utf-8')
-      return { name, content }
-    } catch (error) {
-      // Agent file doesn't exist - expected
-      if (!isNotFoundError(error)) {
-        console.error(`Agent load error: ${getErrorMessage(error)}`)
-      }
-      return null
-    }
-  }
-
-  /**
-   * Build context for Claude to decide agent assignment
-   */
-  async buildAssignmentContext(
-    task: string | { description?: string },
-    projectPath: string
-  ): Promise<AssignmentContext> {
-    const agents = await this.getAgentNames()
-
-    return {
-      task: typeof task === 'string' ? task : task.description || '',
-      availableAgents: agents,
-      projectPath,
-      projectId: this.projectId,
-      // Claude reads this and decides via template
-      _template: 'templates/agent-assignment.md',
-    }
-  }
-
-  /**
-   * Log agent usage to JSONL file
-   */
-  async logUsage(
-    task: string | { description?: string },
-    agent: string | { name?: string },
-    _projectPath: string
-  ): Promise<void> {
-    try {
-      const logPath = path.join(
-        process.env.HOME || '',
-        '.prjct-cli',
-        'projects',
-        this.projectId || '',
-        'agent-usage.jsonl'
-      )
-
-      const entry = `${JSON.stringify({
-        timestamp: new Date().toISOString(),
-        task: typeof task === 'string' ? task : task.description,
-        agent: typeof agent === 'string' ? agent : agent.name,
-        projectId: this.projectId,
-      })}\n`
-
-      await fs.appendFile(logPath, entry)
-    } catch (error) {
-      // Non-critical - log unexpected errors but don't fail
-      if (!isNotFoundError(error)) {
-        console.error(`Agent usage log error: ${getErrorMessage(error)}`)
-      }
-    }
-  }
-}
-
-export default AgentRouter

package/core/agentic/anti-hallucination.ts

@@ -1,141 +0,0 @@
-/**
- * Anti-Hallucination Block Generator
- *
- * Generates constraint blocks that ground the LLM in project reality.
- * Based on research of 25+ system prompts (Claude Code, Gemini, ChatGPT),
- * the following techniques reduce hallucinations 25-40%:
- *
- * 1. Explicit availability — what IS in the project
- * 2. Explicit unavailability — what is NOT in the project
- * 3. Visibility grounding — only use paths shown in context
- * 4. Library verification — check package.json before assuming
- * 5. Scope clarification — limit to project directory
- *
- * This block should be injected BEFORE task context (position 5 in prompt order)
- * so the LLM has constraints loaded before reading code.
- *
- * @module agentic/anti-hallucination
- * @see PRJ-301
- */
-
-import { z } from 'zod'
-import { deduplicateTechStack } from './tech-normalizer'
-
-// =============================================================================
-// Schema
-// =============================================================================
-
-export const ProjectGroundTruthSchema = z.object({
-  /** Project root path */
-  projectPath: z.string(),
-  /** Programming language (e.g., 'TypeScript', 'JavaScript', 'Python') */
-  language: z.string().optional(),
-  /** Primary framework (e.g., 'Hono', 'Next.js', 'Express') */
-  framework: z.string().optional(),
-  /** Technology stack items (e.g., ['Hono', 'Zod', 'Vitest']) */
-  techStack: z.array(z.string()).default([]),
-  /** Domain flags from sealed analysis */
-  domains: z
-    .object({
-      hasFrontend: z.boolean().default(false),
-      hasBackend: z.boolean().default(false),
-      hasDatabase: z.boolean().default(false),
-      hasTesting: z.boolean().default(false),
-      hasDocker: z.boolean().default(false),
-    })
-    .optional(),
-  /** Total files in project */
-  fileCount: z.number().optional(),
-  /** Available agent names (e.g., ['backend', 'testing']) */
-  availableAgents: z.array(z.string()).default([]),
-  /** Sealed analysis languages — used to ground available tech (PRJ-260) */
-  analysisLanguages: z.array(z.string()).default([]),
-  /** Sealed analysis frameworks — used to ground available tech (PRJ-260) */
-  analysisFrameworks: z.array(z.string()).default([]),
-  /** Package manager from sealed analysis (PRJ-260) */
-  analysisPackageManager: z.string().optional(),
-})
-
-export type ProjectGroundTruth = z.input<typeof ProjectGroundTruthSchema>
-
-// =============================================================================
-// Domain Mapping
-// =============================================================================
-
-/** Map domain flags to human-readable technology categories */
-const DOMAIN_LABELS: Record<string, string> = {
-  hasFrontend: 'Frontend (UI/components)',
-  hasBackend: 'Backend (APIs/servers)',
-  hasDatabase: 'Database (SQL/ORM)',
-  hasTesting: 'Testing (unit/integration)',
-  hasDocker: 'Docker/containers',
-}
-
-// =============================================================================
-// Generator
-// =============================================================================
-
-/**
- * Build the anti-hallucination constraints block.
- *
- * Returns a markdown section with explicit availability statements,
- * visibility grounding rules, and library verification directives.
- */
-export function buildAntiHallucinationBlock(truth: ProjectGroundTruth): string {
-  const parts: string[] = []
-
-  parts.push('## CONSTRAINTS (Read Before Acting)\n')
-
-  // 1. Explicit availability (enriched by sealed analysis — PRJ-260, PRJ-300)
-  // Use normalized deduplication to prevent "React" and "react" appearing twice,
-  // and to handle aliases like "Next.js" vs "nextjs".
-  const rawAvailable: string[] = []
-  if (truth.language) rawAvailable.push(truth.language)
-  if (truth.framework) rawAvailable.push(truth.framework)
-  const techStack = truth.techStack ?? []
-  rawAvailable.push(...techStack)
-  // Merge languages/frameworks from sealed analysis
-  const analysisLangs = truth.analysisLanguages ?? []
-  const analysisFrameworks = truth.analysisFrameworks ?? []
-  rawAvailable.push(...analysisLangs, ...analysisFrameworks)
-  const available = deduplicateTechStack(rawAvailable)
-
-  if (available.length > 0) {
-    parts.push(`AVAILABLE in this project: ${available.join(', ')}`)
-  }
-  if (truth.analysisPackageManager) {
-    parts.push(`PACKAGE MANAGER: ${truth.analysisPackageManager}`)
-  }
-
-  // 2. Explicit unavailability from domain flags
-  if (truth.domains) {
-    const absent = Object.entries(truth.domains)
-      .filter(([, hasIt]) => !hasIt)
-      .map(([key]) => DOMAIN_LABELS[key])
-      .filter(Boolean)
-
-    if (absent.length > 0) {
-      parts.push(`NOT PRESENT: ${absent.join(', ')}`)
-    }
-  }
-
-  // 3. Available agents
-  const availableAgents = truth.availableAgents ?? []
-  if (availableAgents.length > 0) {
-    parts.push(`AGENTS: ${availableAgents.join(', ')}`)
-  }
-
-  // 4. Scope and grounding rules
-  parts.push('')
-  parts.push(`SCOPE: Only files in \`${truth.projectPath}\` are accessible.`)
-  parts.push('RULE: Use ONLY file paths explicitly shown in context. Do NOT infer or guess paths.')
-  parts.push('RULE: NEVER assume a library is available. Check package.json/imports first.')
-  parts.push('RULE: If previous context contradicts this section, trust this section.')
-  parts.push('RULE: Read files BEFORE modifying. Never assume code structure.')
-
-  if (truth.fileCount) {
-    parts.push(`\nContext: ${truth.fileCount} files in project.`)
-  }
-
-  return parts.join('\n')
-}

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

@@ -1,234 +0,0 @@
-/**
- * Chain of Thought Reasoning
- * Implements step-by-step reasoning for complex commands
- *
- * @module agentic/chain-of-thought
- * @version 1.0.0
- */
-
-import type { ContextState, ProjectContext } from '../types'
-
-// Type aliases for compatibility with ProjectContext from contextBuilder.build()
-type Context = Pick<ProjectContext, 'projectId' | 'projectPath' | 'params'>
-type State = ContextState
-
-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 }
-
-const chainOfThought = { requiresReasoning, reason, formatPlan, REASONING_REQUIRED_COMMANDS }
-export default chainOfThought

package/core/agentic/command-classifier.ts

@@ -1,141 +0,0 @@
-/**
- * Command Classifier
- *
- * Classifies unknown commands by analyzing template metadata.
- * When a command isn't in command-context.config.json, this module
- * determines what context sections it needs based on template content.
- *
- * Classification chain:
- * 1. Config lookup (instant) — handled by command-context.ts
- * 2. Template heuristic (instant) — this module
- * 3. Wildcard fallback — handled by command-context.ts
- *
- * @see PRJ-298
- */
-
-import type { CommandContextEntry } from '../schemas/command-context'
-import type { Template } from '../types'
-
-// Keywords that indicate code-modifying commands
-const CODE_KEYWORDS = [
-  'build',
-  'create',
-  'add',
-  'implement',
-  'fix',
-  'refactor',
-  'update',
-  'modify',
-  'change',
-  'write',
-  'generate',
-  'scaffold',
-  'migrate',
-  'optimize',
-  'improve',
-  'enhance',
-  'redesign',
-  'rewrite',
-]
-
-// Keywords that indicate read-only / info commands
-const INFO_KEYWORDS = [
-  'list',
-  'show',
-  'get',
-  'status',
-  'info',
-  'check',
-  'view',
-  'display',
-  'describe',
-  'explain',
-  'analyze',
-  'report',
-  'dashboard',
-]
-
-// Keywords that indicate quality/verification commands
-const QUALITY_KEYWORDS = [
-  'test',
-  'verify',
-  'validate',
-  'review',
-  'audit',
-  'check',
-  'lint',
-  'ship',
-  'deploy',
-  'release',
-  'complete',
-  'done',
-  'finish',
-]
-
-// Tools that indicate code modification
-const CODE_TOOLS = ['Write', 'Edit', 'Bash']
-
-/**
- * Count keyword matches using word boundaries to avoid substring false positives.
- */
-function countMatches(text: string, keywords: string[]): number {
-  return keywords.filter((k) => new RegExp(`\\b${k}\\b`).test(text)).length
-}
-
-/**
- * Classify a command based on its template metadata.
- * Analyzes the command name, description, allowed tools, and content
- * to determine what context sections are relevant.
- *
- * Priority: code-modifying > quality/verification > info/read-only > default
- */
-export function classifyCommand(commandName: string, template: Template): CommandContextEntry {
-  const description = (template.frontmatter?.description || '').toLowerCase()
-  const content = template.content.toLowerCase()
-  const allowedTools = template.frontmatter?.['allowed-tools'] || []
-  const combined = `${commandName} ${description} ${content}`
-
-  const codeScore = countMatches(combined, CODE_KEYWORDS)
-  const infoScore = countMatches(combined, INFO_KEYWORDS)
-  const qualityScore = countMatches(combined, QUALITY_KEYWORDS)
-  const hasCodeTools = allowedTools.some((t: string) => CODE_TOOLS.includes(t))
-
-  // Code-modifying command: needs agents + patterns + checklists
-  if (hasCodeTools && codeScore > 0) {
-    return {
-      agents: true,
-      patterns: true,
-      checklist: qualityScore > 0,
-      modules: [],
-    }
-  }
-
-  // Quality/verification command: needs patterns + checklists
-  // Quality takes priority over info when quality score is higher
-  if (qualityScore > 0 && qualityScore >= infoScore) {
-    return {
-      agents: false,
-      patterns: true,
-      checklist: true,
-      modules: [],
-    }
-  }
-
-  // Info/read-only command: needs nothing
-  if (infoScore > 0 && codeScore === 0) {
-    return {
-      agents: false,
-      patterns: false,
-      checklist: false,
-      modules: [],
-    }
-  }
-
-  // Default for unknown: agents + patterns (sensible default)
-  return {
-    agents: true,
-    patterns: true,
-    checklist: false,
-    modules: [],
-  }
-}