helloagents 3.0.2-beta.1 → 3.0.7

package/scripts/delivery-gate.mjs

@@ -0,0 +1,256 @@
+#!/usr/bin/env node
+/**
+ * HelloAGENTS Delivery Gate — workflow-aware completion gate
+ * Blocks "done" style close-out messages when the active plan package is still open
+ * or when the plan artifacts are incomplete enough that delivery is not trustworthy.
+ */
+import { readFileSync } from 'node:fs'
+import { getAdvisorEvidenceStatus } from './advisor-state.mjs'
+import { getCloseoutEvidenceStatus } from './closeout-state.mjs'
+import { getAdvisorRequirement, getVisualValidationRequirement } from './plan-contract.mjs'
+import { getVisualEvidenceStatus } from './visual-state.mjs'
+import { buildDeliveryGateHint, getDeliveryAction, getWorkflowRecommendation, getWorkflowSnapshot } from './workflow-state.mjs'
+import { getReviewEvidenceStatus } from './review-state.mjs'
+import { getVerifyEvidenceStatus } from './verify-state.mjs'
+
+function selectGatePlans(snapshot) {
+  if (snapshot.activePlans.length > 0) return snapshot.activePlans
+  return snapshot.plans
+}
+
+function buildUnderSpecifiedDetails(entry) {
+  return entry.taskSummary.underSpecifiedItems
+    .slice(0, 3)
+    .map((item) => {
+      const missing = []
+      if (item.files.length === 0) missing.push('missing files')
+      if (!item.acceptance) missing.push('missing acceptance')
+      if (!item.validation) missing.push('missing validation')
+      return `${item.text} (${missing.join(', ')})`
+    })
+}
+
+function collectTaskMetadataIssues(entry, issues) {
+  if (entry.taskSummary.underSpecifiedCount === 0) return
+  issues.push({
+    type: 'under-specified-tasks',
+    planName: entry.planName,
+    details: buildUnderSpecifiedDetails(entry),
+    extraCount: Math.max(entry.taskSummary.underSpecifiedCount - 3, 0),
+  })
+}
+
+function collectPlanIssues(planEntries) {
+  const issues = []
+
+  for (const entry of planEntries) {
+    if (entry.missingFiles.length > 0) {
+      issues.push({
+        type: 'missing-files',
+        planName: entry.planName,
+        details: entry.missingFiles.map((file) => `missing ${file}`),
+      })
+    }
+
+    if (entry.templateIssues.length > 0) {
+      issues.push({
+        type: 'template-placeholders',
+        planName: entry.planName,
+        details: entry.templateIssues,
+      })
+    }
+
+    if (entry.taskSummary.total === 0) {
+      issues.push({
+        type: 'missing-task-checklist',
+        planName: entry.planName,
+        details: ['tasks.md does not contain any checklist items'],
+      })
+      continue
+    }
+
+    if (entry.taskSummary.open > 0) {
+      issues.push({
+        type: 'unfinished-tasks',
+        planName: entry.planName,
+        details: entry.taskSummary.items
+          .filter((item) => item.status === 'open')
+          .slice(0, 3)
+          .map((item) => item.text),
+        extraCount: Math.max(entry.taskSummary.open - 3, 0),
+      })
+    }
+    collectTaskMetadataIssues(entry, issues)
+
+    if (entry.contractIssues.length > 0) {
+      issues.push({
+        type: 'missing-contract',
+        planName: entry.planName,
+        details: entry.contractIssues,
+      })
+    }
+  }
+
+  return issues
+}
+
+function collectEvidenceIssues(issues, verificationStatus, reviewStatus, advisorStatus, visualStatus, closeoutStatus) {
+  if (verificationStatus?.required && verificationStatus.status !== 'valid') {
+    issues.push({
+      type: 'missing-verify-evidence',
+      planName: 'delivery',
+      details: verificationStatus.details,
+    })
+  }
+
+  if (reviewStatus?.required && reviewStatus.status !== 'valid') {
+    issues.push({
+      type: 'missing-review-evidence',
+      planName: 'delivery',
+      details: reviewStatus.details,
+    })
+  }
+  if (advisorStatus?.required && advisorStatus.status !== 'valid') {
+    issues.push({
+      type: 'missing-advisor-evidence',
+      planName: 'delivery',
+      details: advisorStatus.details,
+    })
+  }
+  if (visualStatus?.required && visualStatus.status !== 'valid') {
+    issues.push({
+      type: 'missing-visual-evidence',
+      planName: 'delivery',
+      details: visualStatus.details,
+    })
+  }
+
+  if (issues.length === 0 && closeoutStatus?.required && closeoutStatus.status !== 'valid') {
+    issues.push({
+      type: 'missing-closeout-evidence',
+      planName: 'delivery',
+      details: closeoutStatus.details,
+    })
+  }
+}
+
+function collectGateIssues(planEntries, verificationStatus, reviewStatus, advisorStatus, visualStatus, closeoutStatus) {
+  const issues = collectPlanIssues(planEntries)
+  collectEvidenceIssues(issues, verificationStatus, reviewStatus, advisorStatus, visualStatus, closeoutStatus)
+  return issues
+}
+
+function issueHeading(issue) {
+  switch (issue.type) {
+    case 'missing-files':
+      return 'active plan package is missing required artifacts'
+    case 'template-placeholders':
+      return 'active plan package still contains template placeholders'
+    case 'missing-task-checklist':
+      return 'active plan package has no executable tasks'
+    case 'unfinished-tasks':
+      return 'active plan package still has unfinished tasks'
+    case 'under-specified-tasks':
+      return 'active plan package has under-specified task metadata'
+    case 'missing-contract':
+      return 'active plan package is missing a trustworthy structured contract'
+    case 'missing-verify-evidence':
+      return 'current workflow is missing fresh verification evidence'
+    case 'missing-review-evidence':
+      return 'current workflow is missing fresh review evidence'
+    case 'missing-advisor-evidence':
+      return 'current workflow is missing fresh advisor evidence'
+    case 'missing-visual-evidence':
+      return 'current workflow is missing fresh visual validation evidence'
+    case 'missing-closeout-evidence':
+      return 'current workflow is missing fresh closeout evidence'
+    default:
+      return 'active plan package is not ready for delivery'
+  }
+}
+
+function buildBlockReason(issues, recommendation, gateHint) {
+  const lines = ['[Delivery Gate] Delivery is blocked because the current workflow state is not closed yet:']
+
+  for (const issue of issues) {
+    lines.push(`- ${issue.planName}: ${issueHeading(issue)}`)
+    for (const detail of issue.details) {
+      lines.push(`  - ${detail}`)
+    }
+    if (issue.extraCount) {
+      lines.push(`  - ...and ${issue.extraCount} more`)
+    }
+  }
+
+  lines.push('')
+  if (recommendation?.nextPath) {
+    lines.push(`Recommended path: ${recommendation.nextPath}`)
+  }
+  if (issues.some((issue) => issue.type === 'missing-closeout-evidence')) {
+    lines.push('Next closeout step: write `.helloagents/.ralph-closeout.json` with `requirementsCoverage` and `deliveryChecklist` before reporting completion.')
+  }
+  if (issues.some((issue) => issue.type === 'missing-visual-evidence')) {
+    lines.push('Next visual step: write `.helloagents/.ralph-visual.json` with `tooling`, `screensChecked`, `statesChecked`, `status`, and `summary` before reporting completion.')
+  }
+  if (gateHint) {
+    lines.push(gateHint)
+  }
+  lines.push('Do not report completion yet. First finish or explicitly close the remaining tasks, or repair the active plan package so it becomes a trustworthy delivery record.')
+  return lines.join('\n')
+}
+
+function main() {
+  let data = {}
+  try {
+    data = JSON.parse(readFileSync(0, 'utf-8'))
+  } catch {}
+  const cwd = data.cwd || process.cwd()
+  const snapshot = getWorkflowSnapshot(cwd)
+  const recommendation = getWorkflowRecommendation(cwd)
+  const verificationStatus = getVerifyEvidenceStatus(cwd)
+  const deliveryAction = getDeliveryAction(cwd)
+  const gatePlans = selectGatePlans(snapshot)
+  const reviewStatus = getReviewEvidenceStatus(cwd, {
+    required: deliveryAction?.phase === 'verify' && deliveryAction?.mode === 'review-first',
+  })
+  if (gatePlans.length === 0) {
+    process.stdout.write(JSON.stringify({ suppressOutput: true }))
+    return
+  }
+
+  const advisorRequirements = gatePlans.map((entry) => getAdvisorRequirement(entry.contract))
+  const advisorStatus = getAdvisorEvidenceStatus(cwd, {
+    required: advisorRequirements.some((entry) => entry.required),
+    focus: advisorRequirements.flatMap((entry) => entry.focus || []),
+  })
+  const visualRequirements = gatePlans.map((entry) => getVisualValidationRequirement(entry.contract))
+  const visualStatus = getVisualEvidenceStatus(cwd, {
+    required: visualRequirements.some((entry) => entry.required),
+    screens: visualRequirements.flatMap((entry) => entry.screens || []),
+    states: visualRequirements.flatMap((entry) => entry.states || []),
+  })
+  const closeoutRequired = (
+    gatePlans.every((entry) => entry.missingFiles.length === 0 && entry.templateIssues.length === 0 && entry.taskSummary.total > 0 && entry.taskSummary.open === 0 && entry.taskSummary.underSpecifiedCount === 0)
+    && (!verificationStatus.required || verificationStatus.status === 'valid')
+    && (!reviewStatus.required || reviewStatus.status === 'valid')
+    && (!advisorStatus.required || advisorStatus.status === 'valid')
+    && (!visualStatus.required || visualStatus.status === 'valid')
+  )
+  const closeoutStatus = getCloseoutEvidenceStatus(cwd, {
+    required: closeoutRequired,
+  })
+
+  const issues = collectGateIssues(gatePlans, verificationStatus, reviewStatus, advisorStatus, visualStatus, closeoutStatus)
+  if (issues.length === 0) {
+    process.stdout.write(JSON.stringify({ suppressOutput: true }))
+    return
+  }
+
+  process.stdout.write(JSON.stringify({
+    decision: 'block',
+    reason: buildBlockReason(issues, recommendation, buildDeliveryGateHint(cwd)),
+    suppressOutput: true,
+  }))
+}
+
+main()

