helloagents 3.0.2-beta.1 → 3.0.7

package/scripts/workflow-plan-files.mjs

@@ -0,0 +1,249 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { isAbsolute, join, normalize } from 'node:path'
+
+import { getPlanContractIssues, readPlanContract } from './plan-contract.mjs'
+import { getProjectPlansDir, getProjectStatePath, resolveProjectPlanDir } from './project-storage.mjs'
+
+const PLAN_TEMPLATE_MARKERS = {
+  'requirements.md': [
+    /# \{项目\/功能名称\} — 需求/,
+    /\[解决什么问题？给谁用？\]/,
+    /\[必须有什么？不需要什么？\]/,
+  ],
+  'plan.md': [
+    /# \{项目\/功能名称\} — 实施规划/,
+    /\[本次要解决的问题、范围边界、验收目标\]/,
+    /\[关键决策及理由\]/,
+    /\[功能完成时必须为真的条件、关键验收点、reviewer \/ tester 关注边界\]/,
+  ],
+  'tasks.md': [
+    /# \{项目\/功能名称\} — 任务分解/,
+    /\[按执行顺序排列，每个任务独立可验证\]/,
+    /- \[ \] 任务1：描述/,
+  ],
+}
+
+function readText(filePath) {
+  try {
+    return readFileSync(filePath, 'utf-8')
+  } catch {
+    return ''
+  }
+}
+
+function parseMarkdownSections(content = '') {
+  const sections = {}
+  let currentTitle = ''
+  let currentLines = []
+
+  for (const line of content.split(/\r?\n/)) {
+    const match = line.match(/^##\s+(.+?)\s*$/)
+    if (match) {
+      if (currentTitle) {
+        sections[currentTitle] = currentLines.join('\n').trim()
+      }
+      currentTitle = match[1].trim()
+      currentLines = []
+      continue
+    }
+    if (currentTitle) {
+      currentLines.push(line)
+    }
+  }
+
+  if (currentTitle) {
+    sections[currentTitle] = currentLines.join('\n').trim()
+  }
+
+  return sections
+}
+
+function normalizePlanRef(rawValue) {
+  return (rawValue || '')
+    .replace(/[`'"]/g, '')
+    .split(/\r?\n/)[0]
+    .trim()
+}
+
+function resolvePlanDir(cwd, rawValue) {
+  const value = normalizePlanRef(rawValue)
+  if (!value || value === '（无）' || value === '(无)') return ''
+
+  if (isAbsolute(value)) {
+    return normalize(value.replace(/[\\/]+$/, ''))
+  }
+
+  const match = value.match(/(?:\.helloagents[\\/])?plans[\\/][^\s/\\]+/)
+  if (!match) return ''
+  return resolveProjectPlanDir(cwd, match[0])
+}
+
+function splitTaskMetaValues(rawValue = '') {
+  return rawValue
+    .split(/[，,、]/)
+    .map((value) => value.replace(/[`'"]/g, '').trim())
+    .filter(Boolean)
+}
+
+export function normalizeTaskFile(filePath = '') {
+  return filePath.replace(/\\/g, '/').replace(/[`'"]/g, '').trim().toLowerCase()
+}
+
+function extractTaskFiles(text = '') {
+  const explicitMatch = text.match(/涉及文件\s*[:：]\s*([^)）;；]+)/)
+  if (explicitMatch) {
+    return splitTaskMetaValues(explicitMatch[1])
+  }
+
+  const matches = text.match(/(?:[A-Za-z0-9_.-]+[\\/])+[A-Za-z0-9_.-]+(?:\.[A-Za-z0-9_.-]+)?/g) || []
+  return [...new Set(matches.map((value) => value.trim()))]
+}
+
+function extractTaskValidation(text = '') {
+  const validationMatch = text.match(/验证方式\s*[:：]\s*([^)）]+)/)
+  return validationMatch ? validationMatch[1].trim() : ''
+}
+
+function extractTaskAcceptance(text = '') {
+  const acceptanceMatch = text.match(/完成标准\s*[:：]\s*([^)）;；]+)/)
+  return acceptanceMatch ? acceptanceMatch[1].trim() : ''
+}
+
+function summarizeTasks(taskPath) {
+  if (!existsSync(taskPath)) {
+    return {
+      exists: false,
+      total: 0,
+      open: 0,
+      done: 0,
+      skipped: 0,
+      cancelled: 0,
+      items: [],
+    }
+  }
+
+  const items = []
+  for (const rawLine of readText(taskPath).split(/\r?\n/)) {
+    const line = rawLine.trim()
+    const match = line.match(/^-\s+\[([^\]])\]\s+(.+)$/)
+    if (!match) continue
+    const marker = match[1]
+    const text = match[2].trim()
+    let status = 'open'
+
+    if (marker === '√') status = 'done'
+    else if (marker === '-') status = 'skipped'
+    else if (marker.toUpperCase() === 'X') status = 'cancelled'
+
+    items.push({
+      status,
+      text,
+      files: extractTaskFiles(text),
+      acceptance: extractTaskAcceptance(text),
+      validation: extractTaskValidation(text),
+    })
+  }
+
+  return {
+    exists: true,
+    total: items.length,
+    open: items.filter((item) => item.status === 'open').length,
+    done: items.filter((item) => item.status === 'done').length,
+    skipped: items.filter((item) => item.status === 'skipped').length,
+    cancelled: items.filter((item) => item.status === 'cancelled').length,
+    underSpecifiedCount: items.filter((item) => item.files.length === 0 || !item.acceptance || !item.validation).length,
+    underSpecifiedOpenCount: items.filter((item) => item.status === 'open' && (item.files.length === 0 || !item.acceptance || !item.validation)).length,
+    underSpecifiedItems: items.filter((item) => item.files.length === 0 || !item.acceptance || !item.validation),
+    items,
+  }
+}
+
+function findTemplateIssues(fileName, filePath) {
+  if (!existsSync(filePath)) return []
+  const content = readText(filePath)
+  return (PLAN_TEMPLATE_MARKERS[fileName] || [])
+    .filter((pattern) => pattern.test(content))
+    .map(() => `${fileName} still contains template placeholders`)
+}
+
+function comparePlanEntries(a, b) {
+  return a.planName.localeCompare(b.planName)
+}
+
+export function readStateSnapshot(cwd) {
+  const statePath = getProjectStatePath(cwd)
+  const content = readText(statePath)
+  const sections = parseMarkdownSections(content)
+  const referencedPlanDir = resolvePlanDir(cwd, sections['方案'])
+
+  return {
+    statePath,
+    exists: existsSync(statePath),
+    content,
+    sections,
+    referencedPlanDir,
+  }
+}
+
+export function listPlanPackages(cwd) {
+  const plansDir = getProjectPlansDir(cwd)
+  if (!existsSync(plansDir)) return []
+
+  return readdirSync(plansDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => {
+      const dirPath = join(plansDir, entry.name)
+      const filePaths = {
+        requirementsPath: join(dirPath, 'requirements.md'),
+        planPath: join(dirPath, 'plan.md'),
+        taskPath: join(dirPath, 'tasks.md'),
+      }
+      const missingFiles = Object.entries({
+        'requirements.md': filePaths.requirementsPath,
+        'plan.md': filePaths.planPath,
+        'tasks.md': filePaths.taskPath,
+      })
+        .filter(([, pathValue]) => !existsSync(pathValue))
+        .map(([name]) => name)
+      const taskSummary = summarizeTasks(filePaths.taskPath)
+      const planSections = parseMarkdownSections(readText(filePaths.planPath))
+      const contract = readPlanContract(dirPath)
+      const contractIssues = getPlanContractIssues(contract)
+      const templateIssues = [
+        ...findTemplateIssues('requirements.md', filePaths.requirementsPath),
+        ...findTemplateIssues('plan.md', filePaths.planPath),
+        ...findTemplateIssues('tasks.md', filePaths.taskPath),
+      ]
+
+      return {
+        planName: entry.name,
+        dirPath,
+        relativePath: `.helloagents/plans/${entry.name}`,
+        missingFiles,
+        planSections,
+        taskSummary,
+        contract,
+        contractIssues,
+        templateIssues,
+      }
+    })
+    .sort(comparePlanEntries)
+}
+
+export function getWorkflowSnapshot(cwd) {
+  const state = readStateSnapshot(cwd)
+  const plans = listPlanPackages(cwd).map((entry) => ({
+    ...entry,
+    referencedByState: state.referencedPlanDir ? normalize(entry.dirPath) === normalize(state.referencedPlanDir) : false,
+  }))
+
+  const activePlans = state.referencedPlanDir
+    ? plans.filter((entry) => entry.referencedByState)
+    : plans
+
+  return {
+    state,
+    plans,
+    activePlans,
+  }
+}

package/scripts/workflow-recommendation.mjs

@@ -0,0 +1,335 @@
+import { getCloseoutEvidenceStatus } from './closeout-state.mjs'
+import { getAdvisorEvidenceStatus } from './advisor-state.mjs'
+import { getAdvisorRequirement, getVisualValidationRequirement } from './plan-contract.mjs'
+import { getReviewEvidenceStatus } from './review-state.mjs'
+import { getVisualEvidenceStatus } from './visual-state.mjs'
+import { getVerifyEvidenceStatus } from './verify-state.mjs'
+import {
+  classifyPlan,
+  determineVerifyMode,
+  getTargetPlans,
+  normalizeTaskFile,
+} from './workflow-core.mjs'
+
+function getClosedPlanEvidenceStatus(cwd, plan) {
+  const verifyMode = determineVerifyMode(plan)
+  const advisorRequirement = getAdvisorRequirement(plan.contract)
+  const visualRequirement = getVisualValidationRequirement(plan.contract)
+  const verificationStatus = getVerifyEvidenceStatus(cwd)
+  const reviewStatus = getReviewEvidenceStatus(cwd, {
+    required: verifyMode?.mode === 'review-first',
+  })
+  const advisorStatus = getAdvisorEvidenceStatus(cwd, {
+    required: advisorRequirement.required,
+    focus: advisorRequirement.focus,
+  })
+  const visualStatus = getVisualEvidenceStatus(cwd, {
+    required: visualRequirement.required,
+    screens: visualRequirement.screens,
+    states: visualRequirement.states,
+  })
+  const verifyReady = !verificationStatus.required || verificationStatus.status === 'valid'
+  const reviewReady = !reviewStatus.required || reviewStatus.status === 'valid'
+  const advisorReady = !advisorStatus.required || advisorStatus.status === 'valid'
+  const visualReady = !visualStatus.required || visualStatus.status === 'valid'
+  const closeoutStatus = getCloseoutEvidenceStatus(cwd, {
+    required: verifyReady && reviewReady && advisorReady && visualReady,
+  })
+
+  return {
+    verifyMode,
+    advisorRequirement,
+    visualRequirement,
+    verificationStatus,
+    reviewStatus,
+    advisorStatus,
+    visualStatus,
+    closeoutStatus,
+    verifyReady,
+    reviewReady,
+    advisorReady,
+    visualReady,
+    closeoutReady: !closeoutStatus.required || closeoutStatus.status === 'valid',
+  }
+}
+
+function buildConsolidateAction(recommendation) {
+  if (recommendation.mode === 'closeout-pending') {
+    return {
+      phase: 'consolidate',
+      mode: recommendation.mode,
+      routeHint: recommendation.guidance,
+      gateHint: '交付门控：审查与验证证据已满足；先写 `.helloagents/.ralph-closeout.json` 记录需求覆盖与交付清单，再完成 STATE.md / 归档后才可交付。',
+    }
+  }
+
+  return {
+    phase: 'consolidate',
+    mode: recommendation.mode || 'ready',
+    routeHint: recommendation.guidance,
+    gateHint: '交付门控：当前已具备 closeout evidence；完成 STATE.md、知识沉淀与归档后即可交付。',
+  }
+}
+
+function buildVerifyAction(plan, verifyMode) {
+  if (!verifyMode) return null
+  const advisorRequirement = getAdvisorRequirement(plan.contract)
+  const visualRequirement = getVisualValidationRequirement(plan.contract)
+  const extraChecks = []
+  if (advisorRequirement.required) {
+    extraChecks.push('完成独立 advisor / style advisor 复查并写入 `.helloagents/.ralph-advisor.json`')
+  }
+  if (visualRequirement.required) {
+    extraChecks.push('完成视觉验收并写入 `.helloagents/.ralph-visual.json`')
+  }
+  const gateSuffix = extraChecks.length > 0 ? ` ${extraChecks.join('，')}，再进入 CONSOLIDATE。` : ''
+  if (verifyMode.mode === 'review-first') {
+    return {
+      phase: 'verify',
+      mode: verifyMode.mode,
+      routeHint: verifyMode.guidance,
+      gateHint: `交付门控：进入 CONSOLIDATE 前，必须先完成 reviewer / hello-review 范围审查，再完成 tester / hello-verify 全量验证，并留下最新验证证据；两步都通过后才可交付。${gateSuffix}`.trim(),
+    }
+  }
+  if (verifyMode.mode === 'metadata-first') {
+    return {
+      phase: 'verify',
+      mode: verifyMode.mode,
+      routeHint: verifyMode.guidance,
+      gateHint: plan.contractIssues.length > 0
+        ? '交付门控：当前还不能进入 CONSOLIDATE；先补齐 `contract.json` 中的 `verifyMode`、`reviewerFocus`、`testerFocus`，再进入 reviewer / tester。'
+        : '交付门控：当前还不能进入 CONSOLIDATE；先补齐 tasks.md 中每个任务的“涉及文件”“完成标准”和“验证方式”，再进入 reviewer / tester。',
+    }
+  }
+
+  return {
+    phase: 'verify',
+    mode: verifyMode.mode,
+    routeHint: verifyMode.guidance,
+    gateHint: `交付门控：进入 CONSOLIDATE 前，先完成 tester / hello-verify 全量验证并留下最新验证证据，再针对失败点或关键边界补充 hello-review；确认通过后才可交付。${gateSuffix}`.trim(),
+  }
+}
+
+export function buildDeliveryActionFromSnapshot(snapshot, cwd, recommendation = buildRecommendation(snapshot, cwd)) {
+  if (!recommendation) return null
+
+  if (recommendation.stage === 'consolidate') {
+    return buildConsolidateAction(recommendation)
+  }
+
+  const plan = getTargetPlans(snapshot)[0]
+  if (recommendation.nextCommand === 'verify' && plan) {
+    return buildVerifyAction(plan, determineVerifyMode(plan))
+  }
+  if (recommendation.nextCommand === 'build') {
+    return {
+      phase: 'build',
+      gateHint: '交付门控：当前还不能报告完成；先回到 ~build 完成剩余任务，再进入 ~verify。',
+    }
+  }
+  if (recommendation.nextCommand === 'plan') {
+    return {
+      phase: 'plan',
+      gateHint: '交付门控：当前还不能报告完成；先回到 ~plan 修复或补齐当前方案包，再进入 ~build / ~verify。',
+    }
+  }
+
+  return null
+}
+
+export function buildDeliveryGateHintFromSnapshot(snapshot, cwd, recommendation = buildRecommendation(snapshot, cwd)) {
+  return buildDeliveryActionFromSnapshot(snapshot, cwd, recommendation)?.gateHint || ''
+}
+
+function buildPlanRecommendation(scopeLabel, plan, classification) {
+  return {
+    scopeLabel,
+    plan,
+    status: classification.status,
+    details: classification.details,
+    nextCommand: 'plan',
+    nextPath: '~plan -> ~build / ~verify',
+    summary: classification.status === 'incomplete'
+      ? `${scopeLabel} "${plan.planName}" 仍不完整（${classification.details.join('；')}）。`
+      : `${scopeLabel} "${plan.planName}" 尚未形成可执行任务清单。`,
+    guidance: classification.status === 'incomplete'
+      ? '优先先走 ~plan 修复或补全当前方案包，再进入实现或验证；不要把不完整 artifact 直接当成可交付依据。'
+      : '先回到 ~plan 补齐 tasks.md 的原子任务，再进入实现、验证或收尾。',
+  }
+}
+
+function buildInProgressRecommendation(scopeLabel, plan, classification) {
+  return {
+    scopeLabel,
+    plan,
+    status: classification.status,
+    details: classification.details,
+    nextCommand: 'build',
+    nextPath: '~build -> ~verify',
+    summary: `${scopeLabel} "${plan.planName}" 仍有 ${classification.openCount} 个未完成任务。`,
+    guidance: '若用户是在继续当前功能、落实既有方案、或让你“继续做完”，优先复用现有 requirements.md / plan.md / tasks.md 进入 ~build；完成当前实现后再进入 ~verify。除非用户明确要求重规划或现有方案已失效，不要重新回到 ~idea。',
+  }
+}
+
+function buildClosedRecommendation(scopeLabel, plan, cwd) {
+  const closedPlanEvidence = getClosedPlanEvidenceStatus(cwd, plan)
+  if (closedPlanEvidence.verifyMode?.mode === 'metadata-first') {
+    return {
+      scopeLabel,
+      plan,
+      status: 'closed',
+      nextCommand: 'verify',
+      nextPath: '~verify -> CONSOLIDATE',
+      summary: `${scopeLabel} "${plan.planName}" 的任务已全部闭合，但验证 contract 仍未结构化。`,
+      guidance: closedPlanEvidence.verifyMode.guidance,
+    }
+  }
+
+  if (
+    closedPlanEvidence.advisorStatus.required
+    && closedPlanEvidence.advisorStatus.status !== 'valid'
+    && closedPlanEvidence.visualStatus.required
+    && closedPlanEvidence.visualStatus.status !== 'valid'
+  ) {
+    return {
+      scopeLabel,
+      plan,
+      status: 'closed',
+      nextCommand: 'verify',
+      nextPath: '~verify -> CONSOLIDATE',
+      summary: `${scopeLabel} "${plan.planName}" 的任务已闭合，但当前 UI contract 仍要求独立 advisor 复查与视觉验收。`,
+      guidance: '先在 ~verify 阶段完成独立 advisor / style advisor 复查，并写入 `.helloagents/.ralph-advisor.json`；再完成视觉验收并写入 `.helloagents/.ralph-visual.json`，记录 reason、tooling、screensChecked、statesChecked、status 与 summary；两项都通过后再进入 CONSOLIDATE。',
+    }
+  }
+
+  if (closedPlanEvidence.advisorStatus.required && closedPlanEvidence.advisorStatus.status !== 'valid') {
+    return {
+      scopeLabel,
+      plan,
+      status: 'closed',
+      nextCommand: 'verify',
+      nextPath: '~verify -> CONSOLIDATE',
+      summary: `${scopeLabel} "${plan.planName}" 的任务已闭合，但当前 contract 仍要求独立 advisor 复查。`,
+      guidance: '先在 ~verify 阶段完成独立 advisor / style advisor 复查，并写入 `.helloagents/.ralph-advisor.json` 记录复查原因、focus、来源与结论；advisor 通过后再进入 CONSOLIDATE。',
+    }
+  }
+
+  if (closedPlanEvidence.visualStatus.required && closedPlanEvidence.visualStatus.status !== 'valid') {
+    return {
+      scopeLabel,
+      plan,
+      status: 'closed',
+      nextCommand: 'verify',
+      nextPath: '~verify -> CONSOLIDATE',
+      summary: `${scopeLabel} "${plan.planName}" 的任务已闭合，但当前 UI contract 仍要求视觉验收。`,
+      guidance: '先在 ~verify 阶段完成视觉验收，并写入 `.helloagents/.ralph-visual.json` 记录 reason、tooling、screensChecked、statesChecked、status 与 summary；视觉验收通过后再进入 CONSOLIDATE。',
+    }
+  }
+
+  if (closedPlanEvidence.verifyReady && closedPlanEvidence.reviewReady && closedPlanEvidence.advisorReady && closedPlanEvidence.visualReady) {
+    return {
+      scopeLabel,
+      plan,
+      status: 'closed',
+      stage: 'consolidate',
+      mode: closedPlanEvidence.closeoutReady ? 'ready' : 'closeout-pending',
+      nextCommand: 'verify',
+      nextPath: 'CONSOLIDATE',
+      summary: closedPlanEvidence.closeoutReady
+        ? `${scopeLabel} "${plan.planName}" 的任务与交付证据已闭合。`
+        : `${scopeLabel} "${plan.planName}" 的任务、审查与验证已闭合。`,
+      guidance: closedPlanEvidence.closeoutReady
+        ? '当前进入 CONSOLIDATE：完成 `STATE.md`、知识沉淀与方案归档后即可交付；不要无故重开新的方案包或重新跑一遍无关验证。'
+        : '当前进入 CONSOLIDATE：先写 `.helloagents/.ralph-closeout.json` 记录需求覆盖与交付清单，再同步 `STATE.md` / 归档后交付。',
+    }
+  }
+
+  return {
+    scopeLabel,
+    plan,
+    status: 'closed',
+    nextCommand: 'verify',
+    nextPath: '~verify -> CONSOLIDATE',
+    summary: `${scopeLabel} "${plan.planName}" 的任务已全部闭合。`,
+    guidance: '若用户是在做收尾、验真、复查或准备交付，优先走 ~verify 或 CONSOLIDATE；不要无故重开新的方案包。',
+  }
+}
+
+export function buildRecommendation(snapshot, cwd = process.cwd()) {
+  const plan = getTargetPlans(snapshot)[0]
+  if (!plan) return null
+
+  const classification = classifyPlan(plan)
+  const scopeLabel = snapshot.activePlans.length > 0 ? '当前活跃方案包' : '当前存在的方案包'
+
+  if (classification.status === 'incomplete' || classification.status === 'missing-task-checklist') {
+    return buildPlanRecommendation(scopeLabel, plan, classification)
+  }
+  if (classification.status === 'in-progress') {
+    return buildInProgressRecommendation(scopeLabel, plan, classification)
+  }
+  if (classification.status === 'closed') {
+    return buildClosedRecommendation(scopeLabel, plan, cwd)
+  }
+  return null
+}
+
+function findDisjointOpenTaskPair(plan) {
+  const openTasks = plan?.taskSummary?.items?.filter((item) => item.status === 'open') || []
+  const tasksWithFiles = openTasks.filter((item) => item.files.length > 0)
+
+  for (let i = 0; i < tasksWithFiles.length; i += 1) {
+    const left = tasksWithFiles[i]
+    const leftFiles = new Set(left.files.map(normalizeTaskFile))
+    for (let j = i + 1; j < tasksWithFiles.length; j += 1) {
+      const right = tasksWithFiles[j]
+      const overlaps = right.files.some((filePath) => leftFiles.has(normalizeTaskFile(filePath)))
+      if (!overlaps) {
+        return [left, right]
+      }
+    }
+  }
+
+  return null
+}
+
+function buildBuildOrchestrationHint(plan) {
+  if (plan.taskSummary.underSpecifiedOpenCount > 0) {
+    return '编排提示：当前开放任务里仍有条目缺少“涉及文件”“完成标准”或“验证方式”；并行分派或进入可信交付前，先补齐 tasks.md。'
+  }
+
+  const openTasks = plan.taskSummary.items.filter((item) => item.status === 'open')
+  if (openTasks.length < 2) return ''
+
+  const pair = findDisjointOpenTaskPair(plan)
+  if (pair) {
+    const describeTask = (task) => `${task.text}（${task.files.slice(0, 2).join(', ')}${task.validation ? `；验证：${task.validation}` : ''}）`
+    return `编排提示：检测到可并行的开放任务；如需提速，可先读取 hello-subagent 再按 tasks.md 分派。任务A：${describeTask(pair[0])}；任务B：${describeTask(pair[1])}。`
+  }
+  if (openTasks.every((item) => item.files.length === 0)) {
+    return '编排提示：当前有多个开放任务，但 tasks.md 尚未写清 contract 元数据；考虑子代理并行前先补足文件路径、完成标准与验证方式。'
+  }
+  return '编排提示：当前仍有多个开放任务，但文件范围存在重叠；暂不建议并行子代理，优先串行推进。'
+}
+
+export function buildOrchestrationHintFromSnapshot(snapshot, cwd, recommendation = buildRecommendation(snapshot, cwd)) {
+  const plan = getTargetPlans(snapshot)[0]
+  if (!plan || !recommendation) return ''
+
+  if (recommendation.nextCommand === 'build') {
+    return buildBuildOrchestrationHint(plan)
+  }
+  if (recommendation.nextCommand === 'verify' && plan.taskSummary.total >= 1) {
+    const action = buildDeliveryActionFromSnapshot(snapshot, cwd, recommendation)
+    if (action?.phase === 'verify') {
+      return `编排提示：当前已进入收尾；${[action.routeHint, action.gateHint].filter(Boolean).join(' ')}`
+    }
+  }
+  if (recommendation.stage === 'consolidate') {
+    const action = buildDeliveryActionFromSnapshot(snapshot, cwd, recommendation)
+    if (action?.phase === 'consolidate') {
+      return `编排提示：当前已进入 CONSOLIDATE；${[action.routeHint, action.gateHint].filter(Boolean).join(' ')}`
+    }
+  }
+  return ''
+}

package/scripts/workflow-state.mjs

@@ -0,0 +1,113 @@
+import { basename } from 'node:path'
+
+import {
+  buildStateRoleHintFromSnapshot,
+  buildStateSyncHintFromSnapshot,
+  buildUiContractHint,
+  buildVerifyModeHintFromSnapshot,
+  getWorkflowSnapshot,
+  readStateSnapshot,
+  listPlanPackages,
+} from './workflow-core.mjs'
+import {
+  buildDeliveryActionFromSnapshot,
+  buildDeliveryGateHintFromSnapshot,
+  buildOrchestrationHintFromSnapshot,
+  buildRecommendation,
+} from './workflow-recommendation.mjs'
+
+export function getDeliveryAction(cwd) {
+  const snapshot = getWorkflowSnapshot(cwd)
+  const recommendation = buildRecommendation(snapshot, cwd)
+  return buildDeliveryActionFromSnapshot(snapshot, cwd, recommendation)
+}
+
+export function getWorkflowRecommendation(cwd) {
+  return buildRecommendation(getWorkflowSnapshot(cwd), cwd)
+}
+
+export function buildStateSyncHint(cwd) {
+  return buildStateSyncHintFromSnapshot(getWorkflowSnapshot(cwd))
+}
+
+export function buildDeliveryGateHint(cwd) {
+  const snapshot = getWorkflowSnapshot(cwd)
+  return buildDeliveryGateHintFromSnapshot(snapshot, cwd, buildRecommendation(snapshot, cwd))
+}
+
+export function buildWorkflowRouteHint(cwd) {
+  const snapshot = getWorkflowSnapshot(cwd)
+  const recommendation = buildRecommendation(snapshot, cwd)
+  const stateSyncHint = buildStateSyncHintFromSnapshot(snapshot)
+  const stateRoleHint = buildStateRoleHintFromSnapshot(snapshot)
+  const orchestrationHint = buildOrchestrationHintFromSnapshot(snapshot, cwd, recommendation)
+  const uiContractHint = buildUiContractHint(cwd, snapshot)
+
+  if (!recommendation) {
+    return [stateRoleHint, stateSyncHint, uiContractHint].filter(Boolean).join(' ')
+  }
+
+  const suffix = [stateRoleHint, stateSyncHint, orchestrationHint, uiContractHint].filter(Boolean).join(' ')
+  if (recommendation.stage === 'consolidate') {
+    return `${recommendation.summary} 当前建议下一阶段：CONSOLIDATE。推荐路径：${recommendation.nextPath}。${recommendation.guidance}${suffix ? ` ${suffix}` : ''}`
+  }
+  return `${recommendation.summary} 当前建议下一命令：~${recommendation.nextCommand}。推荐路径：${recommendation.nextPath}。${recommendation.guidance}${suffix ? ` ${suffix}` : ''}`
+}
+
+function buildCommandRouteMessage(skillName, recommendation, verifyModeHint) {
+  if (skillName === 'auto') {
+    return recommendation.stage === 'consolidate'
+      ? `当前工作流约束：${recommendation.summary} 当前建议下一阶段：CONSOLIDATE。${recommendation.guidance}`
+      : `当前工作流约束：${recommendation.summary} 当前建议主路径：${recommendation.nextPath}。${recommendation.guidance}`
+  }
+  if (skillName === 'plan') {
+    if (recommendation.stage === 'consolidate') {
+      return `当前工作流约束：${recommendation.summary} 当前更推荐的下一阶段其实是 CONSOLIDATE。只有在用户明确要求重规划、改方向或新增范围时，才继续 ~plan。`
+    }
+    return recommendation.nextCommand === 'plan'
+      ? `当前工作流约束：${recommendation.summary} 当前建议下一命令：~plan。${recommendation.guidance}`
+      : `当前工作流约束：${recommendation.summary} 当前更推荐的下一命令其实是 ~${recommendation.nextCommand}。只有在用户明确要求重规划、改方向或新增范围时，才继续 ~plan。`
+  }
+  if (skillName === 'build') {
+    if (recommendation.stage === 'consolidate') {
+      return `当前工作流约束：${recommendation.summary} 当前更推荐的下一阶段其实是 CONSOLIDATE。只有在用户明确提出新增实现范围时，才继续 ~build。`
+    }
+    return recommendation.nextCommand === 'build'
+      ? `当前工作流约束：${recommendation.summary} 当前建议下一命令：~build。${recommendation.guidance}`
+      : `当前工作流约束：${recommendation.summary} 当前更推荐的下一命令其实是 ~${recommendation.nextCommand}。只有在用户明确提出新增实现范围时，才继续 ~build。`
+  }
+  if (skillName === 'verify') {
+    if (recommendation.stage === 'consolidate') {
+      return `当前工作流约束：${recommendation.summary} 当前建议下一阶段：CONSOLIDATE。${recommendation.guidance}`
+    }
+    return recommendation.nextCommand === 'verify'
+      ? `当前工作流约束：${recommendation.summary} 当前建议下一命令：~verify。${recommendation.guidance}`
+      : `当前工作流约束：${recommendation.summary} 当前更推荐的下一命令其实是 ~${recommendation.nextCommand}。即使执行 ~verify，也不能越过当前工作流边界。${verifyModeHint ? ` 若本次仅做阶段内审查或验真，${verifyModeHint}` : ''}`
+  }
+  return `当前工作流约束：${recommendation.summary} 当前建议下一命令：~${recommendation.nextCommand}。${recommendation.guidance}`
+}
+
+export function buildCommandRouteHint(skillName, cwd) {
+  const snapshot = getWorkflowSnapshot(cwd)
+  const recommendation = buildRecommendation(snapshot, cwd)
+  const contextHints = [
+    buildStateRoleHintFromSnapshot(snapshot),
+    buildStateSyncHintFromSnapshot(snapshot),
+    buildOrchestrationHintFromSnapshot(snapshot, cwd, recommendation),
+    buildUiContractHint(cwd, snapshot),
+  ].filter(Boolean)
+
+  if (!recommendation) {
+    return contextHints.join(' ')
+  }
+
+  const message = buildCommandRouteMessage(skillName, recommendation, buildVerifyModeHintFromSnapshot(snapshot))
+  return [message, ...contextHints].join(' ')
+}
+
+export { readStateSnapshot, listPlanPackages, getWorkflowSnapshot }
+
+export function describePlanForLogs(planEntry) {
+  if (!planEntry) return ''
+  return basename(planEntry.dirPath)
+}