helloagents 3.0.18 → 3.0.19

package/scripts/notify-payload.mjs

@@ -0,0 +1,58 @@
+const PAYLOAD_KEY_ALIASES = {
+  'thread-id': 'threadId',
+  thread_id: 'threadId',
+  'turn-id': 'turnId',
+  turn_id: 'turnId',
+  'session-id': 'sessionId',
+  session_id: 'sessionId',
+  'last-assistant-message': 'lastAssistantMessage',
+  last_assistant_message: 'lastAssistantMessage',
+  'input-messages': 'inputMessages',
+  input_messages: 'inputMessages',
+  hook_event_name: 'hookEventName',
+  permission_mode: 'permissionMode',
+  stop_hook_active: 'stopHookActive',
+  'goal-id': 'goalId',
+  goal_id: 'goalId',
+}
+
+function assignAlias(target, source, sourceKey, targetKey) {
+  if (!Object.prototype.hasOwnProperty.call(source, sourceKey)) return
+  if (target[targetKey] !== undefined) return
+  target[targetKey] = source[sourceKey]
+}
+
+function readMessageText(entry) {
+  if (typeof entry === 'string') return entry
+  if (!entry || typeof entry !== 'object') return ''
+  if (typeof entry.text === 'string') return entry.text
+  if (typeof entry.content === 'string') return entry.content
+  if (Array.isArray(entry.content)) {
+    return entry.content
+      .map((part) => (typeof part === 'string' ? part : part?.text || ''))
+      .filter(Boolean)
+      .join('\n')
+  }
+  return ''
+}
+
+export function normalizeNotifyPayload(payload = {}) {
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) return {}
+  const normalized = { ...payload }
+
+  for (const [sourceKey, targetKey] of Object.entries(PAYLOAD_KEY_ALIASES)) {
+    assignAlias(normalized, payload, sourceKey, targetKey)
+  }
+
+  if (!normalized.prompt && Array.isArray(normalized.inputMessages)) {
+    normalized.prompt = normalized.inputMessages
+      .map(readMessageText)
+      .filter(Boolean)
+      .join('\n')
+      .trim()
+  }
+
+  return normalized
+}
+
+export { PAYLOAD_KEY_ALIASES }

package/scripts/notify.mjs

@@ -11,9 +11,11 @@ import { resolveNotificationSource } from './notify-source.mjs';
 import { buildCompactionContext, buildInjectContext, buildRouteInstruction, buildSemanticRouteInstruction, resolveCanonicalCommandSkill } from './notify-context.mjs';
 import { resolveNotifyHost, shouldIgnoreCodexNotifyClient } from './notify-events.mjs';
 import { runGateScript } from './notify-gates.mjs';
+import { normalizeNotifyPayload } from './notify-payload.mjs';
 import { handleRouteCommand, resolveBootstrapFile } from './notify-route.mjs';
 import { readSettings, readStdinJson, output, suppressedOutput, emptySuppress } from './notify-shared.mjs';
 import { clearRouteContext, getApplicableRouteContext, writeRouteContext } from './runtime-context.mjs';
+import { readRuntimeEvidence, writeRuntimeEvidence } from './runtime-artifacts.mjs';
 import { appendReplayEvent, startReplaySession } from './replay-state.mjs';
 import { clearTurnState, readTurnState } from './turn-state.mjs';
 import { getWorkflowRecommendation } from './workflow-state.mjs';
@@ -27,12 +29,15 @@ const CONFIG_FILE = join(homedir(), '.helloagents', 'helloagents.json');
 const cmd = process.argv[2] || '';
 const HOST = resolveNotifyHost(process.argv);
 const IS_GEMINI = HOST === 'gemini';
+const IS_CODEX = HOST === 'codex';
+const IS_SILENT = process.argv.includes('--silent');
 const EVENT_NAME = {
   SessionStart: 'SessionStart',
   UserPromptSubmit: IS_GEMINI ? 'BeforeAgent' : 'UserPromptSubmit',
   PreCompact: IS_GEMINI ? 'BeforeAgent' : 'PreCompact',
 };
 const RALPH_LOOP_ROUTE_COMMANDS = new Set(['verify', 'loop']);
+const CODEX_NATIVE_STOP_FILE = 'codex-native-stop.json';
 
 const playSound = (event) => _playSound(PKG_ROOT, event);
 const desktopNotify = (event, extra) => _desktopNotify(PKG_ROOT, event, extra);
@@ -52,6 +57,10 @@ function notifyByLevel(event, extra, settings = getSettings()) {
   }
 }
 