package/scripts/guard-rules.mjs

@@ -0,0 +1,122 @@
+import { readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+
+export const DANGEROUS_PATTERNS = [
+  { pattern: /(sudo\s+)?rm\s+(-[a-zA-Z]*f[a-zA-Z]*\s+)?(-[a-zA-Z]*r[a-zA-Z]*\s+)?(\/|~|\*)/, reason: 'Recursive delete of critical path' },
+  { pattern: /(sudo\s+)?rm\s+(-[a-zA-Z]*r[a-zA-Z]*\s+)?(-[a-zA-Z]*f[a-zA-Z]*\s+)?(\/|~|\*)/, reason: 'Recursive delete of critical path' },
+  { pattern: /(sudo\s+)?rm\s+--recursive/, reason: 'Recursive delete (long option)' },
+  { pattern: /(sudo\s+)?rm\s+-[a-zA-Z]*r[a-zA-Z]*\s+\.\.?(\s|$)/, reason: 'Recursive delete of current/parent directory' },
+  { pattern: /git\s+push\s+(-f|--force)/, reason: 'Force push (specify branch explicitly)' },
+  { pattern: /git\s+reset\s+--hard/, reason: 'Hard reset (destructive operation)' },
+  { pattern: /DROP\s+(DATABASE|TABLE|SCHEMA)/i, reason: 'Database destruction command' },
+  { pattern: /TRUNCATE\s+TABLE/i, reason: 'Table truncation' },
+  { pattern: /chmod\s+777/, reason: 'World-writable permissions' },
+  { pattern: /mkfs\b/, reason: 'Filesystem format command' },
+  { pattern: /dd\s+.*of=\/dev\//, reason: 'Direct device write' },
+  { pattern: /FLUSHALL|FLUSHDB/i, reason: 'Redis data flush' },
+]
+
+export const HIGH_RISK_COMMAND_PATTERNS = [
+  { pattern: /\bnpm\s+publish\b/i, reason: 'Package publish command', gate: 'post-verify' },
+  { pattern: /\bgh\s+release\s+create\b/i, reason: 'Release publication command', gate: 'post-verify' },
+  { pattern: /\bterraform\s+(apply|destroy)\b/i, reason: 'Infrastructure apply/destroy command', gate: 'post-verify' },
+  { pattern: /\b(kubectl|helm)\s+(apply|delete|upgrade|rollback|set|rollout)\b/i, reason: 'Cluster deployment command', gate: 'post-verify' },
+  { pattern: /\b(prisma|drizzle-kit|sequelize-cli|typeorm)\b.*\b(migrate|migration)\b/i, reason: 'Database migration command', gate: 'plan-first' },
+  { pattern: /\b(vercel|wrangler|netlify|flyctl|fly)\b.*\b(deploy|publish)\b/i, reason: 'Deployment command', gate: 'post-verify' },
+]
+
+export const IDEA_SIDE_EFFECT_COMMAND_PATTERNS = [
+  /\b(git\s+(add|commit|merge|rebase|cherry-pick|push|pull|stash|restore|checkout|switch))\b/i,
+  /\b(npm|pnpm|yarn|bun)\s+(install|add|remove|uninstall|update|up|upgrade|publish|version)\b/i,
+  /\b(mkdir|md|touch|cp|copy|mv|move|ren|rename|del|erase|rm|rmdir)\b/i,
+  /\b(new-item|copy-item|move-item|remove-item|rename-item|set-content|add-content|out-file)\b/i,
+  /(^|[^\w])>>?($|[^\w])/,
+]
+
+const SECRET_PATTERNS = [
+  { pattern: /AKIA[0-9A-Z]{16}/, reason: 'AWS Access Key ID detected' },
+  { pattern: /ghp_[a-zA-Z0-9]{36}/, reason: 'GitHub Personal Access Token detected' },
+  { pattern: /github_pat_[a-zA-Z0-9]{22}_[a-zA-Z0-9]{59}/, reason: 'GitHub Fine-grained PAT detected' },
+  { pattern: /sk-[a-zA-Z0-9]{20,}/, reason: 'API secret key pattern detected (sk-)' },
+  { pattern: /key-[a-zA-Z0-9]{20,}/, reason: 'API key pattern detected (key-)' },
+  { pattern: /-----BEGIN (RSA |EC |DSA )?PRIVATE KEY-----/, reason: 'Private key detected' },
+  { pattern: /password\s*[:=]\s*["'][^"']{4,}["']/i, reason: 'Hardcoded password detected' },
+  { pattern: /secret\s*[:=]\s*["'][^"']{4,}["']/i, reason: 'Hardcoded secret detected' },
+  { pattern: /AIza[0-9A-Za-z\-_]{35}/, reason: 'Google API Key detected' },
+  { pattern: /xox[bpras]-[0-9a-zA-Z\-]+/, reason: 'Slack Token detected' },
+  { pattern: /eyJ[A-Za-z0-9\-_]+\.eyJ[A-Za-z0-9\-_]+\.[A-Za-z0-9\-_.+/=]+/, reason: 'JWT token detected' },
+  { pattern: /(postgres|mysql|mongodb(\+srv)?):\/\/[^:]+:[^@]+@/i, reason: 'Database connection string with credentials detected' },
+  { pattern: /sk_live_[a-zA-Z0-9]{24,}/, reason: 'Stripe Secret Key detected' },
+  { pattern: /sk-ant-[a-zA-Z0-9\-]{20,}/, reason: 'Anthropic API Key detected' },
+]
+
+export function scanForSecrets(content) {
+  const warnings = []
+  for (const { pattern, reason } of SECRET_PATTERNS) {
+    if (pattern.test(content)) warnings.push(reason)
+  }
+  return warnings
+}
+
+export function scanHighRiskCommands(command) {
+  const warnings = []
+  for (const entry of HIGH_RISK_COMMAND_PATTERNS) {
+    if (entry.pattern.test(command)) {
+      warnings.push({ ...entry })
+    }
+  }
+  return warnings
+}
+
+export function scanUnrequestedFiles(filePath, toolName) {
+  if (!filePath || toolName?.toLowerCase() !== 'write') return []
+  const basename = filePath.split(/[/\\]/).pop() || ''
+  const warnings = []
+
+  const patterns = [
+    { pattern: /^(SUMMARY|NOTES|TODO|SCRATCH|TEMP)\.(md|txt)$/i, reason: `Unrequested file creation: ${basename}` },
+    {
+      pattern: /^README.*\.md$/i,
+      matches: () => filePath.replace(/\\/g, '/').split('/').length > 4,
+      reason: `Suspicious README creation in nested path: ${basename}`,
+    },
+  ]
+
+  for (const entry of patterns) {
+    if (entry.pattern.test(basename) && (!entry.matches || entry.matches())) {
+      warnings.push(entry.reason)
+    }
+  }
+  return warnings
+}
+
+export function scanDangerousPackages(content, filePath) {
+  const warnings = []
+  if (filePath.endsWith('package.json')) {
+    const dangerousScripts = /("(preinstall|postinstall|preuninstall)")\s*:\s*"[^"]*\b(curl|wget|bash|sh|eval|exec)\b/i
+    if (dangerousScripts.test(content)) {
+      warnings.push('Potentially dangerous lifecycle script in package.json (preinstall/postinstall with curl/wget/bash/eval)')
+    }
+  }
+  const unsafeInstall = /npm install\s+[^-].*--ignore-scripts\s*=\s*false|pip install\s+--trusted-host|pip install\s+http:/i
+  if (unsafeInstall.test(content)) {
+    warnings.push('Unsafe dependency installation pattern detected')
+  }
+  return warnings
+}
+
+export function scanEnvCoverage(filePath) {
+  if (!filePath.endsWith('.env') && !filePath.includes('.env.')) return []
+  let dir = dirname(filePath)
+  for (let i = 0; i < 10; i += 1) {
+    try {
+      const gitignore = readFileSync(join(dir, '.gitignore'), 'utf-8')
+      return gitignore.includes('.env') ? [] : ['.env file written but .gitignore does not contain .env pattern']
+    } catch {
+      const parent = dirname(dir)
+      if (parent === dir) break
+      dir = parent
+    }
+  }
+  return ['.env file written but no .gitignore found']
+}