prjct-cli 0.11.4 → 0.12.0

package/core/agentic/ground-truth/verifiers/feature.ts

@@ -0,0 +1,70 @@
+/**
+ * Feature Command Verifier
+ * Verify feature can be added
+ */
+
+import fs from 'fs/promises'
+import type { Context, VerificationResult } from '../types'
+import { escapeRegex } from '../utils'
+
+export async function verifyFeature(context: Context): Promise<VerificationResult> {
+  const warnings: string[] = []
+  const recommendations: string[] = []
+  const actual: Record<string, unknown> = {}
+
+  // 1. Check next.md capacity
+  const nextPath = context.paths.next
+  try {
+    const nextContent = await fs.readFile(nextPath, 'utf-8')
+    actual.nextExists = true
+    const tasks = nextContent.match(/- \[[ x]\]/g) || []
+    actual.taskCount = tasks.length
+    actual.pendingTasks = (nextContent.match(/- \[ \]/g) || []).length
+
+    if ((actual.taskCount as number) >= 90) {
+      warnings.push(`Queue nearly full (${actual.taskCount}/100 tasks)`)
+      recommendations.push('Complete some tasks before adding more')
+    }
+  } catch {
+    actual.nextExists = false
+    actual.taskCount = 0
+  }
+
+  // 2. Check roadmap.md for duplicate features
+  const roadmapPath = context.paths.roadmap
+  try {
+    const roadmapContent = await fs.readFile(roadmapPath, 'utf-8')
+    actual.roadmapExists = true
+
+    const featureName = context.params.description || context.params.feature
+    if (featureName) {
+      const featurePattern = new RegExp(escapeRegex(featureName), 'i')
+      if (featurePattern.test(roadmapContent)) {
+        warnings.push(`Feature "${featureName}" may already exist in roadmap`)
+        recommendations.push('Check roadmap for duplicates with /p:roadmap')
+      }
+    }
+  } catch {
+    actual.roadmapExists = false
+  }
+
+  // 3. Check if there's an active task (should complete first?)
+  const nowPath = context.paths.now
+  try {
+    const nowContent = await fs.readFile(nowPath, 'utf-8')
+    actual.hasActiveTask = nowContent.trim().length > 0 && !nowContent.includes('No current task')
+
+    if (actual.hasActiveTask) {
+      recommendations.push('Consider completing current task first with /p:done')
+    }
+  } catch {
+    actual.hasActiveTask = false
+  }
+
+  return {
+    verified: warnings.length === 0,
+    actual,
+    warnings,
+    recommendations,
+  }
+}

package/core/agentic/ground-truth/verifiers/index.ts

@@ -0,0 +1,37 @@
+/**
+ * Ground Truth Verifiers Index
+ * Re-exports all command verifiers
+ */
+
+import type { Verifier } from '../types'
+import { verifyDone } from './done'
+import { verifyShip } from './ship'
+import { verifyFeature } from './feature'
+import { verifyNow } from './now'
+import { verifyInit } from './init'
+import { verifySync } from './sync'
+import { verifyAnalyze } from './analyze'
+import { verifySpec } from './spec'
+
+/**
+ * Command-specific ground truth verifiers
+ */
+export const verifiers: Record<string, Verifier> = {
+  done: verifyDone,
+  ship: verifyShip,
+  feature: verifyFeature,
+  now: verifyNow,
+  init: verifyInit,
+  sync: verifySync,
+  analyze: verifyAnalyze,
+  spec: verifySpec,
+}
+
+export { verifyDone } from './done'
+export { verifyShip } from './ship'
+export { verifyFeature } from './feature'
+export { verifyNow } from './now'
+export { verifyInit } from './init'
+export { verifySync } from './sync'
+export { verifyAnalyze } from './analyze'
+export { verifySpec } from './spec'

package/core/agentic/ground-truth/verifiers/init.ts

