helloagents 3.0.3-beta.1 → 3.0.7

package/scripts/verify-state.mjs

@@ -0,0 +1,226 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { execSync } from 'node:child_process'
+import { join } from 'node:path'
+import { appendReplayEvent } from './replay-state.mjs'
+import { getProjectVerifyYamlPath } from './project-storage.mjs'
+
+export const VERIFY_EVIDENCE_FILE_NAME = '.ralph-verify.json'
+const VERIFY_EVIDENCE_MAX_AGE_MS = 30 * 60 * 1000
+const SHELL_OPERATORS = /[;&|`$(){}\n\r]/
+
+export function getVerifyEvidencePath(cwd) {
+  return join(cwd, '.helloagents', VERIFY_EVIDENCE_FILE_NAME)
+}
+
+export function readVerifyEvidence(cwd) {
+  try {
+    return JSON.parse(readFileSync(getVerifyEvidencePath(cwd), 'utf-8'))
+  } catch {
+    return null
+  }
+}
+
+export function clearVerifyEvidence(cwd) {
+  rmSync(getVerifyEvidencePath(cwd), { force: true })
+}
+
+function loadVerifyYaml(cwd) {
+  const f = getProjectVerifyYamlPath(cwd)
+  if (!existsSync(f)) return null
+  try {
+    const content = readFileSync(f, 'utf-8')
+    const cmds = []
+    let inCmds = false
+    for (const line of content.split('\n')) {
+      const s = line.trim()
+      if (s.startsWith('commands:')) { inCmds = true; continue }
+      if (inCmds) {
+        if (s.startsWith('- ') && !s.startsWith('# ')) {
+          const cmd = s.slice(2).trim().replace(/^["']|["']$/g, '')
+          if (cmd && !cmd.startsWith('#')) cmds.push(cmd)
+        } else if (s && !s.startsWith('#')) {
+          break
+        }
+      }
+    }
+    return cmds.length ? cmds : null
+  } catch {
+    return null
+  }
+}
+
+function detectFromPackageJson(cwd) {
+  const f = join(cwd, 'package.json')
+  if (!existsSync(f)) return []
+  try {
+    const scripts = JSON.parse(readFileSync(f, 'utf-8')).scripts || {}
+    return ['lint', 'typecheck', 'type-check', 'test', 'build']
+      .filter((k) => k in scripts)
+      .map((k) => `npm run ${k}`)
+  } catch {
+    return []
+  }
+}
+
+function detectFromPyproject(cwd) {
+  const f = join(cwd, 'pyproject.toml')
+  if (!existsSync(f)) return []
+  try {
+    const content = readFileSync(f, 'utf-8')
+    const cmds = []
+    if (content.includes('[tool.ruff')) cmds.push('ruff check .')
+    if (content.includes('[tool.mypy')) cmds.push('mypy .')
+    if (content.includes('[tool.pytest')) cmds.push('pytest --tb=short -q')
+    return cmds
+  } catch {
+    return []
+  }
+}
+
+export function detectCommands(cwd) {
+  const yaml = loadVerifyYaml(cwd)
+  if (yaml?.length) return yaml
+  const pkg = detectFromPackageJson(cwd)
+  if (pkg.length) return pkg
+  return detectFromPyproject(cwd)
+}
+
+export function hasUnsafeVerifyCommand(commands = []) {
+  return commands.some((cmd) => SHELL_OPERATORS.test(cmd))
+}
+
+function readGitDiffStat(cwd, args) {
+  try {
+    return execSync(`git diff --stat ${args}`.trim(), {
+      cwd,
+      encoding: 'utf-8',
+      timeout: 10_000,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim()
+  } catch {
+    return null
+  }
+}
+
+export function captureWorkspaceFingerprint(cwd) {
+  const unstaged = readGitDiffStat(cwd, 'HEAD')
+  const staged = readGitDiffStat(cwd, '--cached')
+  const available = unstaged !== null || staged !== null
+
+  return {
+    available,
+    unstaged: unstaged || '',
+    staged: staged || '',
+    combined: `${unstaged || ''}\n---\n${staged || ''}`.trim(),
+  }
+}
+
+export function writeVerifyEvidence(cwd, { commands = [], fastOnly = false, source = 'ralph-loop' } = {}) {
+  mkdirSync(join(cwd, '.helloagents'), { recursive: true })
+  const payload = {
+    updatedAt: new Date().toISOString(),
+    commands,
+    fastOnly,
+    source,
+    fingerprint: captureWorkspaceFingerprint(cwd),
+  }
+  writeFileSync(getVerifyEvidencePath(cwd), `${JSON.stringify(payload, null, 2)}\n`, 'utf-8')
+  appendReplayEvent(cwd, {
+    event: 'verify_evidence_written',
+    source,
+    details: {
+      commands,
+      fastOnly,
+    },
+    artifacts: ['.helloagents/.ralph-verify.json'],
+  })
+}
+
+function validateVerifyEvidencePresence(commands, evidence) {
+  if (evidence) return null
+  return {
+    required: true,
+    status: 'missing',
+    commands,
+    details: ['missing successful verification evidence for the current workflow'],
+  }
+}
+
+function validateVerifyEvidenceFreshness(cwd, commands, evidence, now) {
+  if (evidence.fastOnly) {
+    return {
+      required: true,
+      status: 'fast-only',
+      commands,
+      evidence,
+      details: ['latest verification evidence only covers subagent fast checks'],
+    }
+  }
+
+  const updatedAt = Date.parse(evidence.updatedAt || '')
+  if (!Number.isFinite(updatedAt)) {
+    return {
+      required: true,
+      status: 'invalid',
+      commands,
+      evidence,
+      details: ['verification evidence timestamp is invalid'],
+    }
+  }
+  if (now - updatedAt > VERIFY_EVIDENCE_MAX_AGE_MS) {
+    return {
+      required: true,
+      status: 'stale-time',
+      commands,
+      evidence,
+      details: ['verification evidence is older than 30 minutes'],
+    }
+  }
+  return null
+}
+
+function validateVerifyFingerprint(cwd, commands, evidence) {
+  const currentFingerprint = captureWorkspaceFingerprint(cwd)
+  if (
+    currentFingerprint.available
+    && evidence.fingerprint?.available
+    && currentFingerprint.combined !== evidence.fingerprint.combined
+  ) {
+    return {
+      required: true,
+      status: 'stale-diff',
+      commands,
+      evidence,
+      details: ['workspace diff changed after the last successful verification evidence'],
+    }
+  }
+  return null
+}
+
+export function getVerifyEvidenceStatus(cwd, now = Date.now()) {
+  const commands = detectCommands(cwd)
+  if (!commands.length) {
+    return {
+      required: false,
+      status: 'not-applicable',
+      commands,
+    }
+  }
+
+  const evidence = readVerifyEvidence(cwd)
+  const missingError = validateVerifyEvidencePresence(commands, evidence)
+  if (missingError) return missingError
+
+  const freshnessError = validateVerifyEvidenceFreshness(cwd, commands, evidence, now)
+  if (freshnessError) return freshnessError
+
+  const fingerprintError = validateVerifyFingerprint(cwd, commands, evidence)
+  if (fingerprintError) return fingerprintError
+
+  return {
+    required: true,
+    status: 'valid',
+    commands,
+    evidence,
+  }
+}

package/scripts/visual-state.mjs

@@ -0,0 +1,244 @@
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { appendReplayEvent } from './replay-state.mjs'
+import { captureWorkspaceFingerprint } from './verify-state.mjs'
+
+export const VISUAL_EVIDENCE_FILE_NAME = '.ralph-visual.json'
+const VISUAL_EVIDENCE_MAX_AGE_MS = 30 * 60 * 1000
+const VALID_VISUAL_STATUSES = new Set(['PASS', 'BLOCKED'])
+
+function normalizeStringArray(values) {
+  if (!Array.isArray(values)) return []
+  return [...new Set(values.map((value) => (typeof value === 'string' ? value.trim() : '')).filter(Boolean))]
+}
+
+function normalizeVisualStatus(value) {
+  const normalized = typeof value === 'string' ? value.trim().toUpperCase() : ''
+  return VALID_VISUAL_STATUSES.has(normalized) ? normalized : ''
+}
+
+function findMissingCoverage(requested = [], completed = []) {
+  const completedSet = new Set(normalizeStringArray(completed))
+  return normalizeStringArray(requested).filter((entry) => !completedSet.has(entry))
+}
+
+export function getVisualEvidencePath(cwd) {
+  return join(cwd, '.helloagents', VISUAL_EVIDENCE_FILE_NAME)
+}
+
+export function readVisualEvidence(cwd) {
+  try {
+    return JSON.parse(readFileSync(getVisualEvidencePath(cwd), 'utf-8'))
+  } catch {
+    return null
+  }
+}
+
+export function clearVisualEvidence(cwd) {
+  rmSync(getVisualEvidencePath(cwd), { force: true })
+}
+
+export function normalizeVisualEvidence(input = {}) {
+  return {
+    source: typeof input.source === 'string' && input.source.trim() ? input.source.trim() : 'manual',
+    originCommand: typeof input.originCommand === 'string' ? input.originCommand.trim() : '',
+    reason: typeof input.reason === 'string' ? input.reason.trim() : '',
+    tooling: normalizeStringArray(input.tooling),
+    screensChecked: normalizeStringArray(input.screensChecked),
+    statesChecked: normalizeStringArray(input.statesChecked),
+    status: normalizeVisualStatus(input.status),
+    summary: typeof input.summary === 'string' ? input.summary.trim() : '',
+    findings: normalizeStringArray(input.findings),
+    recommendations: normalizeStringArray(input.recommendations),
+  }
+}
+
+export function writeVisualEvidence(cwd, input = {}) {
+  mkdirSync(join(cwd, '.helloagents'), { recursive: true })
+  const normalized = normalizeVisualEvidence(input)
+  const payload = {
+    updatedAt: new Date().toISOString(),
+    ...normalized,
+    fingerprint: captureWorkspaceFingerprint(cwd),
+  }
+  writeFileSync(getVisualEvidencePath(cwd), `${JSON.stringify(payload, null, 2)}\n`, 'utf-8')
+  appendReplayEvent(cwd, {
+    event: 'visual_evidence_written',
+    source: normalized.source,
+    skillName: normalized.originCommand,
+    details: {
+      reason: normalized.reason,
+      tooling: normalized.tooling,
+      screensChecked: normalized.screensChecked,
+      statesChecked: normalized.statesChecked,
+      status: normalized.status,
+    },
+    artifacts: ['.helloagents/.ralph-visual.json'],
+  })
+  return payload
+}
+
+function readRequiredVisualEvidence(cwd, required) {
+  if (!required) {
+    return {
+      required: false,
+      status: 'not-applicable',
+    }
+  }
+
+  const evidence = readVisualEvidence(cwd)
+  if (evidence) return { evidence }
+  return {
+    error: {
+      required: true,
+      status: 'missing',
+      details: ['missing visual validation evidence required by the active UI contract'],
+    },
+  }
+}
+
+function validateVisualTimestamp(evidence, now) {
+  const updatedAt = Date.parse(evidence.updatedAt || '')
+  if (!Number.isFinite(updatedAt)) {
+    return {
+      required: true,
+      status: 'invalid',
+      evidence,
+      details: ['visual validation evidence timestamp is invalid'],
+    }
+  }
+  if (now - updatedAt > VISUAL_EVIDENCE_MAX_AGE_MS) {
+    return {
+      required: true,
+      status: 'stale-time',
+      evidence,
+      details: ['visual validation evidence is older than 30 minutes'],
+    }
+  }
+  return null
+}
+
+function validateVisualFingerprint(cwd, evidence) {
+  const currentFingerprint = captureWorkspaceFingerprint(cwd)
+  if (
+    currentFingerprint.available
+    && evidence.fingerprint?.available
+    && currentFingerprint.combined !== evidence.fingerprint.combined
+  ) {
+    return {
+      required: true,
+      status: 'stale-diff',
+      evidence,
+      details: ['workspace diff changed after the last visual validation evidence'],
+    }
+  }
+  return null
+}
+
+function validateVisualContent(evidence, { screens = [], states = [] } = {}) {
+  const normalized = normalizeVisualEvidence(evidence)
+  if (!normalized.status || !normalized.summary || !normalized.reason) {
+    return {
+      required: true,
+      status: 'invalid',
+      evidence,
+      details: ['visual validation evidence must record explicit status, reason, and summary'],
+    }
+  }
+  if (normalized.tooling.length === 0) {
+    return {
+      required: true,
+      status: 'invalid',
+      evidence,
+      details: ['visual validation evidence must record the tooling used for the check'],
+    }
+  }
+  if (normalized.screensChecked.length === 0 && normalized.statesChecked.length === 0) {
+    return {
+      required: true,
+      status: 'invalid',
+      evidence,
+      details: ['visual validation evidence must record at least one checked screen or state'],
+    }
+  }
+
+  const missingScreens = findMissingCoverage(screens, normalized.screensChecked)
+  if (missingScreens.length > 0) {
+    return {
+      required: true,
+      status: 'invalid',
+      evidence,
+      details: [`visual validation evidence does not cover requested screens: ${missingScreens.join(', ')}`],
+    }
+  }
+
+  const missingStates = findMissingCoverage(states, normalized.statesChecked)
+  if (missingStates.length > 0) {
+    return {
+      required: true,
+      status: 'invalid',
+      evidence,
+      details: [`visual validation evidence does not cover requested states: ${missingStates.join(', ')}`],
+    }
+  }
+
+  if (normalized.status !== 'PASS') {
+    return {
+      required: true,
+      status: 'blocked',
+      evidence,
+      details: ['latest visual validation evidence still records blocking findings'],
+    }
+  }
+  return null
+}
+
+export function getVisualEvidenceStatus(cwd, { required = false, screens = [], states = [], now = Date.now() } = {}) {
+  const requiredEvidence = readRequiredVisualEvidence(cwd, required)
+  if ('status' in requiredEvidence) return requiredEvidence
+  if (requiredEvidence.error) return requiredEvidence.error
+
+  const { evidence } = requiredEvidence
+  const timestampError = validateVisualTimestamp(evidence, now)
+  if (timestampError) return timestampError
+
+  const fingerprintError = validateVisualFingerprint(cwd, evidence)
+  if (fingerprintError) return fingerprintError
+
+  const contentError = validateVisualContent(evidence, { screens, states })
+  if (contentError) return contentError
+
+  return {
+    required: true,
+    status: 'valid',
+    evidence: normalizeVisualEvidence(evidence),
+  }
+}
+
+function readStdinJson() {
+  try {
+    return JSON.parse(readFileSync(0, 'utf-8'))
+  } catch {
+    return {}
+  }
+}
+
+function main() {
+  const command = process.argv[2] || ''
+  if (command !== 'write') return
+
+  const input = readStdinJson()
+  const cwd = input.cwd || process.cwd()
+  const payload = writeVisualEvidence(cwd, input)
+  process.stdout.write(JSON.stringify({
+    suppressOutput: true,
+    path: getVisualEvidencePath(cwd),
+    payload,
+  }))
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+  main()
+}

package/scripts/workflow-core.mjs

@@ -0,0 +1,165 @@
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+
+import {
+  getWorkflowSnapshot,
+  listPlanPackages,
+  normalizeTaskFile,
+  readStateSnapshot,
+} from './workflow-plan-files.mjs'
+import { getAdvisorRequirement, getVisualValidationRequirement } from './plan-contract.mjs'
+import { describeProjectStoreFile, getProjectDesignContractPath } from './project-storage.mjs'
+
+export function getTargetPlans(snapshot) {
+  return snapshot.activePlans.length > 0 ? snapshot.activePlans : snapshot.plans
+}
+export function classifyPlan(plan) {
+  if (!plan) {
+    return {
+      status: 'none',
+      details: [],
+    }
+  }
+
+  const details = [
+    ...plan.missingFiles.map((file) => `缺少 ${file}`),
+    ...plan.templateIssues,
+  ]
+
+  if (details.length > 0) {
+    return {
+      status: 'incomplete',
+      details,
+    }
+  }
+
+  if (plan.taskSummary.total === 0) {
+    return {
+      status: 'missing-task-checklist',
+      details: ['tasks.md 尚未形成可执行 checklist'],
+    }
+  }
+
+  if (plan.taskSummary.open > 0) {
+    return {
+      status: 'in-progress',
+      details: plan.taskSummary.items
+        .filter((item) => item.status === 'open')
+        .slice(0, 3)
+        .map((item) => item.text),
+      openCount: plan.taskSummary.open,
+    }
+  }
+
+  return {
+    status: 'closed',
+    details: [],
+  }
+}
+
+export function determineVerifyMode(plan) {
+  if (!plan) return null
+
+  if (plan.contractIssues.length > 0) {
+    return {
+      mode: 'metadata-first',
+      reason: '方案包缺少可信的结构化 contract',
+      guidance: '验证分流：当前还不适合直接进入 reviewer / tester；先回到 ~plan / ~prd 补齐 `contract.json`，明确 `verifyMode`、`reviewerFocus` 和 `testerFocus`。',
+    }
+  }
+
+  if (plan.contract?.verifyMode === 'review-first') {
+    const reviewerFocus = plan.contract.reviewerFocus.join('；')
+    const testerFocus = plan.contract.testerFocus.join('；')
+    return {
+      mode: 'review-first',
+      reason: '方案 contract 已明确要求审查优先',
+      guidance: `验证分流：当前更适合审查优先；先执行 reviewer / hello-review 范围审查，再交给 tester / hello-verify 跑完整验证。${reviewerFocus ? ` reviewer 重点：${reviewerFocus}。` : ''}${testerFocus ? ` tester 重点：${testerFocus}。` : ''}`.trim(),
+    }
+  }
+
+  if (plan.taskSummary.underSpecifiedCount > 0) {
+    return {
+      mode: 'metadata-first',
+      reason: 'tasks.md 仍缺少可信的任务元数据',
+      guidance: '验证分流：当前还不适合直接进入 reviewer / tester；先补齐 tasks.md 中每个任务的“涉及文件”“完成标准”和“验证方式”。',
+    }
+  }
+
+  return {
+    mode: 'test-first',
+    reason: '方案 contract 已明确验证主路径，且任务 contract 已完整',
+    guidance: `验证分流：当前更适合测试优先；先执行 tester / hello-verify 跑完整验证，再针对失败点或关键边界补充 hello-review。${plan.contract?.testerFocus?.length ? ` tester 重点：${plan.contract.testerFocus.join('；')}。` : ''}`.trim(),
+  }
+}
+
+function collectStateSyncIssues(snapshot) {
+  const issues = []
+  const hasPlans = snapshot.plans.length > 0
+  const state = snapshot.state
+
+  if (!hasPlans) {
+    return issues
+  }
+
+  if (!state.exists) {
+    issues.push('当前已存在方案包，但 `.helloagents/STATE.md` 缺失')
+    return issues
+  }
+
+  if (!state.referencedPlanDir) {
+    issues.push('当前已存在方案包，但 `STATE.md` 未记录活跃方案路径')
+  }
+  if (!state.sections['主线目标']) {
+    issues.push('`STATE.md` 缺少“主线目标”')
+  }
+  if (!state.sections['正在做什么']) {
+    issues.push('`STATE.md` 缺少“正在做什么”')
+  }
+  if (!state.sections['下一步']) {
+    issues.push('`STATE.md` 缺少“下一步”')
+  }
+
+  return issues
+}
+
+export function buildVerifyModeHintFromSnapshot(snapshot) {
+  const plan = getTargetPlans(snapshot)[0]
+  if (!plan) return ''
+  if (!plan.planSections['风险与验证'] && plan.taskSummary.total === 0) return ''
+  return determineVerifyMode(plan)?.guidance || ''
+}
+export function buildStateSyncHintFromSnapshot(snapshot) {
+  const issues = collectStateSyncIssues(snapshot)
+  if (issues.length === 0) return ''
+  return `STATE.md 提醒：${issues.join('；')}；继续项目级流程、收尾或进入压缩前先同步恢复快照。`
+}
+
+export function buildStateRoleHintFromSnapshot(snapshot) {
+  if (!snapshot.state.exists || snapshot.plans.length > 0) return ''
+  return '恢复约束：当前仅检测到 `.helloagents/STATE.md`；先以当前用户消息、显式命令和代码事实确认主线，STATE.md 只用于找回上次停在哪，不是当前任务的自动授权或唯一事实源。'
+}
+
+export function buildUiContractHint(cwd, snapshot) {
+  const targetPlans = getTargetPlans(snapshot)
+  const hasDesignContract = existsSync(getProjectDesignContractPath(cwd))
+  const hasPrdUiArtifact = targetPlans.some((plan) => existsSync(join(plan.dirPath, 'prd', '03-ui-design.md')))
+  const hasUiContract = targetPlans.some((plan) => plan.contract?.ui?.required)
+  const styleAdvisorRequired = targetPlans.some((plan) => getAdvisorRequirement(plan.contract).styleRequired)
+  const visualValidationRequired = targetPlans.some((plan) => getVisualValidationRequirement(plan.contract).required)
+
+  if (!hasDesignContract && !hasPrdUiArtifact && !hasUiContract) {
+    return ''
+  }
+
+  const extraHints = []
+  if (styleAdvisorRequired) {
+    extraHints.push('若当前 UI contract 要求 style advisor，收尾前需复用 `.helloagents/.ralph-advisor.json` 留下独立复查证据')
+  }
+  if (visualValidationRequired) {
+    extraHints.push('若当前 UI contract 要求视觉验收，收尾前需写 `.helloagents/.ralph-visual.json` 记录关键视口、状态与结论')
+  }
+  return `UI 约束提示：如本次属于视觉/交互链路，设计决策优先级固定为：当前活跃 plan.md / prd/03-ui-design.md → ${describeProjectStoreFile(cwd, 'DESIGN.md')} → hello-ui。${extraHints.length > 0 ? ` ${extraHints.join('；')}。` : ''}`
+}
+
+export { normalizeTaskFile, readStateSnapshot, listPlanPackages, getWorkflowSnapshot }