helloagents 3.0.7 → 3.0.9-beta.1

package/scripts/turn-state.mjs

@@ -0,0 +1,173 @@
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { dirname, join, normalize, resolve } from 'node:path'
+import { homedir } from 'node:os'
+import { fileURLToPath } from 'node:url'
+
+import { appendReplayEvent } from './replay-state.mjs'
+
+const TURN_STATE_PATH = join(homedir(), '.helloagents', 'runtime', 'turn-state.json')
+const TURN_STATE_TTL_MS = 30 * 60 * 1000
+const VALID_KINDS = new Set(['complete', 'waiting', 'blocked', 'progress'])
+const VALID_ROLES = new Set(['main', 'subagent'])
+
+function normalizePath(filePath = '') {
+  return filePath ? normalize(resolve(filePath)) : ''
+}
+
+function ensureRuntimeDir() {
+  mkdirSync(dirname(TURN_STATE_PATH), { recursive: true })
+}
+
+function readStore() {
+  try {
+    return JSON.parse(readFileSync(TURN_STATE_PATH, 'utf-8'))
+  } catch {
+    return {}
+  }
+}
+
+function writeStore(store) {
+  const keys = Object.keys(store)
+  if (keys.length === 0) {
+    rmSync(TURN_STATE_PATH, { force: true })
+    return
+  }
+
+  ensureRuntimeDir()
+  writeFileSync(TURN_STATE_PATH, `${JSON.stringify(store, null, 2)}\n`, 'utf-8')
+}
+
+function getTurnStateKey(cwd = process.cwd()) {
+  return normalizePath(cwd)
+}
+
+function normalizeTurnState(input = {}) {
+  const kind = typeof input.kind === 'string' ? input.kind.trim().toLowerCase() : ''
+  const role = typeof input.role === 'string' ? input.role.trim().toLowerCase() : 'main'
+
+  return {
+    kind: VALID_KINDS.has(kind) ? kind : '',
+    role: VALID_ROLES.has(role) ? role : 'main',
+    phase: typeof input.phase === 'string' ? input.phase.trim().toLowerCase() : '',
+    source: typeof input.source === 'string' && input.source.trim() ? input.source.trim() : 'manual',
+    requiresDeliveryGate: Boolean(input.requiresDeliveryGate),
+  }
+}
+
+function pruneInvalidEntry(store, key) {
+  delete store[key]
+  writeStore(store)
+}
+
+export function clearTurnState(cwd = process.cwd()) {
+  const key = getTurnStateKey(cwd)
+  if (!key) return false
+  const store = readStore()
+  if (!(key in store)) return false
+  delete store[key]
+  writeStore(store)
+  return true
+}
+
+export function readTurnState(cwd = process.cwd(), { now = Date.now() } = {}) {
+  const key = getTurnStateKey(cwd)
+  if (!key) return null
+
+  const store = readStore()
+  const entry = store[key]
+  if (!entry?.cwd || !entry?.kind || !entry?.updatedAt) {
+    if (entry) pruneInvalidEntry(store, key)
+    return null
+  }
+
+  const updatedAt = Date.parse(entry.updatedAt)
+  if (!Number.isFinite(updatedAt) || (now - updatedAt > TURN_STATE_TTL_MS)) {
+    pruneInvalidEntry(store, key)
+    return null
+  }
+
+  const normalized = normalizeTurnState(entry)
+  if (!normalized.kind) {
+    pruneInvalidEntry(store, key)
+    return null
+  }
+
+  return {
+    cwd: normalizePath(entry.cwd),
+    updatedAt: entry.updatedAt,
+    ...normalized,
+  }
+}
+
+export function writeTurnState(cwd = process.cwd(), input = {}) {
+  const key = getTurnStateKey(cwd)
+  const normalized = normalizeTurnState(input)
+  if (!key || !normalized.kind) {
+    throw new Error('turn-state requires cwd and a valid kind')
+  }
+
+  const store = readStore()
+  const payload = {
+    cwd: key,
+    updatedAt: new Date().toISOString(),
+    ...normalized,
+  }
+  store[key] = payload
+  writeStore(store)
+
+  appendReplayEvent(cwd, {
+    event: 'turn_state_written',
+    source: normalized.source,
+    details: {
+      kind: normalized.kind,
+      role: normalized.role,
+      phase: normalized.phase,
+      requiresDeliveryGate: normalized.requiresDeliveryGate,
+    },
+  })
+
+  return payload
+}
+
+function readStdinJson() {
+  try {
+    return JSON.parse(readFileSync(0, 'utf-8'))
+  } catch {
+    return {}
+  }
+}
+
+function main() {
+  const command = process.argv[2] || ''
+  const input = readStdinJson()
+  const cwd = input.cwd || process.cwd()
+
+  if (command === 'write') {
+    const payload = writeTurnState(cwd, input)
+    process.stdout.write(JSON.stringify({
+      suppressOutput: true,
+      path: TURN_STATE_PATH,
+      payload,
+    }))
+    return
+  }
+
+  if (command === 'clear') {
+    process.stdout.write(JSON.stringify({
+      suppressOutput: true,
+      cleared: clearTurnState(cwd),
+    }))
+    return
+  }
+
+  if (command === 'read') {
+    process.stdout.write(JSON.stringify({
+      suppressOutput: true,
+      state: readTurnState(cwd),
+    }))
+  }
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+  main()
+}