@@ -0,0 +1,52 @@
+/**
+ * Init Command Verifier
+ * Verify project can be initialized
+ */
+
+import fs from 'fs/promises'
+import path from 'path'
+import os from 'os'
+import type { Context, VerificationResult } from '../types'
+
+export async function verifyInit(context: Context): Promise<VerificationResult> {
+  const warnings: string[] = []
+  const recommendations: string[] = []
+  const actual: Record<string, unknown> = {}
+
+  // 1. Check if already initialized
+  const configPath = path.join(context.projectPath, '.prjct/prjct.config.json')
+  try {
+    const configContent = await fs.readFile(configPath, 'utf-8')
+    actual.alreadyInitialized = true
+    actual.existingConfig = JSON.parse(configContent)
+    warnings.push('Project already initialized')
+    recommendations.push('Use /p:analyze to refresh analysis or delete .prjct/ to reinitialize')
+  } catch {
+    actual.alreadyInitialized = false
+  }
+
+  // 2. Check if global storage path is writable
+  const globalPath = path.join(os.homedir(), '.prjct-cli')
+  try {
+    await fs.access(globalPath, fs.constants.W_OK)
+    actual.globalPathWritable = true
+  } catch {
+    try {
+      // Try to create it
+      await fs.mkdir(globalPath, { recursive: true })
+      actual.globalPathWritable = true
+      actual.globalPathCreated = true
+    } catch {
+      actual.globalPathWritable = false
+      warnings.push('Cannot write to ~/.prjct-cli')
+      recommendations.push('Check directory permissions')
+    }
+  }
+
+  return {
+    verified: warnings.length === 0,
+    actual,
+    warnings,
+    recommendations,
+  }
+}

package/core/agentic/ground-truth/verifiers/now.ts