+function readPayloadFromStdin() {
+  return normalizeNotifyPayload(readStdinJson());
+}
+
 function buildNotifyExtra(payload = {}, options = {}) {
   const source = resolveNotificationSource({
     host: HOST,
@@ -130,6 +139,27 @@ function attachTurnSession(payload = {}, cwd = payload.cwd || process.cwd()) {
   return { ...payload, sessionId };
 }
 
+function getCodexTurnId(payload = {}) {
+  return String(payload.turnId || payload.turn_id || payload['turn-id'] || '').trim();
+}
+
+function markCodexNativeStopProcessed(cwd, payload = {}) {
+  if (!IS_CODEX) return;
+  const turnId = getCodexTurnId(payload);
+  if (!turnId) return;
+  writeRuntimeEvidence(cwd, CODEX_NATIVE_STOP_FILE, {
+    turnId,
+    updatedAt: new Date().toISOString(),
+  }, { payload });
+}
+
+function hasCodexNativeStopProcessed(cwd, payload = {}) {
+  const turnId = getCodexTurnId(payload);
+  if (!turnId) return false;
+  const evidence = readRuntimeEvidence(cwd, CODEX_NATIVE_STOP_FILE, { payload });
+  return evidence?.turnId === turnId;
+}
+
 function readMainTurnState(cwd, payload = {}) {
   const turnState = readTurnState(cwd, { payload });
   return turnState?.role === 'main' ? turnState : null;
@@ -145,7 +175,7 @@ function shouldProcessCloseout(turnState) {
 }
 
 function cmdPreCompact() {
-  const payload = readStdinJson();
+  const payload = readPayloadFromStdin();
   const cwd = payload.cwd || process.cwd();
   const settings = getSettings();
   const bootstrapFile = resolveBootstrapFile(cwd, settings, HOST);
@@ -170,37 +200,34 @@ function cmdPreCompact() {
 }
 
 function cmdRoute() {
-  const payload = readStdinJson();
+  const payload = readPayloadFromStdin();
   clearTurnState(payload.cwd || process.cwd(), { payload });
   handleRouteCommand({
     payload,
     host: HOST,
     pkgRoot: PKG_ROOT,
     settings: getSettings(),
-    buildRouteInstruction,
-    buildSemanticRouteInstruction,
+    buildRouteInstruction: IS_SILENT ? () => null : buildRouteInstruction,
+    buildSemanticRouteInstruction: IS_SILENT ? () => null : buildSemanticRouteInstruction,
     resolveCanonicalCommandSkill,
     writeRouteContext,
     clearRouteContext,
     appendReplayEvent,
     getWorkflowRecommendation,
-    suppress: (context) => suppressedOutput(EVENT_NAME.UserPromptSubmit, context),
+    suppress: (context) => IS_SILENT
+      ? emptySuppress()
+      : suppressedOutput(EVENT_NAME.UserPromptSubmit, context),
     emptySuppress,
   });
 }
 
 function cmdInject() {
-  const payload = readStdinJson();
+  const payload = readPayloadFromStdin();
   const source = payload.source || 'startup';
   const cwd = payload.cwd || process.cwd();
   const settings = getSettings();
   const bootstrapFile = resolveBootstrapFile(cwd, settings, HOST);
 
-  let bootstrap = '';
-  try {
-    bootstrap = readFileSync(join(PKG_ROOT, bootstrapFile), 'utf-8');
-  } catch {}
-
   startReplaySession(cwd, {
     host: HOST,
     source,
@@ -219,6 +246,17 @@ function cmdInject() {
       activatedProject: isProjectRuntimeActive(cwd),
     },
   });
+  clearRouteContext({ cwd, payload });
+  clearTurnState(cwd, { payload });
+  if (IS_SILENT) {
+    emptySuppress();
+    return;
+  }
+
+  let bootstrap = '';
+  try {
+    bootstrap = readFileSync(join(PKG_ROOT, bootstrapFile), 'utf-8');
+  } catch {}
   const context = buildInjectContext({
     source,
     bootstrap,
@@ -228,29 +266,34 @@ function cmdInject() {
     cwd,
     payload,
   });
-  clearRouteContext({ cwd, payload });
-  clearTurnState(cwd, { payload });
   suppressedOutput(EVENT_NAME.SessionStart, context || undefined);
 }
 
 function cmdStop() {
-  const payload = readStdinJson();
+  const payload = readPayloadFromStdin();
   const cwd = payload.cwd || process.cwd();
   const turnPayload = attachTurnSession(payload, cwd);
+  if (IS_CODEX && hasCodexNativeStopProcessed(cwd, turnPayload)) {
+    emptySuppress();
+    return;
+  }
   const turnState = readMainTurnState(cwd, turnPayload);
   if (runTurnStopGate(turnPayload)) {
     if (turnState && turnState.kind !== 'complete') consumeMainTurnState(cwd, turnState, turnPayload);
+    markCodexNativeStopProcessed(cwd, turnPayload);
     return;
   }
   const shouldProcess = shouldProcessCloseout(turnState);
   if (shouldProcess && runRalphLoop(turnPayload, { turnState })) {
     consumeMainTurnState(cwd, turnState, turnPayload);
     notifyByLevel('warning', buildNotifyExtra(payload));
+    markCodexNativeStopProcessed(cwd, turnPayload);
     return;
   }
   if (shouldProcess && runDeliveryGate(turnPayload)) {
     consumeMainTurnState(cwd, turnState, turnPayload);
     notifyByLevel('warning', buildNotifyExtra(payload));
+    markCodexNativeStopProcessed(cwd, turnPayload);
     return;
   }
 
@@ -260,6 +303,7 @@ function cmdStop() {
   }
   consumeMainTurnState(cwd, turnState, turnPayload);
   clearRouteContext({ cwd, payload: turnPayload });
+  markCodexNativeStopProcessed(cwd, turnPayload);
   emptySuppress();
 }
 
@@ -274,6 +318,7 @@ function cmdDesktop() {
 function cmdCodexNotify() {
   let data = {};
   try { data = JSON.parse(process.argv[3] || '{}'); } catch {}
+  data = normalizeNotifyPayload(data);
   const cwd = data.cwd || process.cwd();
   const turnPayload = attachTurnSession(data, cwd);
 
@@ -286,6 +331,7 @@ function cmdCodexNotify() {
     return;
   }
   if (type !== 'agent-turn-complete') return;
+  if (hasCodexNativeStopProcessed(cwd, turnPayload)) return;
 
   const turnState = readMainTurnState(cwd, turnPayload);
   if (runTurnStopGate(turnPayload)) {

package/scripts/runtime-artifacts.mjs

@@ -7,8 +7,9 @@ import {
   readSessionArtifact,
   writeSessionArtifact,
 } from './session-capsule.mjs'
+import { EVIDENCE_MAX_AGE_MS, LONG_RUNNING_TTL_HOURS } from './runtime-ttl.mjs'
 
-export const EVIDENCE_MAX_AGE_MS = 30 * 60 * 1000
+export { EVIDENCE_MAX_AGE_MS }
 
 function readGitDiffStat(cwd, args) {
   try {
@@ -23,16 +24,31 @@ function readGitDiffStat(cwd, args) {
   }
 }
 
+function readGitHead(cwd) {
+  try {
+    return execSync('git rev-parse HEAD', {
+      cwd,
+      encoding: 'utf-8',
+      timeout: 10_000,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim()
+  } catch {
+    return null
+  }
+}
+
 export function captureWorkspaceFingerprint(cwd) {
+  const head = readGitHead(cwd)
   const unstaged = readGitDiffStat(cwd, 'HEAD')
   const staged = readGitDiffStat(cwd, '--cached')
-  const available = unstaged !== null || staged !== null
+  const available = head !== null || unstaged !== null || staged !== null
 
   return {
     available,
+    head: head || '',
     unstaged: unstaged || '',
     staged: staged || '',
-    combined: `${unstaged || ''}\n---\n${staged || ''}`.trim(),
+    combined: [`HEAD:${head || ''}`, unstaged || '', staged || ''].join('\n---\n').trim(),
   }
 }
 
@@ -71,7 +87,7 @@ export function validateEvidenceTimestamp(evidence, now, label) {
       required: true,
       status: 'stale-time',
       evidence,
-      details: [`${label}超过 30 分钟`],
+      details: [`${label}超过 ${LONG_RUNNING_TTL_HOURS} 小时`],
     }
   }
   return null

package/scripts/runtime-context.mjs

@@ -1,4 +1,5 @@
 import { normalize, resolve } from 'node:path'
+import { createHash } from 'node:crypto'
 
 import {
   clearCapsuleSection,
@@ -6,13 +7,66 @@ import {
   readCapsuleSection,
   writeCapsuleSection,
 } from './session-capsule.mjs'
+import { ROUTE_CONTEXT_TTL_MS } from './runtime-ttl.mjs'
 
-const ROUTE_CONTEXT_TTL_MS = 30 * 60 * 1000
+export const UNBOUND_ROUTE_CONTEXT_TTL_MS = 10 * 60 * 1000
 
 function normalizePath(filePath = '') {
   return filePath ? normalize(resolve(filePath)) : ''
 }
 
+function normalizeIdentityValue(value) {
+  return String(value || '').trim()
+}
+
+function extractPayloadIdentity(payload = {}) {
+  return {
+    sessionId: normalizeIdentityValue(payload.sessionId || payload.session_id || payload['session-id']),
+    threadId: normalizeIdentityValue(payload.threadId || payload.thread_id || payload['thread-id']),
+    turnId: normalizeIdentityValue(payload.turnId || payload.turn_id || payload['turn-id']),
+    goalId: normalizeIdentityValue(payload.goalId || payload.goal_id || payload['goal-id']),
+  }
+}
+
+function hashPrompt(prompt = '') {
+  const text = String(prompt || '').trim()
+  if (!text) return ''
+  return createHash('sha1').update(text).digest('hex').slice(0, 16)
+}
+
+function routeSource(payload = {}) {
+  return normalizeIdentityValue(payload.hookEventName || payload.source || payload.type || '')
+}
+
+function hasTurnBinding(identity = {}) {
+  return Boolean(identity.turnId)
+}
+
+function hasAnyIdentity(identity = {}) {
+  return Boolean(identity.sessionId || identity.threadId || identity.turnId || identity.goalId)
+}
+
+function routeContextMaxAge(context = {}) {
+  return hasTurnBinding(context.identity) ? ROUTE_CONTEXT_TTL_MS : UNBOUND_ROUTE_CONTEXT_TTL_MS
+}
+
+function identityFieldsMatch(contextIdentity = {}, payloadIdentity = {}) {
+  for (const key of ['sessionId', 'threadId', 'turnId', 'goalId']) {
+    if (contextIdentity[key] && !payloadIdentity[key]) return false
+    if (contextIdentity[key] && payloadIdentity[key] && contextIdentity[key] !== payloadIdentity[key]) return false
+  }
+  return true
+}
+
+function payloadMatchesRouteContext(context = {}, payload = {}) {
+  if (!Object.prototype.hasOwnProperty.call(context, 'identity')) return false
+
+  const contextIdentity = context.identity || {}
+  if (!hasAnyIdentity(contextIdentity)) return true
+
+  return identityFieldsMatch(contextIdentity, extractPayloadIdentity(payload))
+}
+
 function resolvePayload(options = {}) {
   return options.payload && typeof options.payload === 'object' ? options.payload : options
 }
@@ -30,6 +84,9 @@ export function writeRouteContext({ cwd, skillName, sourceSkillName = skillName,
     skillName,
     sourceSkillName,
     zeroSideEffect: skillName === 'idea',
+    identity: extractPayloadIdentity(payload),
+    source: routeSource(payload),
+    promptHash: hashPrompt(payload.prompt),
     scope: scope.scope,
     key: scope.key,
     updatedAt: Date.now(),
@@ -44,7 +101,7 @@ export function readRouteContext(options = {}) {
   if (!context?.cwd || !context?.skillName || !context?.updatedAt) {
     return null
   }
-  if (Date.now() - context.updatedAt > ROUTE_CONTEXT_TTL_MS) {
+  if (Date.now() - context.updatedAt > routeContextMaxAge(context)) {
     clearRouteContext({ cwd, payload, env: options.env, ppid: options.ppid })
     return null
   }
@@ -58,6 +115,7 @@ export function readRouteContext(options = {}) {
 export function getApplicableRouteContext({ cwd = '', filePath = '', payload = {}, env, ppid } = {}) {
   const context = readRouteContext({ cwd, payload, env, ppid })
   if (!context) return null
+  if (!payloadMatchesRouteContext(context, payload)) return null
 
   const normalizedCwd = normalizePath(cwd)
   if (normalizedCwd && normalizedCwd === context.cwd) {

package/scripts/runtime-scope.mjs

@@ -5,6 +5,7 @@ import { dirname, join, normalize, resolve } from 'node:path'
 import { homedir } from 'node:os'
 
 import { resolveSessionToken } from './session-token.mjs'
+import { USER_RUNTIME_MAX_AGE_MS } from './runtime-ttl.mjs'
 
 export const PROJECT_DIR_NAME = '.helloagents'
 export const PROJECT_SESSIONS_DIR_NAME = 'sessions'
@@ -13,7 +14,7 @@ export const CAPSULE_FILE_NAME = 'capsule.json'
 export const EVENTS_FILE_NAME = 'events.jsonl'
 export const DEFAULT_STATE_SESSION_TOKEN = 'default'
 export const USER_RUNTIME_DIR_NAME = 'runtime'
-export const USER_RUNTIME_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000
+export { USER_RUNTIME_MAX_AGE_MS }
 
 function normalizePath(filePath = '') {
   return filePath ? normalize(resolve(filePath)) : ''

package/scripts/runtime-ttl.mjs

@@ -0,0 +1,7 @@
+export const LONG_RUNNING_TTL_HOURS = 720
+export const LONG_RUNNING_TTL_MS = LONG_RUNNING_TTL_HOURS * 60 * 60 * 1000
+
+export const ROUTE_CONTEXT_TTL_MS = LONG_RUNNING_TTL_MS
+export const TURN_STATE_TTL_MS = LONG_RUNNING_TTL_MS
+export const EVIDENCE_MAX_AGE_MS = LONG_RUNNING_TTL_MS
+export const USER_RUNTIME_MAX_AGE_MS = LONG_RUNNING_TTL_MS

package/scripts/session-token.mjs

@@ -7,6 +7,7 @@ const PAYLOAD_SESSION_KEYS = [
   'conversation',
   'threadId',
   'thread_id',
+  'thread-id',
   'thread',
   'windowId',
   'window_id',

package/scripts/turn-state.mjs

@@ -10,8 +10,8 @@ import {
   readCapsuleSection,
   writeCapsuleSection,
 } from './session-capsule.mjs'
+import { TURN_STATE_TTL_MS } from './runtime-ttl.mjs'
 
-const TURN_STATE_TTL_MS = 30 * 60 * 1000
 const VALID_KINDS = new Set(['complete', 'waiting', 'blocked', 'progress'])
 const VALID_ROLES = new Set(['main', 'subagent'])
 const VALID_REASON_CATEGORIES = new Set([

package/scripts/workflow-plan-files.mjs

@@ -23,7 +23,7 @@ const PLAN_TEMPLATE_MARKERS = {
   'tasks.md': [
     /# \{项目\/功能名称\} — 任务分解/,
     /\[按执行顺序排列，每个任务独立可验证\]/,
-    /- \[ \] 任务1：描述/,
+    /- \[ \] 任务1（AFK\/HITL）：端到端行为描述/,
   ],
 }
 

package/skills/commands/auto/SKILL.md

@@ -15,7 +15,7 @@ Trigger: ~auto <任务描述>
 - `T3` 高风险或不可逆操作默认不直接进入 `~build`；优先先走 `~plan` 或 `~prd`，纯审查/纯验证请求才可先进入 `~verify`
 - 主路径一旦确定，立即读取对应 command skill，并在阶段完成后继续执行后续阶段，避免同一任务重复探索或重复等待
 - 选路不替代授权；涉及外部副作用或高风险不可逆操作时，仍遵守 bootstrap 的阻塞判定与确认规则
-- 用户显式使用 `~auto`，表示已授权在当前任务边界内沿选定主路径持续执行；`~plan` / `~prd` 作为中间阶段时，不再额外询问“是否开始执行”，除非仍有真实阻塞
+- 用户显式使用 `~auto`，表示已授权在当前任务边界内沿选定主路径持续执行；若本轮运行在 Codex `/goal` 下，`/goal` 只提供长程续跑与预算，`~auto` 仍按方案包、`state_path` 与验证契约推进；`~plan` / `~prd` 作为中间阶段时，不再额外询问“是否开始执行”，除非仍有真实阻塞；不得把 `🔄 下一步` 当作阶段交接或继续执行占位
 - 优先消费当前上下文中已注入的 ROUTE / TIER、当前工作流约束与项目状态；不要在 `~auto` 内另建一套关键词路由表
 
 ## 流程
@@ -27,6 +27,7 @@ Trigger: ~auto <任务描述>
   - 活跃方案包不完整或缺少任务清单 → 先 `~plan`
   - 活跃方案包仍在执行 → 先 `~build`，完成当前实现后再 `~verify`
   - 活跃方案包已闭合 → 先 `~verify` 或收尾
+  - Codex active goal 已关联方案包 → 按 `tasks.md` 未完成 AFK 项、`contract.json` 与 `state_path` 确定主路径，不把 goal 目标原文替代方案包
 - 只有当用户明确要求换方向、重做方案，或现有方案已失效时，才偏离当前推荐重新规划
 
 ### 1. 选路
@@ -64,9 +65,10 @@ Trigger: ~auto <任务描述>
 - 若主路径是 `~prd` → PRD / 任务 / 契约写入后，若当前任务来自 `~auto` 且未命中阻塞判定，按当前结果继续进入 `~build`，必要时先补一轮轻量 `~plan`
 - 若主路径是 `~verify` → 完成审查 / 验证 / 收尾后结束
 - 若主路径是 `~idea`，且用户本意就是探索/比较，则在探索输出后结束；若探索后已有明确方向且当前任务仍要求写文件或改代码，则继续进入 `~plan` 或 `~build`
+- 若 Codex active goal 的目标已满足 → 仍先完成 `~verify` 与 HelloAGENTS 收尾，再标记 goal complete；未满足时继续下一项可执行 AFK 任务
 
 ### 5. 何时允许停下
 
 - 仅在 bootstrap 的阻塞判定成立时停下：真实歧义、缺必需信息/文件/凭据、未授权外部副作用、高风险或不可逆操作
 - 不得把 `~plan` / `~prd` 中“是否进入执行”的默认询问原样带入 `~auto` 流程
-- 不得把“给出方案”“给出任务列表”“给出建议下一步”当作 `~auto` 的默认完成态；用户显式要求 `~auto` 时，默认目标是把当前任务推进到可交付完成
+- 不得把“给出方案”“给出任务列表”“未执行修改”“等待下一步确认”“给出建议下一步”当作 `~auto` 的默认完成态；用户显式要求 `~auto` 时，默认目标是把当前任务推进到可交付完成

package/skills/commands/build/SKILL.md

@@ -20,7 +20,7 @@ Trigger: ~build [description]
 
 ### 1. 恢复与定位
 
-- 优先按当前已加载 bootstrap 的“.helloagents/ 文件读取优先级”恢复当前任务；若当前消息明确要继续上次任务，或会话刚经历恢复 / 压缩，先读取 `state_path`，再用当前用户消息、活跃方案包 / PRD 与代码事实确认当前任务
+- 优先按当前已加载 bootstrap 的“.helloagents/ 文件读取优先级”恢复当前任务；若当前消息明确要继续上次任务、会话刚经历恢复 / 压缩，或本轮运行在 Codex active goal 下，先读取 `state_path`，再用当前用户消息、活跃方案包 / PRD 与代码事实确认当前任务
 - 若存在最近的活跃方案包，读取对应的：
   - `requirements.md`
   - `plan.md`
@@ -28,6 +28,7 @@ Trigger: ~build [description]
   - `contract.json`
   - 实现时优先把 `tasks.md` 中每个任务的“完成标准”当作本轮实现约束，不要只按任务标题猜测范围
   - `contract.json` 存在时，优先按其中的 `verifyMode`、`reviewerFocus`、`testerFocus` 理解后续验证边界
+- 若本轮运行在 Codex active goal 下，按 `tasks.md` 未完成项、`contract.json` 与 `state_path` 恢复实现位置；不要自动创建新 goal，也不要把 goal 目标原文替代方案包
 - 若当前上下文中已注入“当前工作流约束”或“当前建议下一命令”，先服从它；只有推荐仍为 `~build`，或用户明确提出新增实现范围时，才继续 `~build`
 - 其余项目知识库与相关代码文件，按 bootstrap 的项目上下文规则按需读取
 - 若任务涉及 UI，按以下优先级读取并遵循：当前活跃 `plan.md` / PRD 中的 UI 决策 > 逻辑 `.helloagents/DESIGN.md`（实际路径按当前项目存储模式解析） > `hello-ui` 通用规则
@@ -63,5 +64,6 @@ Trigger: ~build [description]
 
 - 有方案包时，只同步本次实现直接影响的任务状态；未完成项保持打开
 - 当前实现已闭合、且需要进入交付或收尾时，转入 `~verify`
+- 若 Codex active goal 仍有未完成 AFK 任务，继续下一项可执行任务；若目标已满足，先转入 `~verify` 与 HelloAGENTS 收尾，再标记 goal complete
 - 状态文件、知识库、`CHANGELOG.md`、modules 文档与归档边界，按当前已加载 bootstrap 的 VERIFY / CONSOLIDATE 规则执行
 - 不在 `~build` 内把仍未闭合的方案包整体报告为已完成

package/skills/commands/loop/SKILL.md

@@ -37,8 +37,9 @@ iteration	commit	metric	delta	guard	status	description
 
 `~loop` 的八阶段循环是统一执行流程（ROUTE/TIER→SPEC→PLAN→BUILD→VERIFY→CONSOLIDATE）在迭代优化场景下的特化形式。每轮迭代的“修改”阶段遵循已标记的 hello-* 质量技能规范，“验证”阶段遵循 hello-verify 的验证规范。
 执行 `~loop` 时，涉及公共阶段边界、阻塞判定与收尾要求的部分，仍按当前已加载 bootstrap 执行；本 skill 负责补充 loop 场景的迭代顺序与回滚规则。
+若本轮运行在 Codex `/goal` 下，`/goal` 只作为外层长程续跑与预算控制；`~loop` 仍负责指标、守卫、实验提交、keep/revert、results log、`state_path` 与收尾验证，不把 `/goal` 当成循环逻辑本身。
 
-除非达到迭代上限或命中阻塞判定，否则继续执行，不额外询问是否继续。
+除非达到迭代上限或命中阻塞判定，否则继续执行，不额外询问是否继续，也不把 `🔄 下一步` 当作单轮结果或继续执行占位。
 每轮迭代必须完整走完以下八个阶段：
 
 ### 第 1 阶段：回顾
@@ -91,6 +92,7 @@ iteration	commit	metric	delta	guard	status	description
 - 最有效的 3 个改进
 - results log 路径
 - 重写 `state_path`：将“主线目标”保留为本次优化目标，“正在做什么”更新为已完成，保留最终结论摘要，清空阻塞项，并给出可立即执行的下一步（如继续优化、停止、切换目标）
+- 若 Codex `/goal` 处于 active 且目标已达成，完成 HelloAGENTS 验证和收尾后再标记 goal complete；不得因达到预算或单轮结束而标记 complete
 
 ## 安全规则
 - 使用 `git revert`（保留历史）而非 `git reset --hard`（丢失历史）

package/skills/commands/plan/SKILL.md

@@ -14,7 +14,7 @@ Trigger: ~plan [description]
 - 在用户确认方案之前，禁止编写任何实现代码、创建任何实现文件、或执行任何实现操作
 - 需求澄清阶段不读取实现类技能（hello-ui / hello-test / hello-verify 等），需求明确后再按需读取
 - 方案必须整理为可执行产物，不停留在泛化建议
-- 若当前任务来自 `~auto`，则“开始执行”视为已包含在 `~auto` 授权内；方案包写入后默认继续执行，只有命中阻塞判定时才停下
+- 若当前任务来自 `~auto`，则“开始执行”视为已包含在 `~auto` 授权内；方案包写入后默认继续执行，只有命中阻塞判定时才停下。`~design` 是 `~plan` 的兼容别名，只有在 `~auto` 内触发其语义时才默认继续进入 `~build`
 - 涉及 UI 时，当前方案包中的 UI 决策优先于 `.helloagents/DESIGN.md`；`.helloagents/DESIGN.md`（按当前项目存储模式解析）优先于通用 UI 规则
 
 ## 流程
@@ -87,6 +87,7 @@ Trigger: ~plan [description]
 - 只有在 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` 的自然语言说明里猜验证主路径
+- 在 `tasks.md` 中保留 “Codex /goal 执行入口”，内容必须引用当前方案包路径、AFK/HITL 边界、完成前验证与 HelloAGENTS 收尾；不要把普通 PRD 原文当作 `/goal` 目标
 - 涉及 UI 的项目：生成或更新 `.helloagents/DESIGN.md`（按当前项目存储模式解析）；若原文件不存在，先按模板建立最小设计契约，再写入已确认的稳定设计决策
 - 重写 `state_path`，其中“主线目标”写本次规划要完成的目标，不保留其他任务的内容
 
@@ -101,6 +102,7 @@ Trigger: ~plan [description]
 
 如果用户已明确表示继续执行，则视为授权成立，可直接继续执行。
 如果当前任务来自 `~auto`，且方案包已足够支撑实现、也未命中阻塞判定，则默认直接进入 `~build`，不再追加一次“是否开始执行”的询问。
+如果当前任务是显式 `~plan` 或 `~design`，且尚未获得执行授权，收尾必须使用 `❓等待输入`，下一步写清待确认的执行动作。
 
 ## 方案包要求
 
@@ -109,6 +111,7 @@ Trigger: ~plan [description]
 - 每个任务标注 `AFK` 或 `HITL`：`AFK` 表示代理可独立完成，`HITL` 表示需要用户决策、外部凭据、人工视觉确认或手动验收
 - 明确文件路径、预期变更、完成标准、验证方式与依赖关系
 - 每个任务可独立验证；厚任务必须拆成更薄的可验收切片
+- “Codex /goal 执行入口”只作为长程执行提示，不计入任务列表；入口必须让 Codex 按已拆好的 `tasks.md` 执行，而不是直接消费未拆分需求文档
 
 方案包中的 `contract.json` 必须满足：
 - `verifyMode` 只能是 `test-first` 或 `review-first`

package/skills/commands/prd/SKILL.md

@@ -103,6 +103,7 @@ c. AI 总结该维度的决策结果，进入下一个维度
 - 创建 `.helloagents/plans/YYYYMMDDHHMM_{feature}/prd/`（按当前项目存储模式解析）
 - 按 templates/plans/prd/ 的模板格式，仅写入用户未跳过的维度文件
 - 生成 tasks.md（每个任务默认是端到端垂直切片，标注 AFK / HITL、依赖、具体文件路径、预期变更、完成标准与验证方式；任务独立可验证）
+- 在 `tasks.md` 中保留 “Codex /goal 执行入口”，让 Codex 按已拆分任务、验收边界和 `contract.json` 执行；不要把完整 PRD 原文直接当作 `/goal` 目标
 - 生成 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`，不要只把验证路径留在自然语言说明里

package/skills/commands/test/SKILL.md

@@ -11,6 +11,7 @@ Trigger: ~test [scope]
 1. 确定测试范围：
    - 无参数：为最近变更的文件编写测试
    - 指定文件/模块：为指定范围编写测试
+   - Codex active goal 下无参数：从 `tasks.md` 未完成项、`contract.json` 与 `state_path` 推导本轮测试范围
 2. 按 hello-* 技能查找路径读取 hello-test SKILL.md，按其 TDD 规范和边界用例要求编写测试
 3. 运行测试确认全部通过
-4. 报告覆盖情况和遗漏
+4. 同步直接相关的任务状态，报告覆盖情况和遗漏；测试通过只作为 goal 交付证据，不直接标记 goal complete

package/skills/commands/verify/SKILL.md

@@ -13,6 +13,7 @@ Trigger: ~verify [scope]
    - 即使命令通过，也不能越过当前方案包边界：不完整方案包不能视为可信交付记录，未闭合方案包不能被整体报告为已完成
    - 当推荐路径已进入 `~verify` / 收尾时，优先把本命令用于审查、验真和交付收尾
    - 若当前存在活跃方案包，先读取 `requirements.md`、`plan.md`、`tasks.md`、`contract.json`，把它们当作本轮验证契约；不要只看命令结果
+   - 若本轮运行在 Codex active goal 下，按 active goal 关联方案包和 `state_path` 复核范围；`/goal` 只负责续跑，不改变验证契约
    - 若 `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. 先决定验证分流：
@@ -30,6 +31,7 @@ Trigger: ~verify [scope]
    - 逐个运行所有检测到的命令
    - 收集每个命令的输出和退出码
    - 对照当前契约逐项核对：requirements 是否覆盖、tasks 中每项“完成标准”是否满足、`plan.md` 中风险与设计约束是否被验证、`contract.json` 中声明的 `verifyMode` / reviewer / tester 关注边界是否已被覆盖
+   - 若 Codex active goal 存在，还要确认 `tasks.md` 的 AFK/HITL 边界：仍有可执行 AFK 项时，不进入 complete；只在目标、任务、验证和收尾都闭合后标记 goal complete
    - 若 `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. 汇总报告：
@@ -41,4 +43,4 @@ Trigger: ~verify [scope]
 
 ## 失败处理
 - 有失败 → 逐个修复，修复后重新运行对应审查或验证
-- 全部通过 → 进入当前已加载 bootstrap 的 CONSOLIDATE 收尾，再按交付边界报告完成
+- 全部通过 → 进入当前已加载 bootstrap 的 CONSOLIDATE 收尾；若 Codex active goal 的目标也已满足，再标记 goal complete，并按交付边界报告完成

package/skills/helloagents/SKILL.md

@@ -5,7 +5,7 @@ description: 按任务类型适用 — 建立质量驱动工作流，通过技
 
 # HelloAGENTS
 
-主代理触发或读取任意 skill 时，只有在该条消息是本轮最终收尾消息时，才按当前已加载 bootstrap 规则包装 HelloAGENTS 外层输出格式；任何 skill 若在本轮明确要求输出停顿、确认或总结，对应消息也必须同时满足相同条件。
+主代理触发或读取任意 skill 时，只有在该条消息是本轮最终收尾消息时，才按当前已加载 bootstrap 规则包装 HelloAGENTS 外层输出格式；任何 skill 若在本轮明确要求输出停顿、确认或总结，对应消息也必须同时满足相同条件。最终收尾中的 `🔄 下一步` 写真实动作，不写当前状态；等待用户授权时按等待输入收尾，已获授权且可继续执行时不得收尾。
 子代理只豁免路由与收尾要求，直接执行任务；安全、质量、验证和失败处理规则仍持续生效，且不得包装 HelloAGENTS 外层输出格式。所有流式内容、进度或状态汇报、中间文本，以及任何仍将继续执行的文本，都不得触发外层格式。
 只有运行时必须识别本轮“完成 / 等待输入 / 阻塞”时，主代理才写 turn-state；普通问候、普通问答、T0 只读分析和一次性解释不调用。必须调用场景：显式 `~auto` / `~loop`、非只读任务完成验证并进入收尾、需要 delivery gate / Ralph Loop / closeout evidence、需要等待或阻塞且运行时必须识别状态、已进入项目连续流程或方案包闭环。首选 `helloagents-turn-state write --kind complete --role main`；等待或阻塞时写 `kind=waiting` / `kind=blocked`，并同时写 `reasonCategory` 与 `reason`。显式 `~auto` / `~loop` 下，还必须写入 `blocker.target`、`blocker.evidence`、`blocker.requiredAction`。不要查找、读取或拼接 `turn-state.mjs` 源码路径。子代理不得写 turn-state。
 

package/templates/plans/tasks.md

@@ -11,5 +11,8 @@
 - [ ] 任务2（AFK/HITL）：端到端行为描述（依赖：任务1；涉及文件：...；预期变更：...；完成标准：...；验证方式：...）
 - [ ] 任务3（AFK/HITL）：端到端行为描述（依赖：...；涉及文件：...；预期变更：...；完成标准：...；验证方式：...）
 
+## Codex /goal 执行入口
+[可选。需要长程执行时复制到 Codex：/goal 按 `.helloagents/plans/{feature}/tasks.md` 执行本方案；遵守 `requirements.md`、`plan.md`、`contract.json`。按顺序完成所有 AFK 任务；HITL 仅在缺少外部决策、凭据或人工验收时暂停。不要把完整 PRD 原文直接当作 `/goal` 目标。完成前更新 tasks.md、运行契约验证并完成 HelloAGENTS 收尾。]
+
 ## 进度
 [执行过程中更新]