package/scripts/workflow-core.mjs

@@ -13,6 +13,13 @@ import { describeProjectStoreFile, getProjectDesignContractPath } from './projec
 export function getTargetPlans(snapshot) {
   return snapshot.activePlans.length > 0 ? snapshot.activePlans : snapshot.plans
 }
+
+function describeStateLabel(state) {
+  if (state.stateSessionMode === 'default') {
+    return '当前分支默认会话槽位的 `STATE.md`'
+  }
+  return '当前会话的 `STATE.md`'
+}
 export function classifyPlan(plan) {
   if (!plan) {
     return {
@@ -63,7 +70,7 @@ export function determineVerifyMode(plan) {
   if (plan.contractIssues.length > 0) {
     return {
       mode: 'metadata-first',
-      reason: '方案包缺少可信的结构化 contract',
+      reason: '方案包缺少可信的结构化契约',
       guidance: '验证分流：当前还不适合直接进入 reviewer / tester；先回到 ~plan / ~prd 补齐 `contract.json`，明确 `verifyMode`、`reviewerFocus` 和 `testerFocus`。',
     }
   }
@@ -73,7 +80,7 @@ export function determineVerifyMode(plan) {
     const testerFocus = plan.contract.testerFocus.join('；')
     return {
       mode: 'review-first',
-      reason: '方案 contract 已明确要求审查优先',
+      reason: '方案契约已明确要求审查优先',
       guidance: `验证分流：当前更适合审查优先；先执行 reviewer / hello-review 范围审查，再交给 tester / hello-verify 跑完整验证。${reviewerFocus ? ` reviewer 重点：${reviewerFocus}。` : ''}${testerFocus ? ` tester 重点：${testerFocus}。` : ''}`.trim(),
     }
   }
@@ -88,7 +95,7 @@ export function determineVerifyMode(plan) {
 
   return {
     mode: 'test-first',
-    reason: '方案 contract 已明确验证主路径，且任务 contract 已完整',
+    reason: '方案契约已明确验证主路径，且任务契约已完整',
     guidance: `验证分流：当前更适合测试优先；先执行 tester / hello-verify 跑完整验证，再针对失败点或关键边界补充 hello-review。${plan.contract?.testerFocus?.length ? ` tester 重点：${plan.contract.testerFocus.join('；')}。` : ''}`.trim(),
   }
 }
@@ -97,27 +104,28 @@ function collectStateSyncIssues(snapshot) {
   const issues = []
   const hasPlans = snapshot.plans.length > 0
   const state = snapshot.state
+  const stateLabel = describeStateLabel(state)
 
   if (!hasPlans) {
     return issues
   }
 
   if (!state.exists) {
-    issues.push('当前已存在方案包，但 `.helloagents/STATE.md` 缺失')
+    issues.push(`当前已存在方案包，但${stateLabel} 缺失`)
     return issues
   }
 
   if (!state.referencedPlanDir) {
-    issues.push('当前已存在方案包，但 `STATE.md` 未记录活跃方案路径')
+    issues.push(`${stateLabel} 未记录活跃方案路径`)
   }
   if (!state.sections['主线目标']) {
-    issues.push('`STATE.md` 缺少“主线目标”')
+    issues.push(`${stateLabel} 缺少“主线目标”`)
   }
   if (!state.sections['正在做什么']) {
-    issues.push('`STATE.md` 缺少“正在做什么”')
+    issues.push(`${stateLabel} 缺少“正在做什么”`)
   }
   if (!state.sections['下一步']) {
-    issues.push('`STATE.md` 缺少“下一步”')
+    issues.push(`${stateLabel} 缺少“下一步”`)
   }
 
   return issues
@@ -137,7 +145,7 @@ export function buildStateSyncHintFromSnapshot(snapshot) {
 
 export function buildStateRoleHintFromSnapshot(snapshot) {
   if (!snapshot.state.exists || snapshot.plans.length > 0) return ''
-  return '恢复约束：当前仅检测到 `.helloagents/STATE.md`；先以当前用户消息、显式命令和代码事实确认主线，STATE.md 只用于找回上次停在哪，不是当前任务的自动授权或唯一事实源。'
+  return `恢复约束：当前仅检测到${describeStateLabel(snapshot.state)}；先以当前用户消息、显式命令和代码事实确认主线，STATE.md 只用于找回上次停在哪，不是当前任务的自动授权或唯一判断依据。`
 }
 
 export function buildUiContractHint(cwd, snapshot) {
@@ -154,10 +162,10 @@ export function buildUiContractHint(cwd, snapshot) {
 
   const extraHints = []
   if (styleAdvisorRequired) {
-    extraHints.push('若当前 UI contract 要求 style advisor，收尾前需复用 `.helloagents/.ralph-advisor.json` 留下独立复查证据')
+    extraHints.push('若当前 UI 契约要求 style advisor，收尾前需复用 `.helloagents/.ralph-advisor.json` 留下独立复查证据')
   }
   if (visualValidationRequired) {
-    extraHints.push('若当前 UI contract 要求视觉验收，收尾前需写 `.helloagents/.ralph-visual.json` 记录关键视口、状态与结论')
+    extraHints.push('若当前 UI 契约要求视觉验收，收尾前需写 `.helloagents/.ralph-visual.json` 记录关键视口、状态与结论')
   }
   return `UI 约束提示：如本次属于视觉/交互链路，设计决策优先级固定为：当前活跃 plan.md / prd/03-ui-design.md → ${describeProjectStoreFile(cwd, 'DESIGN.md')} → hello-ui。${extraHints.length > 0 ? ` ${extraHints.join('；')}。` : ''}`
 }

package/scripts/workflow-plan-files.mjs

@@ -2,7 +2,11 @@ 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'
+import {
+  getProjectPlansDir,
+  getProjectSessionStateScope,
+  resolveProjectPlanDir,
+} from './project-storage.mjs'
 
 const PLAN_TEMPLATE_MARKERS = {
   'requirements.md': [
@@ -170,15 +174,22 @@ function comparePlanEntries(a, b) {
   return a.planName.localeCompare(b.planName)
 }
 
-export function readStateSnapshot(cwd) {
-  const statePath = getProjectStatePath(cwd)
+export function readStateSnapshot(cwd, options = {}) {
+  const stateScope = getProjectSessionStateScope(cwd, options)
+  const statePath = stateScope.statePath
+  const exists = existsSync(statePath)
   const content = readText(statePath)
   const sections = parseMarkdownSections(content)
   const referencedPlanDir = resolvePlanDir(cwd, sections['方案'])
 
   return {
     statePath,
-    exists: existsSync(statePath),
+    stateScope: stateScope.stateScope,
+    stateSessionToken: stateScope.stateSessionToken,
+    stateSessionMode: stateScope.stateSessionMode,
+    stateBranch: stateScope.stateBranch,
+    sessionScoped: stateScope.stateScope === 'session',
+    exists,
     content,
     sections,
     referencedPlanDir,
@@ -230,8 +241,8 @@ export function listPlanPackages(cwd) {
     .sort(comparePlanEntries)
 }
 
-export function getWorkflowSnapshot(cwd) {
-  const state = readStateSnapshot(cwd)
+export function getWorkflowSnapshot(cwd, options = {}) {
+  const state = readStateSnapshot(cwd, options)
   const plans = listPlanPackages(cwd).map((entry) => ({
     ...entry,
     referencedByState: state.referencedPlanDir ? normalize(entry.dirPath) === normalize(state.referencedPlanDir) : false,

package/scripts/workflow-recommendation.mjs

@@ -59,7 +59,7 @@ function buildConsolidateAction(recommendation) {
       phase: 'consolidate',
       mode: recommendation.mode,
       routeHint: recommendation.guidance,
-      gateHint: '交付门控：审查与验证证据已满足；先写 `.helloagents/.ralph-closeout.json` 记录需求覆盖与交付清单，再完成 STATE.md / 归档后才可交付。',
+      gateHint: '交付把关：审查与验证证据已满足；先写 `.helloagents/.ralph-closeout.json` 记录需求覆盖与交付清单，再完成 STATE.md / 归档后才可交付。',
     }
   }
 
@@ -67,7 +67,7 @@ function buildConsolidateAction(recommendation) {
     phase: 'consolidate',
     mode: recommendation.mode || 'ready',
     routeHint: recommendation.guidance,
-    gateHint: '交付门控：当前已具备 closeout evidence；完成 STATE.md、知识沉淀与归档后即可交付。',
+    gateHint: '交付把关：当前已具备收尾证据；完成 STATE.md、知识沉淀与归档后即可交付。',
   }
 }
 
@@ -88,7 +88,7 @@ function buildVerifyAction(plan, verifyMode) {
       phase: 'verify',
       mode: verifyMode.mode,
       routeHint: verifyMode.guidance,
-      gateHint: `交付门控：进入 CONSOLIDATE 前，必须先完成 reviewer / hello-review 范围审查，再完成 tester / hello-verify 全量验证，并留下最新验证证据；两步都通过后才可交付。${gateSuffix}`.trim(),
+      gateHint: `交付把关：进入 CONSOLIDATE 前，必须先完成 reviewer / hello-review 范围审查，再完成 tester / hello-verify 全量验证，并留下最新验证证据；两步都通过后才可交付。${gateSuffix}`.trim(),
     }
   }
   if (verifyMode.mode === 'metadata-first') {
@@ -97,8 +97,8 @@ function buildVerifyAction(plan, verifyMode) {
       mode: verifyMode.mode,
       routeHint: verifyMode.guidance,
       gateHint: plan.contractIssues.length > 0
-        ? '交付门控：当前还不能进入 CONSOLIDATE；先补齐 `contract.json` 中的 `verifyMode`、`reviewerFocus`、`testerFocus`，再进入 reviewer / tester。'
-        : '交付门控：当前还不能进入 CONSOLIDATE；先补齐 tasks.md 中每个任务的“涉及文件”“完成标准”和“验证方式”，再进入 reviewer / tester。',
+        ? '交付把关：当前还不能进入 CONSOLIDATE；先补齐 `contract.json` 中的 `verifyMode`、`reviewerFocus`、`testerFocus`，再进入 reviewer / tester。'
+        : '交付把关：当前还不能进入 CONSOLIDATE；先补齐 tasks.md 中每个任务的“涉及文件”“完成标准”和“验证方式”，再进入 reviewer / tester。',
     }
   }
 
@@ -106,7 +106,7 @@ function buildVerifyAction(plan, verifyMode) {
     phase: 'verify',
     mode: verifyMode.mode,
     routeHint: verifyMode.guidance,
-    gateHint: `交付门控：进入 CONSOLIDATE 前，先完成 tester / hello-verify 全量验证并留下最新验证证据，再针对失败点或关键边界补充 hello-review；确认通过后才可交付。${gateSuffix}`.trim(),
+    gateHint: `交付把关：进入 CONSOLIDATE 前，先完成 tester / hello-verify 全量验证并留下最新验证证据，再针对失败点或关键边界补充 hello-review；确认通过后才可交付。${gateSuffix}`.trim(),
   }
 }
 
@@ -124,13 +124,13 @@ export function buildDeliveryActionFromSnapshot(snapshot, cwd, recommendation =
   if (recommendation.nextCommand === 'build') {
     return {
       phase: 'build',
-      gateHint: '交付门控：当前还不能报告完成；先回到 ~build 完成剩余任务，再进入 ~verify。',
+      gateHint: '交付把关：当前还不能报告完成；先回到 ~build 完成剩余任务，再进入 ~verify。',
     }
   }
   if (recommendation.nextCommand === 'plan') {
     return {
       phase: 'plan',
-      gateHint: '交付门控：当前还不能报告完成；先回到 ~plan 修复或补齐当前方案包，再进入 ~build / ~verify。',
+      gateHint: '交付把关：当前还不能报告完成；先回到 ~plan 修复或补齐当前方案包，再进入 ~build / ~verify。',
     }
   }
 
@@ -153,7 +153,7 @@ function buildPlanRecommendation(scopeLabel, plan, classification) {
       ? `${scopeLabel} "${plan.planName}" 仍不完整（${classification.details.join('；')}）。`
       : `${scopeLabel} "${plan.planName}" 尚未形成可执行任务清单。`,
     guidance: classification.status === 'incomplete'
-      ? '优先先走 ~plan 修复或补全当前方案包，再进入实现或验证；不要把不完整 artifact 直接当成可交付依据。'
+      ? '优先先走 ~plan 修复或补全当前方案包，再进入实现或验证；不要把不完整的结构化产物直接当成可交付依据。'
       : '先回到 ~plan 补齐 tasks.md 的原子任务，再进入实现、验证或收尾。',
   }
 }
@@ -180,7 +180,7 @@ function buildClosedRecommendation(scopeLabel, plan, cwd) {
       status: 'closed',
       nextCommand: 'verify',
       nextPath: '~verify -> CONSOLIDATE',
-      summary: `${scopeLabel} "${plan.planName}" 的任务已全部闭合，但验证 contract 仍未结构化。`,
+      summary: `${scopeLabel} "${plan.planName}" 的任务已全部闭合，但验证契约仍未结构化。`,
       guidance: closedPlanEvidence.verifyMode.guidance,
     }
   }
@@ -197,7 +197,7 @@ function buildClosedRecommendation(scopeLabel, plan, cwd) {
       status: 'closed',
       nextCommand: 'verify',
       nextPath: '~verify -> CONSOLIDATE',
-      summary: `${scopeLabel} "${plan.planName}" 的任务已闭合，但当前 UI contract 仍要求独立 advisor 复查与视觉验收。`,
+      summary: `${scopeLabel} "${plan.planName}" 的任务已闭合，但当前 UI 契约仍要求独立 advisor 复查与视觉验收。`,
       guidance: '先在 ~verify 阶段完成独立 advisor / style advisor 复查，并写入 `.helloagents/.ralph-advisor.json`；再完成视觉验收并写入 `.helloagents/.ralph-visual.json`，记录 reason、tooling、screensChecked、statesChecked、status 与 summary；两项都通过后再进入 CONSOLIDATE。',
     }
   }
@@ -209,7 +209,7 @@ function buildClosedRecommendation(scopeLabel, plan, cwd) {
       status: 'closed',
       nextCommand: 'verify',
       nextPath: '~verify -> CONSOLIDATE',
-      summary: `${scopeLabel} "${plan.planName}" 的任务已闭合，但当前 contract 仍要求独立 advisor 复查。`,
+      summary: `${scopeLabel} "${plan.planName}" 的任务已闭合，但当前契约仍要求独立 advisor 复查。`,
       guidance: '先在 ~verify 阶段完成独立 advisor / style advisor 复查，并写入 `.helloagents/.ralph-advisor.json` 记录复查原因、focus、来源与结论；advisor 通过后再进入 CONSOLIDATE。',
     }
   }
@@ -221,7 +221,7 @@ function buildClosedRecommendation(scopeLabel, plan, cwd) {
       status: 'closed',
       nextCommand: 'verify',
       nextPath: '~verify -> CONSOLIDATE',
-      summary: `${scopeLabel} "${plan.planName}" 的任务已闭合，但当前 UI contract 仍要求视觉验收。`,
+      summary: `${scopeLabel} "${plan.planName}" 的任务已闭合，但当前 UI 契约仍要求视觉验收。`,
       guidance: '先在 ~verify 阶段完成视觉验收，并写入 `.helloagents/.ralph-visual.json` 记录 reason、tooling、screensChecked、statesChecked、status 与 summary；视觉验收通过后再进入 CONSOLIDATE。',
     }
   }
@@ -307,7 +307,7 @@ function buildBuildOrchestrationHint(plan) {
     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 '编排提示：当前有多个开放任务，但 tasks.md 尚未写清契约元数据；考虑子代理并行前先补足文件路径、完成标准与验证方式。'
   }
   return '编排提示：当前仍有多个开放任务，但文件范围存在重叠；暂不建议并行子代理，优先串行推进。'
 }

package/scripts/workflow-state.mjs

@@ -16,27 +16,27 @@ import {
   buildRecommendation,
 } from './workflow-recommendation.mjs'
 
-export function getDeliveryAction(cwd) {
-  const snapshot = getWorkflowSnapshot(cwd)
+export function getDeliveryAction(cwd, options = {}) {
+  const snapshot = getWorkflowSnapshot(cwd, options)
   const recommendation = buildRecommendation(snapshot, cwd)
   return buildDeliveryActionFromSnapshot(snapshot, cwd, recommendation)
 }
 
-export function getWorkflowRecommendation(cwd) {
-  return buildRecommendation(getWorkflowSnapshot(cwd), cwd)
+export function getWorkflowRecommendation(cwd, options = {}) {
+  return buildRecommendation(getWorkflowSnapshot(cwd, options), cwd)
 }
 
-export function buildStateSyncHint(cwd) {
-  return buildStateSyncHintFromSnapshot(getWorkflowSnapshot(cwd))
+export function buildStateSyncHint(cwd, options = {}) {
+  return buildStateSyncHintFromSnapshot(getWorkflowSnapshot(cwd, options))
 }
 
-export function buildDeliveryGateHint(cwd) {
-  const snapshot = getWorkflowSnapshot(cwd)
+export function buildDeliveryGateHint(cwd, options = {}) {
+  const snapshot = getWorkflowSnapshot(cwd, options)
   return buildDeliveryGateHintFromSnapshot(snapshot, cwd, buildRecommendation(snapshot, cwd))
 }
 
-export function buildWorkflowRouteHint(cwd) {
-  const snapshot = getWorkflowSnapshot(cwd)
+export function buildWorkflowRouteHint(cwd, options = {}) {
+  const snapshot = getWorkflowSnapshot(cwd, options)
   const recommendation = buildRecommendation(snapshot, cwd)
   const stateSyncHint = buildStateSyncHintFromSnapshot(snapshot)
   const stateRoleHint = buildStateRoleHintFromSnapshot(snapshot)
@@ -57,8 +57,8 @@ export function buildWorkflowRouteHint(cwd) {
 function buildCommandRouteMessage(skillName, recommendation, verifyModeHint) {
   if (skillName === 'auto') {
     return recommendation.stage === 'consolidate'
-      ? `当前工作流约束：${recommendation.summary} 当前建议下一阶段：CONSOLIDATE。${recommendation.guidance}`
-      : `当前工作流约束：${recommendation.summary} 当前建议主路径：${recommendation.nextPath}。${recommendation.guidance}`
+      ? `当前工作流约束：${recommendation.summary} 当前建议下一阶段：CONSOLIDATE。${recommendation.guidance} 若本次明确使用 ~auto，则在未命中阻塞判定时直接完成当前收尾，不再额外停下询问。`
+      : `当前工作流约束：${recommendation.summary} 当前建议主路径：${recommendation.nextPath}。${recommendation.guidance} 若本次明确使用 ~auto，则命中主路径后继续衔接后续阶段，除非触发阻塞判定，否则不要在方案/PRD 阶段额外停下。`
   }
   if (skillName === 'plan') {
     if (recommendation.stage === 'consolidate') {
@@ -87,8 +87,8 @@ function buildCommandRouteMessage(skillName, recommendation, verifyModeHint) {
   return `当前工作流约束：${recommendation.summary} 当前建议下一命令：~${recommendation.nextCommand}。${recommendation.guidance}`
 }
 
-export function buildCommandRouteHint(skillName, cwd) {
-  const snapshot = getWorkflowSnapshot(cwd)
+export function buildCommandRouteHint(skillName, cwd, options = {}) {
+  const snapshot = getWorkflowSnapshot(cwd, options)
   const recommendation = buildRecommendation(snapshot, cwd)
   const contextHints = [
     buildStateRoleHintFromSnapshot(snapshot),

package/skills/_meta/SKILL.md

@@ -7,7 +7,7 @@ policy:
 
 ## Skill 系统
 Skills 是带 YAML frontmatter 的 Markdown 文件。
-- helloagents: 检查清单驱动的质量门控（每次对话自动加载）
+- helloagents: 由检查清单驱动的质量把关（每次对话自动加载）
 - hello-*: 质量技能（根据任务自动激活，提供实现标准和交付检查清单）
 - commands/*: 用户通过 ~command 调用
 

package/skills/commands/auto/SKILL.md

@@ -1,27 +1,28 @@
 ---
 name: ~auto
-description: 自动选路命令 — 根据任务自动选择 ~idea / ~plan / ~build / ~verify / ~prd 的组合路径（~auto 命令）
+description: 自动编排命令 — 自动选择并串联 ~idea / ~plan / ~build / ~verify / ~prd，默认持续推进直到交付完成（~auto 命令）
 policy:
   allow_implicit_invocation: false
 ---
 Trigger: ~auto <任务描述>
 
-`~auto` 是自动选路命令。它根据任务类型、复杂度、风险等级与项目状态，自动在 `~idea`、`~plan`、`~build`、`~verify`、`~prd` 之间选择合适路径。
-`~auto` 只做选路。路径一旦确定，立即读取对应 command skill 并按其流程执行。
+`~auto` 是自动编排命令。它根据任务类型、复杂度、风险等级与项目状态，自动在 `~idea`、`~plan`、`~build`、`~verify`、`~prd` 之间选择合适主路径，并把这些阶段串成一条连续交付链路。
+`~auto` 不止做一次选路；主路径一旦确定，就按需要继续衔接后续阶段，默认持续推进直到完成交付，只有命中 bootstrap 的阻塞判定时才停下。
 
 ## 铁律
 - 不为了“自动化”而强行走重流程
 - 复杂度与风险不足以支撑更重路径时，优先选更轻但能保证质量的路线
 - `T3` 高风险或不可逆链路默认不直接进入 `~build`；优先先走 `~plan` 或 `~prd`，纯审查/纯验证请求才可先进入 `~verify`
-- 选路一旦确定，立即读取对应 command skill，避免重复探索
+- 主路径一旦确定，立即读取对应 command skill，并在阶段完成后继续衔接后续阶段，避免同一任务重复探索或重复等待
 - 选路不替代授权；涉及外部副作用或高风险不可逆操作时，仍遵守 bootstrap 的阻塞判定与确认规则
-- 优先消费当前上下文已注入的 ROUTE / TIER、当前工作流约束与项目状态；不要在 `~auto` 内另建一套关键词路由表
+- 用户显式使用 `~auto`，表示已授权在当前任务边界内沿选定主路径持续执行；`~plan` / `~prd` 作为中间阶段时，不再额外询问“是否开始执行”，除非仍有真实阻塞
+- 优先消费当前上下文中已注入的 ROUTE / TIER、当前工作流约束与项目状态；不要在 `~auto` 内另建一套关键词路由表
 
 ## 流程
 
 ### 0. 当前工作流优先
 
-- 若当前上下文已注入“当前工作流提示”或“当前工作流约束”，优先服从其中的推荐下一命令 / 主路径
+- 若当前上下文中已注入“当前工作流提示”或“当前工作流约束”，优先服从其中的推荐下一命令 / 主路径
 - 默认原则：
   - 活跃方案包不完整或缺少任务清单 → 先 `~plan`
   - 活跃方案包仍在执行 → 先 `~build`，完成当前实现后再 `~verify`
@@ -31,7 +32,7 @@ Trigger: ~auto <任务描述>
 ### 1. 选路
 
 - 先按当前上下文里已注入的 ROUTE / TIER 语义约束判断，不依赖关键词命中做机械分流
-- 若当前轮没有足够的注入约束，再结合以下信号补足判断：影响范围、风险等级、是否需要 artifact、是否已有活跃方案包、用户是否只想先比较方向
+- 若本轮没有足够的注入约束，再结合以下信号补足判断：影响范围、风险等级、是否需要结构化产物、是否已有活跃方案包、用户是否只想先比较方向
 - 选路优先级：
   - 纯探索 / 点子 / 方向比较 → `~idea`
   - 明确要求验证 / 审查 / 跑检查 → `~verify`
@@ -43,10 +44,10 @@ Trigger: ~auto <任务描述>
 
 - `T0` → 保持在 `~idea`，不创建项目文件
 - `T1` → 在 `~build` / `~verify` 间选择最短可交付路径
-- `T2` → 需要 artifact 或范围未完全收敛时优先 `~plan`
+- `T2` → 需要结构化产物或范围未完全收敛时优先 `~plan`
 - `T3` → 纯审查/验真走 `~verify`；其余默认 `~plan` 或 `~prd`，待方案与风险边界明确后再进入实现
 
-### 3. 读取对应命令并执行
+### 3. 读取对应命令并执行主路径
 
 - 选中 `idea` → 读取 `skills/commands/idea/SKILL.md`
 - 选中 `plan` → 读取 `skills/commands/plan/SKILL.md`
@@ -55,3 +56,17 @@ Trigger: ~auto <任务描述>
 - 选中 `prd` → 读取 `skills/commands/prd/SKILL.md`
 
 不要额外读取未选中的 command skill。
+
+### 4. 自动衔接直到完成
+
+- 若主路径是 `~build` → 完成实现后继续进入 `~verify`，再按当前链路进入收尾
+- 若主路径是 `~plan` → 方案包落地后，若当前链路来自 `~auto` 且未命中阻塞判定，直接继续进入 `~build`，不要把“方案已形成”当作最终停点
+- 若主路径是 `~prd` → PRD / 任务 / 契约落地后，若当前链路来自 `~auto` 且未命中阻塞判定，按收敛结果继续进入 `~build`，必要时先补一轮轻量 `~plan`
+- 若主路径是 `~verify` → 完成审查 / 验证 / 收尾后结束
+- 若主路径是 `~idea`，且用户本意就是探索/比较，则在探索输出后结束；若探索后已收敛成明确方向且当前任务仍要求落地，则继续进入 `~plan` 或 `~build`
+
+### 5. 何时允许停下
+
+- 仅在 bootstrap 的阻塞判定成立时停下：真实歧义、缺必需信息/文件/凭据、未授权外部副作用、高风险或不可逆操作
+- 不得把 `~plan` / `~prd` 中“是否进入执行”的默认询问原样带入 `~auto` 链路
+- 不得把“给出方案”“给出任务列表”“给出建议下一步”当作 `~auto` 的默认完成态；用户显式要求 `~auto` 时，默认目标是把当前任务推进到可交付完成

package/skills/commands/build/SKILL.md

@@ -8,7 +8,7 @@ Trigger: ~build [description]
 
 `~build` 是执行实现命令。它负责读取现有需求、方案包与项目上下文，完成实现、局部验证、修复循环，并把结果衔接到后续验证与收尾。
 执行 `~build` 时，通用阶段边界按当前已加载 bootstrap 执行；本 skill 负责补充实现前定位、实现约束，以及进入 `~verify` / 收尾前的实现边界。
-`.helloagents/` 在本 skill 中表示逻辑项目空间：`STATE.md` 与 `.ralph-*.json` 保持项目本地；若 `project_store_mode=repo-shared`，知识库、`DESIGN.md`、`verify.yaml` 与方案包按当前会话注入的项目知识/方案目录解析。
+`.helloagents/` 在本 skill 中统一按项目级存储路径理解：`STATE.md` 与 `.ralph-*.json` 保持项目本地；若当前上下文中的“当前项目存储”给出 `state_path`，本轮恢复快照统一读写该路径；若 `project_store_mode=repo-shared`，知识库、`DESIGN.md`、`verify.yaml` 与方案包按当前上下文中已注入的项目知识/方案目录解析。
 
 ## 铁律
 - 默认先定位上下文与范围，再修改代码
@@ -20,15 +20,15 @@ Trigger: ~build [description]
 
 ### 1. 恢复与定位
 
-- 优先按当前已加载 bootstrap 的“.helloagents/ 文件读取优先级”恢复当前链路；若当前消息显式继续既有链路，或会话刚经历恢复 / 压缩，先读取 `.helloagents/STATE.md` 作为恢复快照，再用当前用户消息、活跃方案包 / PRD 与代码事实校正主线
+- 优先按当前已加载 bootstrap 的“.helloagents/ 文件读取优先级”恢复当前链路；若当前消息显式继续既有链路，或会话刚经历恢复 / 压缩，先读取 `.helloagents/STATE.md` 作为恢复快照（若当前项目存储给出 `state_path`，则优先读取该当前会话的 `STATE.md`），再用当前用户消息、活跃方案包 / PRD 与代码事实校正主线
 - 若存在最近的活跃方案包，读取对应的：
   - `requirements.md`
   - `plan.md`
   - `tasks.md`
   - `contract.json`
-  - 实现时优先把 `tasks.md` 中每个任务的“完成标准”当作本轮 build contract，不要只按任务标题猜测范围
+  - 实现时优先把 `tasks.md` 中每个任务的“完成标准”当作本轮实现约束，不要只按任务标题猜测范围
   - `contract.json` 存在时，优先按其中的 `verifyMode`、`reviewerFocus`、`testerFocus` 理解后续验证边界
-- 若当前上下文已注入“当前工作流约束”或“当前建议下一命令”，先服从它；只有推荐仍为 `~build`，或用户明确提出新增实现范围时，才继续 `~build`
+- 若当前上下文中已注入“当前工作流约束”或“当前建议下一命令”，先服从它；只有推荐仍为 `~build`，或用户明确提出新增实现范围时，才继续 `~build`
 - 其余项目知识库与相关代码文件，按 bootstrap 的项目上下文规则按需读取
 - 若任务涉及 UI，按以下优先级读取并遵循：当前活跃 `plan.md` / PRD 中的 UI 决策 > 逻辑 `.helloagents/DESIGN.md`（实际路径按当前项目存储模式解析） > `hello-ui` 通用规则
 - 若已激活项目且当前任务属于整页新建、设计系统改造、或跨多个组件的视觉重做，但逻辑 `.helloagents/DESIGN.md` 不存在，先按模板创建最小设计契约，再继续大规模实现

package/skills/commands/clean/SKILL.md

@@ -7,13 +7,13 @@ policy:
 Trigger: ~clean
 
 执行 `~clean` 时，方案包归档、临时文件清理和 `STATE.md` 更新边界按当前已加载 bootstrap 执行；本命令只负责判定哪些方案包可以清理，以及输出清理摘要。
-`.helloagents/` 在本 skill 中表示逻辑项目空间：`STATE.md` 和临时运行态文件保持项目本地；若 `project_store_mode=repo-shared`，`plans/` 与 `archive/` 按当前会话注入的项目知识/方案目录解析。
+`.helloagents/` 在本 skill 中统一按项目级存储路径理解：`STATE.md` 和临时运行态文件保持项目本地；若当前上下文中的“当前项目存储”给出 `state_path`，本轮恢复快照统一读写该路径；若 `project_store_mode=repo-shared`，`plans/` 与 `archive/` 按当前上下文中已注入的项目知识/方案目录解析。
 
 ## 流程
 
-1. 扫描逻辑 `.helloagents/plans/` 下的方案包（`project_store_mode=repo-shared` 时按当前知识/方案目录解析）
+1. 扫描 `.helloagents/plans/` 下的方案包（按当前项目存储模式解析；`project_store_mode=repo-shared` 时使用共享知识/方案目录）
 2. 判定完成状态：优先以 tasks.md 中所有任务已标记 [√] 为准；只有任务清单无法判断时，才把 `STATE.md` 中与当前方案一致的“主线目标”+“正在做什么”作为辅助信号，避免把旧恢复快照误当当前主线
-3. 已完成的方案包 → 按 bootstrap 的归档规则移入逻辑 `.helloagents/archive/YYYY-MM/`，并同步更新逻辑 `.helloagents/archive/_index.md`
+3. 已完成的方案包 → 按 bootstrap 的归档规则移入 `.helloagents/archive/YYYY-MM/`（按当前项目存储模式解析），并同步更新 `.helloagents/archive/_index.md`
 4. 清理 bootstrap 中定义的临时文件
 5. 按 bootstrap 的流程状态规则更新 `STATE.md`；若当前状态指向已归档方案包，则清空对应方案路径
 7. 输出清理摘要（归档了几个方案包、清理了哪些文件）

package/skills/commands/commit/SKILL.md

@@ -20,7 +20,7 @@ Trigger: ~commit [message]
    - ""（空，默认）→ 不添加归属
    - 有内容（如 "Co-Authored-By: HelloAGENTS"）→ 添加该内容到 commit message
 6. 执行 git commit
-7. 若项目已有 `.helloagents/STATE.md`，按 bootstrap 的“已有则更新”规则同步当前已提交状态
+7. 若当前 `STATE.md` 已存在（优先取当前项目存储中的 `state_path`，未注入时回退 `.helloagents/STATE.md`），按 bootstrap 的“已有则更新”规则同步当前已提交状态
 
 ## 知识库同步
 提交后，继续复用上方已解析的同一份设置获取 `kb_create_mode`，不要再次读取 `~/.helloagents/helloagents.json`：