@@ -0,0 +1,57 @@
+/**
+ * Now Command Verifier
+ * Verify task can be set (anti-hallucination: warn if replacing)
+ */
+
+import fs from 'fs/promises'
+import type { Context, VerificationResult } from '../types'
+
+export async function verifyNow(context: Context): Promise<VerificationResult> {
+  const warnings: string[] = []
+  const recommendations: string[] = []
+  const actual: Record<string, unknown> = {}
+
+  // 1. Check if there's already an active task
+  const nowPath = context.paths.now
+  try {
+    const nowContent = await fs.readFile(nowPath, 'utf-8')
+    actual.nowExists = true
+    actual.nowContent = nowContent.trim()
+
+    const hasRealTask =
+      nowContent.trim().length > 0 && !nowContent.includes('No current task') && !nowContent.match(/^#\s*NOW\s*$/m)
+
+    actual.hasActiveTask = hasRealTask
+
+    // ANTI-HALLUCINATION: Warn if replacing existing task
+    if (hasRealTask && context.params.task) {
+      const taskPreview = nowContent.substring(0, 50).replace(/\n/g, ' ')
+      warnings.push(`Replacing existing task: "${taskPreview}..."`)
+      recommendations.push('Use /p:done first to track completion')
+    }
+  } catch {
+    actual.nowExists = false
+    actual.hasActiveTask = false
+  }
+
+  // 2. Check next.md for available tasks
+  const nextPath = context.paths.next
+  try {
+    const nextContent = await fs.readFile(nextPath, 'utf-8')
+    const pendingTasks = (nextContent.match(/- \[ \]/g) || []).length
+    actual.pendingTasks = pendingTasks
+
+    if (!context.params.task && pendingTasks > 0) {
+      recommendations.push(`${pendingTasks} tasks available in queue`)
+    }
+  } catch {
+    actual.pendingTasks = 0
+  }
+
+  return {
+    verified: warnings.length === 0,
+    actual,
+    warnings,
+    recommendations,
+  }
+}

package/core/agentic/ground-truth/verifiers/ship.ts

@@ -0,0 +1,85 @@
+/**
+ * Ship Command Verifier
+ * Verify feature is ready to ship
+ */
+
+import fs from 'fs/promises'
+import path from 'path'
+import { execSync } from 'child_process'
+import type { Context, VerificationResult } from '../types'
+import { escapeRegex } from '../utils'
+
+export async function verifyShip(context: Context): Promise<VerificationResult> {
+  const warnings: string[] = []
+  const recommendations: string[] = []
+  const actual: Record<string, unknown> = {}
+
+  // 1. Check for uncommitted changes
+  try {
+    const gitStatus = execSync('git status --porcelain', {
+      cwd: context.projectPath,
+      encoding: 'utf-8',
+    })
+    actual.hasUncommittedChanges = gitStatus.trim().length > 0
+    actual.uncommittedFiles = gitStatus.trim().split('\n').filter(Boolean).length
+
+    if (actual.hasUncommittedChanges) {
+      warnings.push(`${actual.uncommittedFiles} uncommitted file(s)`)
+      recommendations.push('Commit changes before shipping')
+    }
+  } catch {
+    actual.gitAvailable = false
+    // Not a git repo or git not available - not a blocker
+  }
+
+  // 2. Check for package.json version (if exists)
+  const pkgPath = path.join(context.projectPath, 'package.json')
+  try {
+    const pkgContent = await fs.readFile(pkgPath, 'utf-8')
+    const pkg = JSON.parse(pkgContent)
+    actual.currentVersion = pkg.version
+    actual.hasPackageJson = true
+  } catch {
+    actual.hasPackageJson = false
+  }
+
+  // 3. Check shipped.md for duplicate feature names
+  const shippedPath = context.paths.shipped
+  try {
+    const shippedContent = await fs.readFile(shippedPath, 'utf-8')
+    actual.shippedExists = true
+
+    // Check if feature name already shipped today
+    const featureName = context.params.feature || context.params.description
+    if (featureName) {
+      const today = new Date().toISOString().split('T')[0]
+      const todayPattern = new RegExp(`${today}.*${escapeRegex(featureName)}`, 'i')
+      if (todayPattern.test(shippedContent)) {
+        warnings.push(`Feature "${featureName}" already shipped today`)
+        recommendations.push('Use a different feature name or skip /p:ship')
+      }
+    }
+  } catch {
+    actual.shippedExists = false
+  }
+
+  // 4. Check for test failures (if test script exists)
+  if (actual.hasPackageJson) {
+    try {
+      const pkgContent = await fs.readFile(pkgPath, 'utf-8')
+      const pkg = JSON.parse(pkgContent)
+      actual.hasTestScript = !!pkg.scripts?.test
+      // Note: We don't run tests here, just check if they exist
+      // Running tests is the user's responsibility
+    } catch {
+      actual.hasTestScript = false
+    }
+  }
+
+  return {
+    verified: warnings.length === 0,
+    actual,
+    warnings,
+    recommendations,
+  }
+}

package/core/agentic/ground-truth/verifiers/spec.ts

@@ -0,0 +1,45 @@
+/**
+ * Spec Command Verifier
+ * Verify spec can be created
+ */
+
+import fs from 'fs/promises'
+import type { Context, VerificationResult } from '../types'
+
+export async function verifySpec(context: Context): Promise<VerificationResult> {
+  const warnings: string[] = []
+  const recommendations: string[] = []
+  const actual: Record<string, unknown> = {}
+
+  // 1. Check specs directory exists
+  const specsPath = context.paths.specs
+  try {
+    await fs.access(specsPath)
+    actual.specsExists = true
+
+    // List existing specs
+    const files = await fs.readdir(specsPath)
+    actual.existingSpecs = files.filter((f) => f.endsWith('.md'))
+    actual.specCount = (actual.existingSpecs as string[]).length
+  } catch {
+    actual.specsExists = false
+    actual.specCount = 0
+  }
+
+  // 2. Check for duplicate spec name
+  const featureName = context.params.feature || context.params.name || context.params.description
+  if (featureName && actual.existingSpecs) {
+    const slug = featureName.toLowerCase().replace(/\s+/g, '-')
+    if ((actual.existingSpecs as string[]).includes(`${slug}.md`)) {
+      warnings.push(`Spec "${featureName}" already exists`)
+      recommendations.push('Use a different name or edit existing spec')
+    }
+  }
+
+  return {
+    verified: warnings.length === 0,
+    actual,
+    warnings,
+    recommendations,
+  }
+}

package/core/agentic/ground-truth/verifiers/sync.ts

@@ -0,0 +1,47 @@
+/**
+ * Sync Command Verifier
+ * Verify sync can proceed
+ */
+
+import fs from 'fs/promises'
+import path from 'path'
+import os from 'os'
+import type { Context, VerificationResult } from '../types'
+
+export async function verifySync(context: Context): Promise<VerificationResult> {
+  const warnings: string[] = []
+  const recommendations: string[] = []
+  const actual: Record<string, unknown> = {}
+
+  // 1. Check if project is initialized
+  const configPath = path.join(context.projectPath, '.prjct/prjct.config.json')
+  try {
+    const configContent = await fs.readFile(configPath, 'utf-8')
+    actual.hasConfig = true
+    actual.config = JSON.parse(configContent)
+  } catch {
+    actual.hasConfig = false
+    warnings.push('Project not initialized')
+    recommendations.push('Run /p:init first')
+    return { verified: false, actual, warnings, recommendations }
+  }
+
+  // 2. Check if global storage exists
+  const projectId = (actual.config as { projectId?: string })?.projectId
+  const globalProjectPath = path.join(os.homedir(), '.prjct-cli/projects', projectId || '')
+  try {
+    await fs.access(globalProjectPath)
+    actual.globalStorageExists = true
+  } catch {
+    actual.globalStorageExists = false
+    warnings.push('Global storage missing')
+    recommendations.push('Run /p:init to recreate')
+  }
+
+  return {
+    verified: warnings.length === 0,
+    actual,
+    warnings,
+    recommendations,
+  }
+}

package/core/agentic/ground-truth/verifiers.ts

@@ -0,0 +1,6 @@
+/**
+ * Ground Truth Verifiers
+ * Re-exports from verifiers/index.ts for backwards compatibility.
+ */
+
+export * from './verifiers/index'

package/core/agentic/ground-truth.ts

@@ -0,0 +1,8 @@
+/**
+ * Ground Truth Verification
+ * Re-exports from ground-truth/index.ts for backwards compatibility.
+ */
+
+import groundTruth from './ground-truth/index'
+export * from './ground-truth/index'
+export default groundTruth

package/core/agentic/loop-detector/error-analysis.ts

@@ -0,0 +1,97 @@
+/**
+ * Error Analysis
+ * Pattern detection and suggestion generation for errors
+ */
+
+import type { ErrorEntry, ErrorPattern } from './types'
+
+/**
+ * Check if two errors are similar
+ */
+export function isSimilarError(error1: string, error2: string): boolean {
+  if (!error1 || !error2) return false
+
+  // Normalize errors
+  const normalize = (e: string) =>
+    e
+      .toLowerCase()
+      .replace(/[0-9]+/g, 'N') // Replace numbers
+      .replace(/['"`]/g, '') // Remove quotes
+      .replace(/\s+/g, ' ') // Normalize whitespace
+      .trim()
+
+  return normalize(error1) === normalize(error2)
+}
+
+/**
+ * Analyze error pattern from history
+ */
+export function analyzeErrorPattern(errors: ErrorEntry[]): ErrorPattern {
+  if (!errors || errors.length === 0) {
+    return { type: 'unknown', description: 'No error information' }
+  }
+
+  const lastError = errors[errors.length - 1]?.message?.toLowerCase() || ''
+
+  // Detect common patterns (ORDER MATTERS - more specific patterns first)
+  if (lastError.includes('permission') || lastError.includes('access denied')) {
+    return { type: 'permission', description: 'File or directory permission issue' }
+  }
+  if (lastError.includes('not found') || lastError.includes('no such file')) {
+    return { type: 'not_found', description: 'File or resource not found' }
+  }
+  if (lastError.includes('syntax') || lastError.includes('parse')) {
+    return { type: 'syntax', description: 'Syntax or parsing error' }
+  }
+  if (lastError.includes('timeout') || lastError.includes('timed out')) {
+    return { type: 'timeout', description: 'Operation timed out' }
+  }
+  if (lastError.includes('network') || lastError.includes('connection')) {
+    return { type: 'network', description: 'Network or connection issue' }
+  }
+  // Config pattern MUST be checked before validation (since "invalid config" contains both)
+  if (lastError.includes('config') || lastError.includes('configuration')) {
+    return { type: 'config', description: 'Configuration issue' }
+  }
+  if (lastError.includes('validation') || lastError.includes('invalid')) {
+    return { type: 'validation', description: 'Validation failed' }
+  }
+
+  return { type: 'unknown', description: 'Unrecognized error pattern' }
+}
+
+/**
+ * Generate user-friendly escalation message
+ */
+export function generateEscalationMessage(command: string, errorPattern: ErrorPattern, maxAttempts: number): string {
+  const messages: Record<string, string> = {
+    permission: `I've tried ${command} ${maxAttempts} times but keep hitting permission issues.`,
+    not_found: `After ${maxAttempts} attempts, I still can't find the required file or resource.`,
+    syntax: `I'm encountering repeated syntax errors with ${command}.`,
+    timeout: `The operation keeps timing out after ${maxAttempts} attempts.`,
+    network: `Network issues are preventing ${command} from completing.`,
+    validation: `Validation keeps failing for ${command}.`,
+    config: `There seems to be a configuration issue affecting ${command}.`,
+    unknown: `I've tried ${command} ${maxAttempts} times without success.`,
+  }
+
+  return messages[errorPattern.type] || messages.unknown
+}
+
+/**
+ * Generate actionable suggestion based on error pattern
+ */
+export function generateSuggestion(errorPattern: ErrorPattern): string {
+  const suggestions: Record<string, string> = {
+    permission: 'Check file permissions. Try: chmod -R u+w ~/.prjct-cli/',
+    not_found: 'Verify the file path exists. Run /p:init if project not initialized.',
+    syntax: 'Check the file format. There may be invalid JSON or markdown.',
+    timeout: 'Check your network connection or try again in a moment.',
+    network: 'Verify internet connection and try again.',
+    validation: 'Review the input parameters and try with different values.',
+    config: 'Check .prjct/prjct.config.json for issues. Try /p:init to reinitialize.',
+    unknown: 'Can you check the issue manually and provide more context?',
+  }
+
+  return suggestions[errorPattern.type] || suggestions.unknown
+}

package/core/agentic/loop-detector/hallucination.ts

@@ -0,0 +1,71 @@
+/**
+ * Hallucination Detection
+ * ANTI-HALLUCINATION: Patterns that indicate Claude may be hallucinating
+ */
+
+import type { HallucinationPattern, HallucinationResult } from './types'
+
+/**
+ * ANTI-HALLUCINATION: Patterns that indicate Claude may be hallucinating
+ * These patterns detect contradictory or impossible statements
+ */
+export const HALLUCINATION_PATTERNS: HallucinationPattern[] = [
+  // Contradictory file operations
+  { pattern: /file.*not found.*created/i, type: 'contradiction', description: 'Claims file created but also not found' },
+  { pattern: /created.*but.*error/i, type: 'contradiction', description: 'Claims success but also error' },
+  { pattern: /successfully.*failed/i, type: 'contradiction', description: 'Contradictory success/failure' },
+
+  // Impossible task states
+  {
+    pattern: /already.*completed.*completing/i,
+    type: 'state',
+    description: 'Completing already-completed task',
+  },
+  { pattern: /no task.*marking complete/i, type: 'state', description: 'Completing non-existent task' },
+  { pattern: /no.*active.*done with/i, type: 'state', description: 'Finishing task that doesnt exist' },
+
+  // Invented data
+  {
+    pattern: /version.*updated.*no package/i,
+    type: 'invented',
+    description: 'Version update without package.json',
+  },
+  { pattern: /committed.*nothing to commit/i, type: 'invented', description: 'Commit without changes' },
+  { pattern: /pushed.*no remote/i, type: 'invented', description: 'Push without remote' },
+]
+
+/**
+ * Get suggestion for handling detected hallucination
+ */
+export function getHallucinationSuggestion(type: string): string {
+  const suggestions: Record<string, string> = {
+    contradiction: 'Verify file/resource state before reporting. Use Read tool to check actual state.',
+    state: 'Check current task state from now.md before assuming completion.',
+    invented: 'Verify prerequisites exist (package.json, git remote) before claiming actions.',
+  }
+  return suggestions[type] || 'Verify actual state before proceeding.'
+}
+
+/**
+ * Detect potential hallucination patterns in output
+ */
+export function detectHallucination(output: string): HallucinationResult {
+  if (!output || typeof output !== 'string') {
+    return { detected: false }
+  }
+
+  for (const { pattern, type, description } of HALLUCINATION_PATTERNS) {
+    if (pattern.test(output)) {
+      return {
+        detected: true,
+        type,
+        pattern: pattern.source,
+        description,
+        message: `Potential hallucination detected: ${description}`,
+        suggestion: getHallucinationSuggestion(type),
+      }
+    }
+  }
+
+  return { detected: false }
+}

package/core/agentic/loop-detector/index.ts

@@ -0,0 +1,41 @@
+/**
+ * Loop Detection & User Escalation
+ *
+ * Detects when commands are failing repeatedly and escalates to user
+ * instead of continuing in infinite loops.
+ *
+ * OPTIMIZATION (P2.4): Loop Detection
+ * - Track attempt counts per command/error type
+ * - Auto-escalate after 3 failed attempts
+ * - Provide specific help based on error patterns
+ *
+ * ANTI-HALLUCINATION: Detects contradictory/impossible outputs
+ * - Patterns that indicate Claude is hallucinating (saying file exists when it doesn't)
+ * - Contradictory statements in same response
+ * - Completing tasks that were never started
+ *
+ * Source: Augment Code pattern
+ * "If you notice yourself going around in circles... ask the user for help"
+ */
+
+export type {
+  ErrorEntry,
+  AttemptRecord,
+  ErrorPattern,
+  EscalationInfo,
+  AttemptResult,
+  AttemptInfo,
+  HallucinationPattern,
+  HallucinationResult,
+  OutputAnalysis,
+} from './types'
+
+export { HALLUCINATION_PATTERNS, detectHallucination, getHallucinationSuggestion } from './hallucination'
+export { isSimilarError, analyzeErrorPattern, generateEscalationMessage, generateSuggestion } from './error-analysis'
+export { LoopDetector } from './loop-detector'
+
+import { LoopDetector } from './loop-detector'
+
+// Singleton instance
+const loopDetector = new LoopDetector()
+export default loopDetector