helloagents 3.0.32 → 3.0.35

package/scripts/session-capsule.mjs

@@ -10,6 +10,7 @@ import {
   writeActiveProjectSession,
   writeJsonFileAtomic,
 } from './runtime-scope.mjs'
+import { readStateDocument, writeStateDocument } from './state-document.mjs'
 
 export { getRuntimeScope }
 
@@ -68,7 +69,7 @@ function getScope(cwd, options = {}) {
 }
 
 export function getSessionCapsulePath(cwd = process.cwd(), options = {}) {
-  return getScope(cwd, options).capsulePath
+  return getScope(cwd, options).statePath
 }
 
 export function getSessionEventsPath(cwd = process.cwd(), options = {}) {
@@ -93,8 +94,9 @@ export function getSessionArtifactRelativePath(cwd, fileName, options = {}) {
 
 export function readSessionCapsule(cwd = process.cwd(), options = {}) {
   const scope = getScope(cwd, options)
-  const capsule = readJsonFile(scope.capsulePath, null)
-  if (!capsule || typeof capsule !== 'object') return buildEmptyCapsule(scope)
+  const { metadata } = readStateDocument(scope.statePath)
+  const capsule = metadata && typeof metadata === 'object' ? metadata : null
+  if (!capsule || Array.isArray(capsule)) return buildEmptyCapsule(scope)
   return {
     ...buildEmptyCapsule(scope),
     ...capsule,
@@ -109,7 +111,24 @@ export function readSessionCapsule(cwd = process.cwd(), options = {}) {
 }
 
 export function writeSessionCapsule(cwd, capsule, options = {}) {
-  const scope = getScope(cwd, options)
+  const normalizedOptions = normalizeOptions(options)
+  const scope = getScope(cwd, normalizedOptions)
+  const currentDocument = readStateDocument(scope.statePath)
+  const hasBody = Boolean(currentDocument.body && currentDocument.body.trim())
+  if (!hasBody && normalizedOptions.ensureProjectLocal !== true && !existsSync(scope.statePath)) {
+    return {
+      ...buildEmptyCapsule(scope),
+      ...capsule,
+      scope: scope.scope,
+      key: scope.key,
+      cwd: scope.cwd,
+      branch: scope.branch,
+      workspace: scope.workspace || scope.branch,
+      session: scope.session,
+      sessionMode: scope.sessionMode,
+      updatedAt: new Date().toISOString(),
+    }
+  }
   const nextCapsule = {
     ...buildEmptyCapsule(scope),
     ...capsule,
@@ -122,9 +141,12 @@ export function writeSessionCapsule(cwd, capsule, options = {}) {
     sessionMode: scope.sessionMode,
     updatedAt: new Date().toISOString(),
   }
-  writeJsonFileAtomic(scope.capsulePath, nextCapsule)
+  writeStateDocument(scope.statePath, {
+    metadata: nextCapsule,
+    body: currentDocument.body,
+  })
   writeActiveProjectSession(scope, {
-    env: normalizeOptions(options).env,
+    env: normalizedOptions.env,
   })
   return nextCapsule
 }
@@ -151,8 +173,8 @@ export function writeCapsuleSection(cwd, section, value, options = {}) {
 }
 
 export function clearCapsuleSection(cwd, section, options = {}) {
-  const capsulePath = getSessionCapsulePath(cwd, options)
-  if (!existsSync(capsulePath)) return false
+  const statePath = getSessionCapsulePath(cwd, options)
+  if (!existsSync(statePath)) return false
 
   const capsule = readSessionCapsule(cwd, options)
   if (!Object.prototype.hasOwnProperty.call(capsule, section)) return false
@@ -180,6 +202,13 @@ export function appendSessionEvent(cwd, eventPayload, options = {}) {
   const eventName = eventPayload?.event || ''
   if (!eventName) return ''
 
+  writeActiveProjectSession(scope, {
+    host: eventPayload.host || '',
+    source: eventPayload.source || eventName,
+    env: scopedOptions.env,
+  })
+  if (!shouldRecordSessionEvents(scopedOptions)) return ''
+
   mkdirSync(dirname(scope.eventsPath), { recursive: true })
   const payload = {
     ts: new Date().toISOString(),
@@ -192,17 +221,13 @@ export function appendSessionEvent(cwd, eventPayload, options = {}) {
     encoding: 'utf-8',
     flag: 'a',
   })
-  writeActiveProjectSession(scope, {
-    host: eventPayload.host || '',
-    source: eventPayload.source || eventName,
-    env: scopedOptions.env,
-  })
   return scope.eventsPath
 }
 
 export function resetSessionEvents(cwd, options = {}) {
   const scope = getScope(cwd, options)
   if (scope.scope === 'project-session' && !scope.active) return ''
+  if (!shouldRecordSessionEvents(options)) return ''
   mkdirSync(dirname(scope.eventsPath), { recursive: true })
   writeFileSync(scope.eventsPath, '', 'utf-8')
   return scope.eventsPath
@@ -242,3 +267,16 @@ export function clearSessionArtifact(cwd, fileName, options = {}) {
 export function removeSessionCapsule(cwd, options = {}) {
   removeRuntimeFile(getSessionCapsulePath(cwd, options))
 }
+
+function shouldRecordSessionEvents(options = {}) {
+  const normalizedOptions = normalizeOptions(options)
+  const payload = normalizedOptions.payload || {}
+  if (normalizedOptions.traceEvents === true || payload.traceEvents === true || payload._helloagentsTraceEvents === true) {
+    return true
+  }
+
+  const raw = String(normalizedOptions.env?.HELLOAGENTS_TRACE_EVENTS || process.env.HELLOAGENTS_TRACE_EVENTS || '')
+    .trim()
+    .toLowerCase()
+  return raw === '1' || raw === 'true' || raw === 'yes'
+}

package/scripts/state-document.mjs

@@ -0,0 +1,77 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname } from 'node:path'
+
+const STATE_META_BEGIN = '<!-- HELLOAGENTS_STATE_META'
+const STATE_META_END = 'HELLOAGENTS_STATE_META -->'
+
+function normalizeText(content = '') {
+  return String(content || '').replace(/^\uFEFF/, '')
+}
+
+function splitLines(content = '') {
+  return normalizeText(content).replace(/\r\n/g, '\n').split('\n')
+}
+
+export function parseStateDocument(content = '') {
+  const lines = splitLines(content)
+  if (lines[0]?.trim() !== STATE_META_BEGIN) {
+    return {
+      hasMetadata: false,
+      metadata: null,
+      body: normalizeText(content),
+    }
+  }
+
+  const endIndex = lines.findIndex((line, index) => index > 0 && line.trim() === STATE_META_END)
+  if (endIndex < 0) {
+    return {
+      hasMetadata: false,
+      metadata: null,
+      body: normalizeText(content),
+    }
+  }
+
+  const metadataText = lines.slice(1, endIndex).join('\n').trim()
+  const body = lines.slice(endIndex + 1).join('\n').replace(/^\n+/, '')
+  try {
+    return {
+      hasMetadata: true,
+      metadata: JSON.parse(metadataText),
+      body,
+    }
+  } catch {
+    return {
+      hasMetadata: false,
+      metadata: null,
+      body,
+    }
+  }
+}
+
+export function readStateDocument(filePath) {
+  if (!filePath || !existsSync(filePath)) {
+    return {
+      hasMetadata: false,
+      metadata: null,
+      body: '',
+    }
+  }
+
+  return parseStateDocument(readFileSync(filePath, 'utf-8'))
+}
+
+export function composeStateDocument({ metadata = {}, body = '' } = {}) {
+  const normalizedBody = normalizeText(body).replace(/^\n+/, '')
+  return [
+    STATE_META_BEGIN,
+    JSON.stringify(metadata, null, 2),
+    STATE_META_END,
+    '',
+    normalizedBody,
+  ].join('\n').replace(/\n+$/, '\n')
+}
+
+export function writeStateDocument(filePath, { metadata = {}, body = '' } = {}) {
+  mkdirSync(dirname(filePath), { recursive: true })
+  writeFileSync(filePath, composeStateDocument({ metadata, body }), 'utf-8')
+}

package/scripts/workflow-core.mjs

@@ -20,6 +20,7 @@ function describeStateLabel(state) {
   }
   return '当前会话的状态文件'
 }
+
 export function classifyPlan(plan) {
   if (!plan) {
     return {
@@ -64,24 +65,14 @@ export function classifyPlan(plan) {
   }
 }
 
-export function determineVerifyMode(plan) {
+export function determineQaMode(plan) {
   if (!plan) return null
 
   if (plan.contractIssues.length > 0) {
     return {
       mode: 'metadata-first',
-      reason: '方案包缺少可信的结构化契约',
-      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: '方案契约已明确要求审查优先',
-      guidance: `验证分流：当前更适合审查优先；先执行 reviewer / hello-review 范围审查，再交给 tester / hello-verify 跑完整验证。${reviewerFocus ? ` reviewer 重点：${reviewerFocus}。` : ''}${testerFocus ? ` tester 重点：${testerFocus}。` : ''}`.trim(),
+      reason: '方案包缺少可信的结构化 QA 契约',
+      guidance: '质量闭环：当前还不适合直接进入 ~qa；先回到 ~plan / ~prd 补齐 `contract.json`，明确 `qaMode` 与 `qaFocus`。',
     }
   }
 
@@ -89,14 +80,16 @@ export function determineVerifyMode(plan) {
     return {
       mode: 'metadata-first',
       reason: 'tasks.md 仍缺少可信的任务元数据',
-      guidance: '验证分流：当前还不适合直接进入 reviewer / tester；先补齐 tasks.md 中每个任务的“涉及文件”“完成标准”和“验证方式”。',
+      guidance: '质量闭环：当前还不适合直接进入 ~qa；先补齐 tasks.md 中每个任务的“涉及文件”“完成标准”和“验证方式”。',
     }
   }
 
+  const qaMode = plan.contract?.qaMode === 'deep' ? 'deep' : 'standard'
+  const qaFocus = (plan.contract?.qaFocus || []).join('；')
   return {
-    mode: 'test-first',
-    reason: '方案契约已明确验证主路径，且任务契约已完整',
-    guidance: `验证分流：当前更适合测试优先；先执行 tester / hello-verify 跑完整验证，再针对失败点或关键边界补充 hello-review。${plan.contract?.testerFocus?.length ? ` tester 重点：${plan.contract.testerFocus.join('；')}。` : ''}`.trim(),
+    mode: qaMode,
+    reason: qaMode === 'deep' ? '方案契约已明确要求深度 qa-review' : '方案契约已明确要求统一 qa-review',
+    guidance: `质量闭环：当前统一使用 qa-review；先完成阻断性质量审查，再运行验证命令、修复失败项并留下最新 qa-review 证据。${qaFocus ? ` QA 重点：${qaFocus}。` : ''}`.trim(),
   }
 }
 
@@ -131,12 +124,13 @@ function collectStateSyncIssues(snapshot) {
   return issues
 }
 
-export function buildVerifyModeHintFromSnapshot(snapshot) {
+export function buildQaFocusHintFromSnapshot(snapshot) {
   const plan = getTargetPlans(snapshot)[0]
   if (!plan) return ''
   if (!plan.planSections['风险与验证'] && plan.taskSummary.total === 0) return ''
-  return determineVerifyMode(plan)?.guidance || ''
+  return determineQaMode(plan)?.guidance || ''
 }
+
 export function buildStateSyncHintFromSnapshot(snapshot) {
   const issues = collectStateSyncIssues(snapshot)
   if (issues.length === 0) return ''

package/scripts/workflow-plan-files.mjs

@@ -18,7 +18,7 @@ const PLAN_TEMPLATE_MARKERS = {
     /# \{项目\/功能名称\} — 实施规划/,
     /\[本次要解决的问题、范围边界、验收目标\]/,
     /\[关键决策及理由\]/,
-    /\[功能完成时必须为真的条件、关键验收点、reviewer \/ tester 关注边界\]/,
+    /\[功能完成时必须为真的条件、关键验收点、qaMode 与 qaFocus\]/,
   ],
   'tasks.md': [
     /# \{项目\/功能名称\} — 任务分解/,

package/scripts/workflow-recommendation.mjs

@@ -1,23 +1,21 @@
 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 { getQaReviewEvidenceStatus } from './qa-review-state.mjs'
 import { getVisualEvidenceStatus } from './visual-state.mjs'
-import { getVerifyEvidenceStatus } from './verify-state.mjs'
 import {
   classifyPlan,
-  determineVerifyMode,
+  determineQaMode,
   getTargetPlans,
   normalizeTaskFile,
 } from './workflow-core.mjs'
 
 function getClosedPlanEvidenceStatus(cwd, plan, options = {}) {
-  const verifyMode = determineVerifyMode(plan)
+  const qaMode = determineQaMode(plan)
   const advisorRequirement = getAdvisorRequirement(plan.contract)
   const visualRequirement = getVisualValidationRequirement(plan.contract)
-  const verificationStatus = getVerifyEvidenceStatus(cwd, options)
-  const reviewStatus = getReviewEvidenceStatus(cwd, {
-    required: verifyMode?.mode === 'review-first',
+  const qaStatus = getQaReviewEvidenceStatus(cwd, {
+    required: qaMode?.mode !== 'metadata-first',
     ...options,
   })
   const advisorStatus = getAdvisorEvidenceStatus(cwd, {
@@ -31,26 +29,23 @@ function getClosedPlanEvidenceStatus(cwd, plan, options = {}) {
     states: visualRequirement.states,
     ...options,
   })
-  const verifyReady = !verificationStatus.required || verificationStatus.status === 'valid'
-  const reviewReady = !reviewStatus.required || reviewStatus.status === 'valid'
+  const qaReady = !qaStatus.required || qaStatus.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,
+    required: qaReady && advisorReady && visualReady,
     ...options,
   })
 
   return {
-    verifyMode,
+    qaMode,
     advisorRequirement,
     visualRequirement,
-    verificationStatus,
-    reviewStatus,
+    qaStatus,
     advisorStatus,
     visualStatus,
     closeoutStatus,
-    verifyReady,
-    reviewReady,
+    qaReady,
     advisorReady,
     visualReady,
     closeoutReady: !closeoutStatus.required || closeoutStatus.status === 'valid',
@@ -63,7 +58,7 @@ function buildConsolidateAction(recommendation) {
       phase: 'consolidate',
       mode: recommendation.mode,
       routeHint: recommendation.guidance,
-      gateHint: '交付把关：审查与验证证据已满足；先写当前会话 `artifacts/closeout.json` 记录需求覆盖与交付清单，再更新 `state_path` 并归档后才可交付。',
+      gateHint: '交付把关：qa-review 与附加证据已满足；先写当前会话 `artifacts/closeout.json` 记录需求覆盖与交付清单，再更新 `state_path` 并归档后才可交付。',
     }
   }
 
@@ -75,8 +70,8 @@ function buildConsolidateAction(recommendation) {
   }
 }
 
-function buildVerifyAction(plan, verifyMode) {
-  if (!verifyMode) return null
+function buildQaAction(plan, qaMode) {
+  if (!qaMode) return null
   const advisorRequirement = getAdvisorRequirement(plan.contract)
   const visualRequirement = getVisualValidationRequirement(plan.contract)
   const extraChecks = []
@@ -87,30 +82,23 @@ function buildVerifyAction(plan, verifyMode) {
     extraChecks.push('完成视觉验收并写入当前会话 `artifacts/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') {
+
+  if (qaMode.mode === 'metadata-first') {
     return {
-      phase: 'verify',
-      mode: verifyMode.mode,
-      routeHint: verifyMode.guidance,
+      phase: 'plan',
+      mode: qaMode.mode,
+      routeHint: qaMode.guidance,
       gateHint: plan.contractIssues.length > 0
-        ? '交付把关：当前还不能进入 CONSOLIDATE；先补齐 `contract.json` 中的 `verifyMode`、`reviewerFocus`、`testerFocus`，再进入 reviewer / tester。'
-        : '交付把关：当前还不能进入 CONSOLIDATE；先补齐 tasks.md 中每个任务的“涉及文件”“完成标准”和“验证方式”，再进入 reviewer / tester。',
+        ? '交付把关：当前还不能进入 CONSOLIDATE；先补齐 `contract.json` 中的 `qaMode` 与 `qaFocus`，再进入 ~qa。'
+        : '交付把关：当前还不能进入 CONSOLIDATE；先补齐 tasks.md 中每个任务的“涉及文件”“完成标准”和“验证方式”，再进入 ~qa。',
     }
   }
 
   return {
-    phase: 'verify',
-    mode: verifyMode.mode,
-    routeHint: verifyMode.guidance,
-    gateHint: `交付把关：进入 CONSOLIDATE 前，先完成 tester / hello-verify 全量验证并留下最新验证证据，再针对失败点或关键边界补充 hello-review；确认通过后才可交付。${gateSuffix}`.trim(),
+    phase: 'qa',
+    mode: qaMode.mode,
+    routeHint: qaMode.guidance,
+    gateHint: `交付把关：进入 CONSOLIDATE 前，必须完成 qa-review 全量质量闭环，并留下最新 qa-review 证据。${gateSuffix}`.trim(),
   }
 }
 
@@ -122,19 +110,19 @@ export function buildDeliveryActionFromSnapshot(snapshot, cwd, recommendation =
   }
 
   const plan = getTargetPlans(snapshot)[0]
-  if (recommendation.nextCommand === 'verify' && plan) {
-    return buildVerifyAction(plan, determineVerifyMode(plan))
+  if (recommendation.nextCommand === 'qa' && plan) {
+    return buildQaAction(plan, determineQaMode(plan))
   }
   if (recommendation.nextCommand === 'build') {
     return {
       phase: 'build',
-      gateHint: '交付把关：当前还不能报告完成；先回到 ~build 完成剩余任务，再进入 ~verify。',
+      gateHint: '交付把关：当前还不能报告完成；先回到 ~build 完成剩余任务，再进入 ~qa。',
     }
   }
   if (recommendation.nextCommand === 'plan') {
     return {
       phase: 'plan',
-      gateHint: '交付把关：当前还不能报告完成；先回到 ~plan 修复或补齐当前方案包，再进入 ~build / ~verify。',
+      gateHint: '交付把关：当前还不能报告完成；先回到 ~plan 修复或补齐当前方案包，再进入 ~build / ~qa。',
     }
   }
 
@@ -152,13 +140,13 @@ function buildPlanRecommendation(scopeLabel, plan, classification) {
     status: classification.status,
     details: classification.details,
     nextCommand: 'plan',
-    nextPath: '~plan -> ~build / ~verify',
+    nextPath: '~plan -> ~build / ~qa',
     summary: classification.status === 'incomplete'
       ? `${scopeLabel} "${plan.planName}" 仍不完整（${classification.details.join('；')}）。`
       : `${scopeLabel} "${plan.planName}" 尚未形成可执行任务清单。`,
     guidance: classification.status === 'incomplete'
-      ? '优先先走 ~plan 修复或补全当前方案包，再进入实现或验证；不要把不完整的结构化产物直接当成可交付依据。'
-      : '先回到 ~plan 补齐 tasks.md 的原子任务，再进入实现、验证或收尾。',
+      ? '优先先走 ~plan 修复或补全当前方案包，再进入实现或 qa-review；不要把不完整的结构化产物直接当成可交付依据。'
+      : '先回到 ~plan 补齐 tasks.md 的原子任务，再进入实现、qa-review 或收尾。',
   }
 }
 
@@ -169,23 +157,23 @@ function buildInProgressRecommendation(scopeLabel, plan, classification) {
     status: classification.status,
     details: classification.details,
     nextCommand: 'build',
-    nextPath: '~build -> ~verify',
+    nextPath: '~build -> ~qa',
     summary: `${scopeLabel} "${plan.planName}" 仍有 ${classification.openCount} 个未完成任务。`,
-    guidance: '若用户是在继续当前功能、落实既有方案、或让你“继续做完”，优先复用现有 requirements.md / plan.md / tasks.md 进入 ~build；完成当前实现后再进入 ~verify。除非用户明确要求重规划或现有方案已失效，不要重新回到 ~idea。',
+    guidance: '若用户是在继续当前功能、落实既有方案、或让你“继续做完”，优先复用现有 requirements.md / plan.md / tasks.md 进入 ~build；完成当前实现后再进入 ~qa。除非用户明确要求重规划或现有方案已失效，不要重新回到 ~idea。',
   }
 }
 
 function buildClosedRecommendation(scopeLabel, plan, cwd, options = {}) {
   const closedPlanEvidence = getClosedPlanEvidenceStatus(cwd, plan, options)
-  if (closedPlanEvidence.verifyMode?.mode === 'metadata-first') {
+  if (closedPlanEvidence.qaMode?.mode === 'metadata-first') {
     return {
       scopeLabel,
       plan,
       status: 'closed',
-      nextCommand: 'verify',
-      nextPath: '~verify -> CONSOLIDATE',
-      summary: `${scopeLabel} "${plan.planName}" 的任务已全部闭合，但验证契约仍未结构化。`,
-      guidance: closedPlanEvidence.verifyMode.guidance,
+      nextCommand: 'plan',
+      nextPath: '~plan -> ~qa',
+      summary: `${scopeLabel} "${plan.planName}" 的任务已全部闭合，但 QA 契约仍未结构化。`,
+      guidance: closedPlanEvidence.qaMode.guidance,
     }
   }
 
@@ -199,10 +187,10 @@ function buildClosedRecommendation(scopeLabel, plan, cwd, options = {}) {
       scopeLabel,
       plan,
       status: 'closed',
-      nextCommand: 'verify',
-      nextPath: '~verify -> CONSOLIDATE',
+      nextCommand: 'qa',
+      nextPath: '~qa -> CONSOLIDATE',
       summary: `${scopeLabel} "${plan.planName}" 的任务已闭合，但当前 UI 契约仍要求独立 advisor 复查与视觉验收。`,
-      guidance: '先在 ~verify 阶段完成独立 advisor / style advisor 复查，并写入当前会话 `artifacts/advisor.json`；再完成视觉验收并写入当前会话 `artifacts/visual.json`，记录 reason、tooling、screensChecked、statesChecked、status 与 summary；两项都通过后再进入 CONSOLIDATE。',
+      guidance: '先在 ~qa 阶段完成独立 advisor / style advisor 复查，并写入当前会话 `artifacts/advisor.json`；再完成视觉验收并写入当前会话 `artifacts/visual.json`，记录 reason、tooling、screensChecked、statesChecked、status 与 summary；两项都通过后再进入 CONSOLIDATE。',
     }
   }
 
@@ -211,10 +199,10 @@ function buildClosedRecommendation(scopeLabel, plan, cwd, options = {}) {
       scopeLabel,
       plan,
       status: 'closed',
-      nextCommand: 'verify',
-      nextPath: '~verify -> CONSOLIDATE',
+      nextCommand: 'qa',
+      nextPath: '~qa -> CONSOLIDATE',
       summary: `${scopeLabel} "${plan.planName}" 的任务已闭合，但当前契约仍要求独立 advisor 复查。`,
-      guidance: '先在 ~verify 阶段完成独立 advisor / style advisor 复查，并写入当前会话 `artifacts/advisor.json` 记录复查原因、focus、来源与结论；advisor 通过后再进入 CONSOLIDATE。',
+      guidance: '先在 ~qa 阶段完成独立 advisor / style advisor 复查，并写入当前会话 `artifacts/advisor.json` 记录复查原因、focus、来源与结论；advisor 通过后再进入 CONSOLIDATE。',
     }
   }
 
@@ -223,25 +211,25 @@ function buildClosedRecommendation(scopeLabel, plan, cwd, options = {}) {
       scopeLabel,
       plan,
       status: 'closed',
-      nextCommand: 'verify',
-      nextPath: '~verify -> CONSOLIDATE',
+      nextCommand: 'qa',
+      nextPath: '~qa -> CONSOLIDATE',
       summary: `${scopeLabel} "${plan.planName}" 的任务已闭合，但当前 UI 契约仍要求视觉验收。`,
-      guidance: '先在 ~verify 阶段完成视觉验收，并写入当前会话 `artifacts/visual.json` 记录 reason、tooling、screensChecked、statesChecked、status 与 summary；视觉验收通过后再进入 CONSOLIDATE。',
+      guidance: '先在 ~qa 阶段完成视觉验收，并写入当前会话 `artifacts/visual.json` 记录 reason、tooling、screensChecked、statesChecked、status 与 summary；视觉验收通过后再进入 CONSOLIDATE。',
     }
   }
 
-  if (closedPlanEvidence.verifyReady && closedPlanEvidence.reviewReady && closedPlanEvidence.advisorReady && closedPlanEvidence.visualReady) {
+  if (closedPlanEvidence.qaReady && closedPlanEvidence.advisorReady && closedPlanEvidence.visualReady) {
     return {
       scopeLabel,
       plan,
       status: 'closed',
       stage: 'consolidate',
       mode: closedPlanEvidence.closeoutReady ? 'ready' : 'closeout-pending',
-      nextCommand: 'verify',
+      nextCommand: 'qa',
       nextPath: 'CONSOLIDATE',
       summary: closedPlanEvidence.closeoutReady
         ? `${scopeLabel} "${plan.planName}" 的任务与交付证据已闭合。`
-        : `${scopeLabel} "${plan.planName}" 的任务、审查与验证已闭合。`,
+        : `${scopeLabel} "${plan.planName}" 的任务与 qa-review 已闭合。`,
       guidance: closedPlanEvidence.closeoutReady
         ? '当前进入 CONSOLIDATE：更新 `state_path`、知识文件并归档方案后即可交付；不要无故重开新的方案包或重新跑一遍无关验证。'
         : '当前进入 CONSOLIDATE：先写当前会话 `artifacts/closeout.json` 记录需求覆盖与交付清单，再更新 `state_path` 并归档后交付。',
@@ -252,10 +240,10 @@ function buildClosedRecommendation(scopeLabel, plan, cwd, options = {}) {
     scopeLabel,
     plan,
     status: 'closed',
-    nextCommand: 'verify',
-    nextPath: '~verify -> CONSOLIDATE',
+    nextCommand: 'qa',
+    nextPath: '~qa -> CONSOLIDATE',
     summary: `${scopeLabel} "${plan.planName}" 的任务已全部闭合。`,
-    guidance: '若用户是在做收尾、验真、复查或准备交付，优先走 ~verify 或 CONSOLIDATE；不要无故重开新的方案包。',
+    guidance: '若用户是在做收尾、验真、复查或准备交付，优先走 ~qa 或 CONSOLIDATE；不要无故重开新的方案包。',
   }
 }
 
@@ -323,9 +311,9 @@ export function buildOrchestrationHintFromSnapshot(snapshot, cwd, recommendation
   if (recommendation.nextCommand === 'build') {
     return buildBuildOrchestrationHint(plan)
   }
-  if (recommendation.nextCommand === 'verify' && plan.taskSummary.total >= 1) {
+  if (recommendation.nextCommand === 'qa' && plan.taskSummary.total >= 1) {
     const action = buildDeliveryActionFromSnapshot(snapshot, cwd, recommendation)
-    if (action?.phase === 'verify') {
+    if (action?.phase === 'qa') {
       return `编排提示：当前已进入收尾；${[action.routeHint, action.gateHint].filter(Boolean).join(' ')}`
     }
   }

package/scripts/workflow-state.mjs

@@ -1,10 +1,10 @@
 import { basename } from 'node:path'
 
 import {
+  buildQaFocusHintFromSnapshot,
   buildStateRoleHintFromSnapshot,
   buildStateSyncHintFromSnapshot,
   buildUiContractHint,
-  buildVerifyModeHintFromSnapshot,
   getWorkflowSnapshot,
   readStateSnapshot,
   listPlanPackages,
@@ -54,14 +54,14 @@ export function buildWorkflowRouteHint(cwd, options = {}) {
   return `${recommendation.summary} 当前应执行 ~${recommendation.nextCommand}。执行路径：${recommendation.nextPath}。${recommendation.guidance}${suffix ? ` ${suffix}` : ''}`
 }
 
-function buildCommandRouteMessage(skillName, recommendation, verifyModeHint) {
+function buildCommandRouteMessage(skillName, recommendation, qaFocusHint) {
   if (skillName === 'auto') {
     return recommendation.stage === 'consolidate'
       ? `当前工作流约束：${recommendation.summary} 本次 ~auto 应直接完成当前收尾。${recommendation.guidance} 未命中阻塞判定前不要停下，也不要把收尾动作写成“下一步建议”。`
       : `当前工作流约束：${recommendation.summary} 本次 ~auto 的执行主路径：${recommendation.nextPath}。${recommendation.guidance} 命中主路径后继续执行后续阶段；未触发阻塞判定前不要停下，也不要把阶段结果写成“下一步建议”。`
   }
   if (skillName === 'loop') {
-    return `当前工作流约束：用户已显式使用 ~loop，应按 ~loop 的循环规则直接执行。现有工作流只作上下文参考：${recommendation.summary} ${recommendation.guidance} 除非达到迭代上限、达成目标或命中阻塞判定，否则不要停下，也不要把单轮结果写成“下一步建议”。`
+    return `当前工作流约束：用户已显式使用 ~loop，应把它视为长任务入口，默认按“/goal -> ~auto -> ~qa”直接推进。现有工作流只作上下文参考：${recommendation.summary} ${recommendation.guidance} 若当前宿主不支持 /goal，则按 ~auto 持续推进，并在交付前强制进入 ~qa。未命中阻塞判定前不要停下，也不要把阶段结果写成“下一步建议”。`
   }
   if (skillName === 'plan') {
     if (recommendation.stage === 'consolidate') {
@@ -79,13 +79,13 @@ function buildCommandRouteMessage(skillName, recommendation, verifyModeHint) {
       ? `当前工作流约束：${recommendation.summary} 当前应执行 ~build。${recommendation.guidance}`
       : `当前工作流约束：${recommendation.summary} 当前不该继续 ~build；先按 ~${recommendation.nextCommand} 处理。只有在用户明确提出新增实现范围时，才继续 ~build。`
   }
-  if (skillName === 'verify') {
+  if (skillName === 'qa') {
     if (recommendation.stage === 'consolidate') {
       return `当前工作流约束：${recommendation.summary} 当前应直接进入 CONSOLIDATE。${recommendation.guidance}`
     }
-    return recommendation.nextCommand === 'verify'
-      ? `当前工作流约束：${recommendation.summary} 当前应执行 ~verify。${recommendation.guidance}`
-      : `当前工作流约束：${recommendation.summary} 当前不该把 ~verify 当成越级入口；先按 ~${recommendation.nextCommand} 处理。即使执行 ~verify，也不能越过当前工作流边界。${verifyModeHint ? ` 若本次仅做阶段内审查或验真，${verifyModeHint}` : ''}`
+    return recommendation.nextCommand === 'qa'
+      ? `当前工作流约束：${recommendation.summary} 当前应执行 ~qa。${recommendation.guidance}`
+      : `当前工作流约束：${recommendation.summary} 当前不该把 ~qa 当成越级入口；先按 ~${recommendation.nextCommand} 处理。即使执行 ~qa，也不能越过当前工作流边界。${qaFocusHint ? ` 若本次只是阶段内收尾，${qaFocusHint}` : ''}`
   }
   return `当前工作流约束：${recommendation.summary} 当前应执行 ~${recommendation.nextCommand}。${recommendation.guidance}`
 }
@@ -104,7 +104,7 @@ export function buildCommandRouteHint(skillName, cwd, options = {}) {
     return contextHints.join(' ')
   }
 
-  const message = buildCommandRouteMessage(skillName, recommendation, buildVerifyModeHintFromSnapshot(snapshot))
+  const message = buildCommandRouteMessage(skillName, recommendation, buildQaFocusHintFromSnapshot(snapshot))
   return [message, ...contextHints].join(' ')
 }