helloagents 3.0.12 → 3.0.15-beta.1

package/scripts/visual-state.mjs

@@ -1,12 +1,19 @@
-import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
-import { join } from 'node:path'
+import { readFileSync } from 'node:fs'
 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
+import {
+  captureWorkspaceFingerprint,
+  clearRuntimeEvidence,
+  getRuntimeEvidencePath,
+  getRuntimeEvidenceRelativePath,
+  readRuntimeEvidence,
+  validateEvidenceFingerprint,
+  validateEvidenceTimestamp,
+  writeRuntimeEvidence,
+} from './runtime-artifacts.mjs'
+
+export const VISUAL_EVIDENCE_FILE_NAME = 'visual.json'
 const VALID_VISUAL_STATUSES = new Set(['PASS', 'BLOCKED'])
 
 function normalizeStringArray(values) {
@@ -24,20 +31,16 @@ function findMissingCoverage(requested = [], completed = []) {
   return normalizeStringArray(requested).filter((entry) => !completedSet.has(entry))
 }
 
-export function getVisualEvidencePath(cwd) {
-  return join(cwd, '.helloagents', VISUAL_EVIDENCE_FILE_NAME)
+export function getVisualEvidencePath(cwd, options = {}) {
+  return getRuntimeEvidencePath(cwd, VISUAL_EVIDENCE_FILE_NAME, options)
 }
 
-export function readVisualEvidence(cwd) {
-  try {
-    return JSON.parse(readFileSync(getVisualEvidencePath(cwd), 'utf-8'))
-  } catch {
-    return null
-  }
+export function readVisualEvidence(cwd, options = {}) {
+  return readRuntimeEvidence(cwd, VISUAL_EVIDENCE_FILE_NAME, options)
 }
 
-export function clearVisualEvidence(cwd) {
-  rmSync(getVisualEvidencePath(cwd), { force: true })
+export function clearVisualEvidence(cwd, options = {}) {
+  clearRuntimeEvidence(cwd, VISUAL_EVIDENCE_FILE_NAME, options)
 }
 
 export function normalizeVisualEvidence(input = {}) {
@@ -55,19 +58,19 @@ export function normalizeVisualEvidence(input = {}) {
   }
 }
 
-export function writeVisualEvidence(cwd, input = {}) {
-  mkdirSync(join(cwd, '.helloagents'), { recursive: true })
+export function writeVisualEvidence(cwd, input = {}, options = {}) {
   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')
+  writeRuntimeEvidence(cwd, VISUAL_EVIDENCE_FILE_NAME, payload, options)
   appendReplayEvent(cwd, {
     event: 'visual_evidence_written',
     source: normalized.source,
     skillName: normalized.originCommand,
+    payload: options.payload || {},
     details: {
       reason: normalized.reason,
       tooling: normalized.tooling,
@@ -75,12 +78,12 @@ export function writeVisualEvidence(cwd, input = {}) {
       statesChecked: normalized.statesChecked,
       status: normalized.status,
     },
-    artifacts: ['.helloagents/.ralph-visual.json'],
+    artifacts: [getRuntimeEvidenceRelativePath(cwd, VISUAL_EVIDENCE_FILE_NAME, options)],
   })
   return payload
 }
 
-function readRequiredVisualEvidence(cwd, required) {
+function readRequiredVisualEvidence(cwd, required, options = {}) {
   if (!required) {
     return {
       required: false,
@@ -88,53 +91,23 @@ function readRequiredVisualEvidence(cwd, required) {
     }
   }
 
-  const evidence = readVisualEvidence(cwd)
+  const evidence = readVisualEvidence(cwd, options)
   if (evidence) return { evidence }
   return {
     error: {
       required: true,
       status: 'missing',
-      details: ['missing visual validation evidence required by the active UI contract'],
+      details: ['缺少当前 UI 契约要求的视觉验收证据'],
     },
   }
 }
 
 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
+  return validateEvidenceTimestamp(evidence, now, '视觉验收证据')
 }
 
 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
+  return validateEvidenceFingerprint(cwd, evidence, '视觉验收证据')
 }
 
 function validateVisualContent(evidence, { screens = [], states = [] } = {}) {
@@ -144,7 +117,7 @@ function validateVisualContent(evidence, { screens = [], states = [] } = {}) {
       required: true,
       status: 'invalid',
       evidence,
-      details: ['visual validation evidence must record explicit status, reason, and summary'],
+      details: ['视觉验收证据必须记录明确的 status、reason 和 summary'],
     }
   }
   if (normalized.tooling.length === 0) {
@@ -152,7 +125,7 @@ function validateVisualContent(evidence, { screens = [], states = [] } = {}) {
       required: true,
       status: 'invalid',
       evidence,
-      details: ['visual validation evidence must record the tooling used for the check'],
+      details: ['视觉验收证据必须记录使用的检查工具'],
     }
   }
   if (normalized.screensChecked.length === 0 && normalized.statesChecked.length === 0) {
@@ -160,7 +133,7 @@ function validateVisualContent(evidence, { screens = [], states = [] } = {}) {
       required: true,
       status: 'invalid',
       evidence,
-      details: ['visual validation evidence must record at least one checked screen or state'],
+      details: ['视觉验收证据必须记录至少一个已检查视口或状态'],
     }
   }
 
@@ -170,7 +143,7 @@ function validateVisualContent(evidence, { screens = [], states = [] } = {}) {
       required: true,
       status: 'invalid',
       evidence,
-      details: [`visual validation evidence does not cover requested screens: ${missingScreens.join(', ')}`],
+      details: [`视觉验收证据未覆盖要求的视口：${missingScreens.join(', ')}`],
     }
   }
 
@@ -180,7 +153,7 @@ function validateVisualContent(evidence, { screens = [], states = [] } = {}) {
       required: true,
       status: 'invalid',
       evidence,
-      details: [`visual validation evidence does not cover requested states: ${missingStates.join(', ')}`],
+      details: [`视觉验收证据未覆盖要求的状态：${missingStates.join(', ')}`],
     }
   }
 
@@ -189,14 +162,14 @@ function validateVisualContent(evidence, { screens = [], states = [] } = {}) {
       required: true,
       status: 'blocked',
       evidence,
-      details: ['latest visual validation evidence still records blocking findings'],
+      details: ['最新视觉验收证据仍记录阻塞问题'],
     }
   }
   return null
 }
 
-export function getVisualEvidenceStatus(cwd, { required = false, screens = [], states = [], now = Date.now() } = {}) {
-  const requiredEvidence = readRequiredVisualEvidence(cwd, required)
+export function getVisualEvidenceStatus(cwd, { required = false, screens = [], states = [], now = Date.now(), ...options } = {}) {
+  const requiredEvidence = readRequiredVisualEvidence(cwd, required, options)
   if ('status' in requiredEvidence) return requiredEvidence
   if (requiredEvidence.error) return requiredEvidence.error
 
@@ -231,10 +204,10 @@ function main() {
 
   const input = readStdinJson()
   const cwd = input.cwd || process.cwd()
-  const payload = writeVisualEvidence(cwd, input)
+  const payload = writeVisualEvidence(cwd, input, { payload: input })
   process.stdout.write(JSON.stringify({
     suppressOutput: true,
-    path: getVisualEvidencePath(cwd),
+    path: getVisualEvidencePath(cwd, { payload: input }),
     payload,
   }))
 }

package/scripts/workflow-core.mjs

@@ -162,10 +162,10 @@ export function buildUiContractHint(cwd, snapshot) {
 
   const extraHints = []
   if (styleAdvisorRequired) {
-    extraHints.push('若当前 UI 契约要求 style advisor，收尾前需复用 `.helloagents/.ralph-advisor.json` 留下独立复查证据')
+    extraHints.push('若当前 UI 契约要求 style advisor，收尾前需写当前会话 `artifacts/advisor.json` 留下独立复查证据')
   }
   if (visualValidationRequired) {
-    extraHints.push('若当前 UI 契约要求视觉验收，收尾前需写 `.helloagents/.ralph-visual.json` 记录关键视口、状态与结论')
+    extraHints.push('若当前 UI 契约要求视觉验收，收尾前需写当前会话 `artifacts/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

@@ -167,7 +167,7 @@ function findTemplateIssues(fileName, filePath) {
   const content = readText(filePath)
   return (PLAN_TEMPLATE_MARKERS[fileName] || [])
     .filter((pattern) => pattern.test(content))
-    .map(() => `${fileName} still contains template placeholders`)
+    .map(() => `${fileName} 仍包含模板占位内容`)
 }
 
 function comparePlanEntries(a, b) {

package/scripts/workflow-recommendation.mjs

@@ -11,22 +11,25 @@ import {
   normalizeTaskFile,
 } from './workflow-core.mjs'
 
-function getClosedPlanEvidenceStatus(cwd, plan) {
+function getClosedPlanEvidenceStatus(cwd, plan, options = {}) {
   const verifyMode = determineVerifyMode(plan)
   const advisorRequirement = getAdvisorRequirement(plan.contract)
   const visualRequirement = getVisualValidationRequirement(plan.contract)
-  const verificationStatus = getVerifyEvidenceStatus(cwd)
+  const verificationStatus = getVerifyEvidenceStatus(cwd, options)
   const reviewStatus = getReviewEvidenceStatus(cwd, {
     required: verifyMode?.mode === 'review-first',
+    ...options,
   })
   const advisorStatus = getAdvisorEvidenceStatus(cwd, {
     required: advisorRequirement.required,
     focus: advisorRequirement.focus,
+    ...options,
   })
   const visualStatus = getVisualEvidenceStatus(cwd, {
     required: visualRequirement.required,
     screens: visualRequirement.screens,
     states: visualRequirement.states,
+    ...options,
   })
   const verifyReady = !verificationStatus.required || verificationStatus.status === 'valid'
   const reviewReady = !reviewStatus.required || reviewStatus.status === 'valid'
@@ -34,6 +37,7 @@ function getClosedPlanEvidenceStatus(cwd, plan) {
   const visualReady = !visualStatus.required || visualStatus.status === 'valid'
   const closeoutStatus = getCloseoutEvidenceStatus(cwd, {
     required: verifyReady && reviewReady && advisorReady && visualReady,
+    ...options,
   })
 
   return {
@@ -59,7 +63,7 @@ function buildConsolidateAction(recommendation) {
       phase: 'consolidate',
       mode: recommendation.mode,
       routeHint: recommendation.guidance,
-      gateHint: '交付把关：审查与验证证据已满足；先写 `.helloagents/.ralph-closeout.json` 记录需求覆盖与交付清单，再更新 `state_path` 并归档后才可交付。',
+      gateHint: '交付把关：审查与验证证据已满足；先写当前会话 `artifacts/closeout.json` 记录需求覆盖与交付清单，再更新 `state_path` 并归档后才可交付。',
     }
   }
 
@@ -77,10 +81,10 @@ function buildVerifyAction(plan, verifyMode) {
   const visualRequirement = getVisualValidationRequirement(plan.contract)
   const extraChecks = []
   if (advisorRequirement.required) {
-    extraChecks.push('完成独立 advisor / style advisor 复查并写入 `.helloagents/.ralph-advisor.json`')
+    extraChecks.push('完成独立 advisor / style advisor 复查并写入当前会话 `artifacts/advisor.json`')
   }
   if (visualRequirement.required) {
-    extraChecks.push('完成视觉验收并写入 `.helloagents/.ralph-visual.json`')
+    extraChecks.push('完成视觉验收并写入当前会话 `artifacts/visual.json`')
   }
   const gateSuffix = extraChecks.length > 0 ? ` ${extraChecks.join('，')}，再进入 CONSOLIDATE。` : ''
   if (verifyMode.mode === 'review-first') {
@@ -171,8 +175,8 @@ function buildInProgressRecommendation(scopeLabel, plan, classification) {
   }
 }
 
-function buildClosedRecommendation(scopeLabel, plan, cwd) {
-  const closedPlanEvidence = getClosedPlanEvidenceStatus(cwd, plan)
+function buildClosedRecommendation(scopeLabel, plan, cwd, options = {}) {
+  const closedPlanEvidence = getClosedPlanEvidenceStatus(cwd, plan, options)
   if (closedPlanEvidence.verifyMode?.mode === 'metadata-first') {
     return {
       scopeLabel,
@@ -198,7 +202,7 @@ function buildClosedRecommendation(scopeLabel, plan, cwd) {
       nextCommand: 'verify',
       nextPath: '~verify -> CONSOLIDATE',
       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。',
+      guidance: '先在 ~verify 阶段完成独立 advisor / style advisor 复查，并写入当前会话 `artifacts/advisor.json`；再完成视觉验收并写入当前会话 `artifacts/visual.json`，记录 reason、tooling、screensChecked、statesChecked、status 与 summary；两项都通过后再进入 CONSOLIDATE。',
     }
   }
 
@@ -210,7 +214,7 @@ function buildClosedRecommendation(scopeLabel, plan, cwd) {
       nextCommand: 'verify',
       nextPath: '~verify -> CONSOLIDATE',
       summary: `${scopeLabel} "${plan.planName}" 的任务已闭合，但当前契约仍要求独立 advisor 复查。`,
-      guidance: '先在 ~verify 阶段完成独立 advisor / style advisor 复查，并写入 `.helloagents/.ralph-advisor.json` 记录复查原因、focus、来源与结论；advisor 通过后再进入 CONSOLIDATE。',
+      guidance: '先在 ~verify 阶段完成独立 advisor / style advisor 复查，并写入当前会话 `artifacts/advisor.json` 记录复查原因、focus、来源与结论；advisor 通过后再进入 CONSOLIDATE。',
     }
   }
 
@@ -222,7 +226,7 @@ function buildClosedRecommendation(scopeLabel, plan, cwd) {
       nextCommand: 'verify',
       nextPath: '~verify -> CONSOLIDATE',
       summary: `${scopeLabel} "${plan.planName}" 的任务已闭合，但当前 UI 契约仍要求视觉验收。`,
-      guidance: '先在 ~verify 阶段完成视觉验收，并写入 `.helloagents/.ralph-visual.json` 记录 reason、tooling、screensChecked、statesChecked、status 与 summary；视觉验收通过后再进入 CONSOLIDATE。',
+      guidance: '先在 ~verify 阶段完成视觉验收，并写入当前会话 `artifacts/visual.json` 记录 reason、tooling、screensChecked、statesChecked、status 与 summary；视觉验收通过后再进入 CONSOLIDATE。',
     }
   }
 
@@ -240,7 +244,7 @@ function buildClosedRecommendation(scopeLabel, plan, cwd) {
         : `${scopeLabel} "${plan.planName}" 的任务、审查与验证已闭合。`,
       guidance: closedPlanEvidence.closeoutReady
         ? '当前进入 CONSOLIDATE：更新 `state_path`、知识文件并归档方案后即可交付；不要无故重开新的方案包或重新跑一遍无关验证。'
-        : '当前进入 CONSOLIDATE：先写 `.helloagents/.ralph-closeout.json` 记录需求覆盖与交付清单，再更新 `state_path` 并归档后交付。',
+        : '当前进入 CONSOLIDATE：先写当前会话 `artifacts/closeout.json` 记录需求覆盖与交付清单，再更新 `state_path` 并归档后交付。',
     }
   }
 
@@ -255,7 +259,7 @@ function buildClosedRecommendation(scopeLabel, plan, cwd) {
   }
 }
 
-export function buildRecommendation(snapshot, cwd = process.cwd()) {
+export function buildRecommendation(snapshot, cwd = process.cwd(), options = {}) {
   const plan = getTargetPlans(snapshot)[0]
   if (!plan) return null
 
@@ -269,7 +273,7 @@ export function buildRecommendation(snapshot, cwd = process.cwd()) {
     return buildInProgressRecommendation(scopeLabel, plan, classification)
   }
   if (classification.status === 'closed') {
-    return buildClosedRecommendation(scopeLabel, plan, cwd)
+    return buildClosedRecommendation(scopeLabel, plan, cwd, options)
   }
   return null
 }

package/scripts/workflow-state.mjs

@@ -18,12 +18,12 @@ import {
 
 export function getDeliveryAction(cwd, options = {}) {
   const snapshot = getWorkflowSnapshot(cwd, options)
-  const recommendation = buildRecommendation(snapshot, cwd)
+  const recommendation = buildRecommendation(snapshot, cwd, options)
   return buildDeliveryActionFromSnapshot(snapshot, cwd, recommendation)
 }
 
 export function getWorkflowRecommendation(cwd, options = {}) {
-  return buildRecommendation(getWorkflowSnapshot(cwd, options), cwd)
+  return buildRecommendation(getWorkflowSnapshot(cwd, options), cwd, options)
 }
 
 export function buildStateSyncHint(cwd, options = {}) {
@@ -32,12 +32,12 @@ export function buildStateSyncHint(cwd, options = {}) {
 
 export function buildDeliveryGateHint(cwd, options = {}) {
   const snapshot = getWorkflowSnapshot(cwd, options)
-  return buildDeliveryGateHintFromSnapshot(snapshot, cwd, buildRecommendation(snapshot, cwd))
+  return buildDeliveryGateHintFromSnapshot(snapshot, cwd, buildRecommendation(snapshot, cwd, options))
 }
 
 export function buildWorkflowRouteHint(cwd, options = {}) {
   const snapshot = getWorkflowSnapshot(cwd, options)
-  const recommendation = buildRecommendation(snapshot, cwd)
+  const recommendation = buildRecommendation(snapshot, cwd, options)
   const stateSyncHint = buildStateSyncHintFromSnapshot(snapshot)
   const stateRoleHint = buildStateRoleHintFromSnapshot(snapshot)
   const orchestrationHint = buildOrchestrationHintFromSnapshot(snapshot, cwd, recommendation)
@@ -92,7 +92,7 @@ function buildCommandRouteMessage(skillName, recommendation, verifyModeHint) {
 
 export function buildCommandRouteHint(skillName, cwd, options = {}) {
   const snapshot = getWorkflowSnapshot(cwd, options)
-  const recommendation = buildRecommendation(snapshot, cwd)
+  const recommendation = buildRecommendation(snapshot, cwd, options)
   const contextHints = [
     buildStateRoleHintFromSnapshot(snapshot),
     buildStateSyncHintFromSnapshot(snapshot),

package/skills/commands/build/SKILL.md

@@ -8,7 +8,7 @@ Trigger: ~build [description]
 
 `~build` 是执行实现命令。它负责读取现有需求、方案包与项目上下文，完成实现、局部验证、修复循环，并把结果交给后续验证与收尾。
 执行 `~build` 时，通用阶段边界按当前已加载 bootstrap 执行；本 skill 负责补充实现前定位、实现约束，以及进入 `~verify` / 收尾前的实现边界。
-`.helloagents/` 在本 skill 中统一按项目级存储路径理解：状态文件只使用 `state_path`，`.ralph-*.json` 保持项目本地；若 `project_store_mode=repo-shared`，知识库、`DESIGN.md`、`verify.yaml` 与方案包按当前上下文中已注入的项目知识/方案目录解析。
+`.helloagents/` 在本 skill 中统一按项目级存储路径理解：状态文件只使用 `state_path`；会话证据使用当前 `state_path` 所在目录下的 `artifacts/*.json`；若 `project_store_mode=repo-shared`，知识库、`DESIGN.md`、`verify.yaml` 与方案包按当前上下文中已注入的项目知识/方案目录解析。
 
 ## 铁律
 - 默认先定位上下文与范围，再修改代码

package/skills/commands/commit/SKILL.md

@@ -15,7 +15,7 @@ Trigger: ~commit [message]
 3. 生成 conventional commit message（如未提供）
    - 格式: type(scope): description
    - type: feat|fix|refactor|docs|test|chore|style|perf
-4. 先一次性解析本轮设置：优先使用当前上下文中已注入的“当前用户设置”；只有上下文不存在时才读取一次 `~/.helloagents/helloagents.json`
+4. 先一次性解析本轮设置：优先使用当前上下文中已注入的“当前用户设置”；上下文不存在或缺少 `commit_attribution` / `kb_create_mode` 时，读取一次 `~/.helloagents/helloagents.json`
 5. 复用上一步已解析的设置获取 `commit_attribution`：
    - ""（空，默认）→ 不添加归属
    - 有内容（如 "Co-Authored-By: HelloAGENTS"）→ 添加该内容到 commit message

package/skills/commands/help/SKILL.md

@@ -39,14 +39,14 @@ Trigger: ~help
 完成时：hello-verify, hello-reflect
 
 ### 当前设置
-优先使用当前上下文中已注入的“当前用户设置”显示；仅在上下文不存在该信息时，才尝试读取 `~/.helloagents/helloagents.json`。
+优先使用当前上下文中已注入的“当前用户设置”显示；若上下文不存在该信息，或缺少下表任一配置项，读取一次 `~/.helloagents/helloagents.json`。
 如果当前 CLI 存在工作区限制导致家目录不可读，则明确说明“无法直接读取配置文件，以下按已注入设置或默认值展示”，不要改用无关工具或伪造已读取结果。
 | 配置项 | 默认值 | 作用 | 适用 CLI |
 |--------|-------|------|---------|
 | output_language | "" | 空=跟随用户语言/填写则指定（如 zh-CN、en） | Claude Code + Gemini CLI + Codex CLI |
-| output_format | true | true=仅主代理在最终收尾回复使用 HelloAGENTS 格式，所有流式/中间输出及子代理输出保持自然；false=自然输出 | Claude Code + Gemini CLI + Codex CLI |
+| output_format | true | true=主代理最终收尾必须使用 HelloAGENTS 格式，流式/中间输出及子代理输出保持自然；false=自然输出 | Claude Code + Gemini CLI + Codex CLI |
 | notify_level | 0 | 0=关闭/1=桌面通知/2=声音/3=两者 | Claude Code + Gemini CLI + Codex CLI |
-| ralph_loop_enabled | true | 自动验证循环（任务完成时触发 lint/test/build） | Claude Code + Gemini CLI + Codex CLI |
+| ralph_loop_enabled | true | 自动验证循环（显式 ~verify / ~loop 或收尾要求时触发 lint/test/build） | Claude Code + Gemini CLI + Codex CLI |
 | guard_enabled | true | 阻断危险命令与写入后的安全扫描 | Claude Code + Gemini CLI + Codex CLI |
 | kb_create_mode | 1 | 0=关闭/1=已激活项目或全局模式中编码自动/2=已激活项目或全局模式中始终 | Claude Code + Gemini CLI + Codex CLI |
 | project_store_mode | "local" | "local"=知识库/方案包保留在项目本地 `.helloagents/`；"repo-shared"=本地 `.helloagents/` 仅保留激活/STATE/运行态，知识库与方案包改写到 `~/.helloagents/projects/<repo-key>/` | Claude Code + Gemini CLI + Codex CLI |

package/skills/commands/loop/SKILL.md

@@ -22,7 +22,7 @@ Trigger: ~loop <目标描述> [--iterations N] [--metric "命令"] [--direction
 2. 确保 `.helloagents/` 目录和 `state_path` 存在；文件不存在时按 `templates/STATE.md` 创建。`~loop` 必须维护这个状态文件，不受 `kb_create_mode` 控制；“主线目标”固定写本次优化目标，避免混入其他任务
 3. 运行指标命令获取基线值，记录到 results log
 4. 如有守卫命令，运行确认基线通过
-5. 创建 `.helloagents/loop-results.tsv`，并确保 .gitignore 包含该文件
+5. 创建当前会话的 `.helloagents/sessions/{branch}/{session}/artifacts/loop-results.tsv`
 6. 根据优化目标标记可能需要的 hello-* 质量技能（如性能优化标记 hello-perf，UI 优化标记 hello-ui）
 7. 重写 `state_path`：记录主线目标=当前优化目标、基线指标、守卫命令、下一步设为第一轮迭代的具体动作
 

package/skills/commands/plan/SKILL.md

@@ -8,7 +8,7 @@ Trigger: ~plan [description]
 
 `~plan` 是实现前的主规划命令。它负责需求澄清、方案设计、任务拆解与方案写入；直接显式执行 `~plan` 时，默认停在“形成可执行方案”，只有用户明确授权继续时才继续执行。
 执行 `~plan` 时，通用阶段边界按当前已加载 bootstrap 执行；本 skill 负责补充 `~plan` 的需求澄清、方案确认、方案包写入与继续执行要求。
-`.helloagents/` 在本 skill 中统一按项目级存储路径理解：状态文件只使用 `state_path`，`.ralph-*.json` 保持项目本地；若 `project_store_mode=repo-shared`，知识库、`DESIGN.md` 与 `plans/` / `archive/` 按当前上下文中已注入的项目知识/方案目录解析。
+`.helloagents/` 在本 skill 中统一按项目级存储路径理解：状态文件只使用 `state_path`；会话证据使用当前 `state_path` 所在目录下的 `artifacts/*.json`；若 `project_store_mode=repo-shared`，知识库、`DESIGN.md` 与 `plans/` / `archive/` 按当前上下文中已注入的项目知识/方案目录解析。
 
 ## 铁律
 - 在用户确认方案之前，禁止编写任何实现代码、创建任何实现文件、或执行任何实现操作
@@ -39,6 +39,7 @@ Trigger: ~plan [description]
 - 先读取 5-15 个相关文件，基于代码证据形成假设
 - 用 2-4 轮确认关键假设
 - 低置信度假设必须明确询问
+- 发现用户用词与 `.helloagents/context.md` 的领域语言冲突时，立即澄清并统一术语
 
 **交互模式**（全新项目或信息不足）：
 - 每次只问一个问题，优先使用选择题
@@ -69,6 +70,7 @@ Trigger: ~plan [description]
 - 数据流与错误处理
 - 验证策略
 - 涉及 UI 时的设计方向、状态覆盖与 `DESIGN.md` 更新点
+- 涉及项目特有概念时，同步确认标准术语、避免用语和关键关系，必要时更新 `.helloagents/context.md` 的“领域语言”区块（按当前项目存储模式解析）
 
 ### 5. 写入方案包
 
@@ -81,7 +83,7 @@ Trigger: ~plan [description]
   - `tasks.md`
   - `contract.json`
 - 写 `contract.json` 时，至少落成以下字段：`verifyMode`、`reviewerFocus`、`testerFocus`；涉及 UI 时再写 `ui.required`、`ui.designContract` 与 `ui.sourcePriority`
-- 只有在 UI 方向确需先明确时，才额外写 `ui.styleAdvisor.required`、`ui.styleAdvisor.reason` 与 `ui.styleAdvisor.focus`；它复用 `.helloagents/.ralph-advisor.json`，不是默认常驻步骤
+- 只有在 UI 方向确需先明确时，才额外写 `ui.styleAdvisor.required`、`ui.styleAdvisor.reason` 与 `ui.styleAdvisor.focus`；它复用当前会话 `artifacts/advisor.json`，不是默认常驻步骤
 - 只有在 UI 验收确有收益时，才额外写 `ui.visualValidation.required`、`ui.visualValidation.reason`、`ui.visualValidation.screens` 与 `ui.visualValidation.states`；不要把视觉验收扩成所有 UI 任务的固定步骤
 - 只有在 `T3`、非 UI 的高风险审查或确需额外跨模型建议时，才写 `advisor.required`、`advisor.reason`、`advisor.focus` 与 `advisor.preferredSources`；不要把 advisor 变成默认常驻流程
 - 使用 `scripts/plan-contract.mjs write` 写 `contract.json`，不要让后续检查脚本再从 `plan.md` 的自然语言说明里猜验证主路径
@@ -103,10 +105,10 @@ Trigger: ~plan [description]
 ## 方案包要求
 
 方案包中的 `tasks.md` 必须满足：
-- 每个任务是一个原子操作
-- 明确文件路径、预期变更、完成标准与验证方式
-- 任务之间依赖关系清晰
-- 任务可独立验证
+- 每个任务默认是端到端垂直切片，能交付一个可验证行为；除非确有技术前置，否则不按“数据库 / API / UI / 测试”横向拆分
+- 每个任务标注 `AFK` 或 `HITL`：`AFK` 表示代理可独立完成，`HITL` 表示需要用户决策、外部凭据、人工视觉确认或手动验收
+- 明确文件路径、预期变更、完成标准、验证方式与依赖关系
+- 每个任务可独立验证；厚任务必须拆成更薄的可验收切片
 
 方案包中的 `contract.json` 必须满足：
 - `verifyMode` 只能是 `test-first` 或 `review-first`

package/skills/commands/prd/SKILL.md

@@ -8,7 +8,7 @@ Trigger: ~prd [description]
 
 执行 `~prd` 时，不读取 `~plan` 的 command skill；只有当前流程明确需要时，才继续读取对应的 hello-* 技能。
 执行 `~prd` 时，通用阶段边界按当前已加载 bootstrap 执行；本 skill 负责补充规格探索、PRD 写入与继续执行要求。
-`.helloagents/` 在本 skill 中统一按项目级存储路径理解：状态文件只使用 `state_path`，`.ralph-*.json` 保持项目本地；若 `project_store_mode=repo-shared`，知识库、`DESIGN.md` 与 `plans/` / `archive/` 按当前上下文中已注入的项目知识/方案目录解析。
+`.helloagents/` 在本 skill 中统一按项目级存储路径理解：状态文件只使用 `state_path`；会话证据使用当前 `state_path` 所在目录下的 `artifacts/*.json`；若 `project_store_mode=repo-shared`，知识库、`DESIGN.md` 与 `plans/` / `archive/` 按当前上下文中已注入的项目知识/方案目录解析。
 
 ## 铁律
 - 在用户确认方案之前，禁止编写任何实现代码、创建任何文件、或执行任何实现操作。
@@ -60,6 +60,7 @@ Trigger: ~prd [description]
 已有项目：
 - 按当前已加载 bootstrap 的“.helloagents/ 文件读取优先级”和“项目文件”规则恢复上下文；若当前消息明确要继续上次任务，或会话刚经历恢复 / 压缩，先读取 `state_path`，再用当前用户消息、显式命令、活跃方案包 / PRD 与代码事实确认当前任务
 - 在进入维度探索前，至少确认 `.helloagents/context.md`、`.helloagents/guidelines.md`，并只扫描与当前产品范围直接相关的代码和配置
+- 若 `.helloagents/context.md` 已有领域语言，PRD 中统一沿用；发现术语冲突或歧义时，先澄清再写入
 
 全新项目（无 .helloagents/ 目录）：
 - 跳过，直接进入项目定位
@@ -88,6 +89,7 @@ c. AI 总结该维度的决策结果，进入下一个维度
 - 用户说"默认" → AI 按推荐方案填充，快速过
 - 用户说"展开" → 深入讨论该维度的子项
 - 维度之间可以回溯：用户说"回到 03" → 重新讨论 UI/UX 设计
+- 涉及项目特有概念时，确认标准术语、避免用语和关键关系；不要把泛化技术词写入领域语言
 
 选项质量要求：
 - 涉及视觉/交互/体验的问题时，选项必须体现当前前沿设计水准
@@ -100,7 +102,7 @@ c. AI 总结该维度的决策结果，进入下一个维度
 - 按当前已加载 bootstrap 的 `.helloagents/` 与流程状态规则，确保最小项目状态已建立；这是方案包写入的前置操作，不受 kb_create_mode 开关控制
 - 创建 `.helloagents/plans/YYYYMMDDHHMM_{feature}/prd/`（按当前项目存储模式解析）
 - 按 templates/plans/prd/ 的模板格式，仅写入用户未跳过的维度文件
-- 生成 tasks.md（每个任务包含具体文件路径、预期变更、完成标准、验证方式；任务独立可验证；依赖顺序明确）
+- 生成 tasks.md（每个任务默认是端到端垂直切片，标注 AFK / HITL、依赖、具体文件路径、预期变更、完成标准与验证方式；任务独立可验证）
 - 生成 decisions.md（贯穿全程的决策日志）
 - 生成 `contract.json`（至少包含 `verifyMode`、`reviewerFocus`、`testerFocus`；涉及 UI 时补 `ui.required`、`ui.designContract`、`ui.sourcePriority`；仅在确需先明确审美方向时再补 `ui.styleAdvisor.required`、`ui.styleAdvisor.reason`、`ui.styleAdvisor.focus`；仅在确需视觉验收时再补 `ui.visualValidation.required`、`ui.visualValidation.reason`、`ui.visualValidation.screens`、`ui.visualValidation.states`；仅在确需独立 advisor 时，再补 `advisor.required`、`advisor.reason`、`advisor.focus`、`advisor.preferredSources`）
 - 使用 `scripts/plan-contract.mjs write` 写 `contract.json`，不要只把验证路径留在自然语言说明里
@@ -140,7 +142,7 @@ plans/YYYYMMDDHHMM_{feature}/
 │   ├── 02-functional.md
 │   └── ...
 ├── contract.json           # 机器可消费的验证 / 审查契约
-├── tasks.md                # 任务分解
+├── tasks.md                # 端到端垂直切片任务
 └── decisions.md            # 决策日志
 ```
 

package/skills/commands/verify/SKILL.md

@@ -13,8 +13,8 @@ Trigger: ~verify [scope]
    - 即使命令通过，也不能越过当前方案包边界：不完整方案包不能视为可信交付记录，未闭合方案包不能被整体报告为已完成
    - 当推荐路径已进入 `~verify` / 收尾时，优先把本命令用于审查、验真和交付收尾
    - 若当前存在活跃方案包，先读取 `requirements.md`、`plan.md`、`tasks.md`、`contract.json`，把它们当作本轮验证契约；不要只看命令结果
-   - 若 `contract.json` 声明 `advisor.required=true` 或 `ui.styleAdvisor.required=true`，则本轮还必须补齐 `.helloagents/.ralph-advisor.json`；advisor / style advisor 都是可选能力，不是默认常驻步骤
-   - 若 `contract.json` 声明 `ui.visualValidation.required=true`，则本轮还必须补齐 `.helloagents/.ralph-visual.json`；视觉验收优先用截图/浏览器工具，没有工具时才降级为结构化代码级自检
+   - 若 `contract.json` 声明 `advisor.required=true` 或 `ui.styleAdvisor.required=true`，则本轮还必须补齐当前会话 `artifacts/advisor.json`；advisor / style advisor 都是可选能力，不是默认常驻步骤
+   - 若 `contract.json` 声明 `ui.visualValidation.required=true`，则本轮还必须补齐当前会话 `artifacts/visual.json`；视觉验收优先用截图/浏览器工具，没有工具时才降级为结构化代码级自检
 1. 先决定验证分流：
    - 若当前上下文中已注入“验证分流”，先按该分流执行
    - 用户显式使用 `~review` 时，即使本轮没有注入分流，也按审查优先起步
@@ -23,15 +23,15 @@ Trigger: ~verify [scope]
    - 获取变更范围：无参数默认未提交变更；`staged` 代表暂存区；指定文件/目录则只审查对应范围
    - 按 hello-* 技能查找路径读取 `hello-review` SKILL.md，执行逐文件审查
    - 高风险流程除显式范围外，还要主动补查相关配置、迁移、权限、部署或安全边界文件，不能只盯住单个功能文件
-   - 审查结论确定后，立即调用 `scripts/review-state.mjs write` 写 `.helloagents/.ralph-review.json`；用结构化字段记录 `outcome`、`conclusion`、`findings`、`fileReferences`，不要让后续检查脚本再从自然语言消息里猜结论
+   - 审查结论确定后，立即调用 `scripts/review-state.mjs write` 写当前会话 `artifacts/review.json`；用结构化字段记录 `outcome`、`conclusion`、`findings`、`fileReferences`，不要让后续检查脚本再从自然语言消息里猜结论
 3. 全量验证模式或审查后继续验证：
    - 读取 `hello-verify` SKILL.md
    - 按其“验证命令来源”优先级检测命令
    - 逐个运行所有检测到的命令
    - 收集每个命令的输出和退出码
    - 对照当前契约逐项核对：requirements 是否覆盖、tasks 中每项“完成标准”是否满足、`plan.md` 中风险与设计约束是否被验证、`contract.json` 中声明的 `verifyMode` / reviewer / tester 关注边界是否已被覆盖
-   - 若 `advisor.required=true` 或 `ui.styleAdvisor.required=true`，在进入收尾前调用 `scripts/advisor-state.mjs write` 写 `.helloagents/.ralph-advisor.json`；记录触发原因、focus、consultedSources、结论与建议，禁止只在自然语言里留一段 advisor 意见
-   - 若 `ui.visualValidation.required=true`，在进入收尾前调用 `scripts/visual-state.mjs write` 写 `.helloagents/.ralph-visual.json`；记录 `reason`、`tooling`、`screensChecked`、`statesChecked`、`status`、`summary`、`findings` 与 `recommendations`
+   - 若 `advisor.required=true` 或 `ui.styleAdvisor.required=true`，在进入收尾前调用 `scripts/advisor-state.mjs write` 写当前会话 `artifacts/advisor.json`；记录触发原因、focus、consultedSources、结论与建议，禁止只在自然语言里留一段 advisor 意见
+   - 若 `ui.visualValidation.required=true`，在进入收尾前调用 `scripts/visual-state.mjs write` 写当前会话 `artifacts/visual.json`；记录 `reason`、`tooling`、`screensChecked`、`statesChecked`、`status`、`summary`、`findings` 与 `recommendations`
 4. 汇总报告：
    - ✅ 通过的审查项 / 命令
    - ❌ 失败的审查项 / 命令 + 错误详情