@fitlab-ai/agent-infra 0.11.10 → 0.11.12

package/lib/task/platform-operation-journal.ts

@@ -33,7 +33,18 @@ type PlatformPullRequestIntent = Readonly<{
   closingIssue?: boolean;
 }>;
 type PlatformIssueCreateIntent = Readonly<{ title: string; bodyDigest: string }>;
-type PlatformPullRequestSummaryIntent = Readonly<{ body: string; changeReportFile: string }>;
+type PlatformPullRequestSummaryManualValidationIntent = Readonly<{
+  phase: 'pending' | 'final';
+  transactionId: string;
+  receiptDigest?: string;
+  prHeadSha?: string;
+  authority?: 'coordinator';
+}>;
+type PlatformPullRequestSummaryIntent = Readonly<{
+  body: string;
+  changeReportFile: string;
+  manualValidation?: PlatformPullRequestSummaryManualValidationIntent;
+}>;
 type PlatformPullRequestReviewIntent = Readonly<{
   prNumber: string;
   resource: ResourceIdentity;
@@ -147,6 +158,22 @@ function parseJournal(file: string, taskId: string): PlatformOperationJournal {
         ? !item.pullRequestSummary || typeof item.pullRequestSummary.body !== 'string'
           || !item.pullRequestSummary.body.trim() || typeof item.pullRequestSummary.changeReportFile !== 'string'
           || !item.pullRequestSummary.changeReportFile.trim()
+          || (item.pullRequestSummary.manualValidation !== undefined && (
+            !item.pullRequestSummary.manualValidation
+            || typeof item.pullRequestSummary.manualValidation !== 'object'
+            || Array.isArray(item.pullRequestSummary.manualValidation)
+            || !['pending', 'final'].includes(item.pullRequestSummary.manualValidation.phase)
+            || typeof item.pullRequestSummary.manualValidation.transactionId !== 'string'
+            || !item.pullRequestSummary.manualValidation.transactionId.trim()
+            || (item.pullRequestSummary.manualValidation.receiptDigest !== undefined && !/^[a-f0-9]{64}$/u.test(item.pullRequestSummary.manualValidation.receiptDigest))
+            || (item.pullRequestSummary.manualValidation.prHeadSha !== undefined && !/^[a-f0-9]{40}$/u.test(item.pullRequestSummary.manualValidation.prHeadSha))
+            || (item.pullRequestSummary.manualValidation.authority !== undefined && item.pullRequestSummary.manualValidation.authority !== 'coordinator')
+            || (item.pullRequestSummary.manualValidation.phase === 'final' && (
+              !/^[a-f0-9]{64}$/u.test(item.pullRequestSummary.manualValidation.receiptDigest ?? '')
+              || !/^[a-f0-9]{40}$/u.test(item.pullRequestSummary.manualValidation.prHeadSha ?? '')
+              || item.pullRequestSummary.manualValidation.authority !== 'coordinator'
+            ))
+          ))
         : item.pullRequestSummary !== undefined)
       || (item.kind === 'pull-request-review'
         ? !item.pullRequestReview || typeof item.pullRequestReview.prNumber !== 'string'
@@ -234,4 +261,4 @@ function readPlatformOperationJournal(taskRef: string, cwd?: string): PlatformOp
 }
 
 export { JOURNAL_FILE as PLATFORM_OPERATION_JOURNAL_FILE, operationId, recordPlatformOperation, readPlatformOperationJournal };
-export type { PlatformIssueCreateIntent, PlatformIssueMetadataIntent, PlatformOperation, PlatformOperationJournal, PlatformOperationKind, PlatformOperationState, PlatformPullRequestIntent, PlatformPullRequestReviewIntent, PlatformPullRequestSummaryIntent, RecordOperationInput };
+export type { PlatformIssueCreateIntent, PlatformIssueMetadataIntent, PlatformOperation, PlatformOperationJournal, PlatformOperationKind, PlatformOperationState, PlatformPullRequestIntent, PlatformPullRequestReviewIntent, PlatformPullRequestSummaryIntent, PlatformPullRequestSummaryManualValidationIntent, RecordOperationInput };

package/lib/task/platform-operation-recovery.ts

@@ -187,6 +187,14 @@ async function replayPullRequestSummary(taskId: string, operation: ReturnType<ty
   let identity;
   try { identity = parseResourceIdentity(JSON.parse(operation.target), 'queued pull-request summary identity'); }
   catch { return platformResult('failed', { error: { code: 'PLATFORM_OPERATION_PAYLOAD_INVALID', message: 'Queued pull-request summary identity is invalid', retryable: false } }); }
+  const summary = operation.pullRequestSummary;
+  if (!summary) return platformResult('blocked', { error: {
+    code: 'PLATFORM_OPERATION_PAYLOAD_INVALID', message: 'Pull-request summary recovery content is missing', retryable: false
+  } });
+  const manualValidationHeading = /^###\s+(?:⏳\s+(?:Manual Validation Pending|人工验证待收尾)|✅\s+(?:Manual Validation Passed|人工验证已通过))\s*$/mu.test(summary.body);
+  if (manualValidationHeading && !summary.manualValidation) return platformResult('blocked', { error: {
+    code: 'MANUAL_VALIDATION_TRANSACTION_REQUIRED', message: 'Queued manual-validation summary has no persisted transaction context', retryable: false
+  } });
   const resolved = await resolvePlatformProviderContext({ cwd, client });
   if (!resolved.ok) return resolved.context;
   const listed = resolved.value.provider.comments?.list
@@ -198,12 +206,9 @@ async function replayPullRequestSummary(taskId: string, operation: ReturnType<ty
   if (summaries.length > 1) return platformResult('blocked', { error: {
     code: 'PR_SUMMARY_MARKER_AMBIGUOUS', message: 'Multiple pull-request comments contain the queued summary marker', retryable: false
   } });
-  if (summaries.length === 1 && createHash('sha256').update(normalizeCommentContent(summaries[0]!.body)).digest('hex') === operation.expectedDigest) {
+  if (!summary.manualValidation && summaries.length === 1 && createHash('sha256').update(normalizeCommentContent(summaries[0]!.body)).digest('hex') === operation.expectedDigest) {
     return platformResult('no-op');
   }
-  if (!operation.pullRequestSummary) return platformResult('blocked', { error: {
-    code: 'PLATFORM_OPERATION_PAYLOAD_INVALID', message: 'Pull-request summary recovery content is missing', retryable: false
-  } });
   const bound = await inspectPlatformPullRequest(taskId, { cwd, client });
   if (!bound.pullRequest || !resourceIdentityEquals(bound.pullRequest.identity, identity)) return platformResult('blocked', { error: bound.error ?? {
     code: 'PLATFORM_OPERATION_IDENTITY_MISMATCH', message: 'Bound pull request differs from the queued summary target', retryable: false
@@ -212,8 +217,9 @@ async function replayPullRequestSummary(taskId: string, operation: ReturnType<ty
     agent,
     cwd,
     client,
-    body: operation.pullRequestSummary.body,
-    changeReportFile: operation.pullRequestSummary.changeReportFile,
+    body: summary.body,
+    changeReportFile: summary.changeReportFile,
+    ...(summary.manualValidation ? { manualValidation: summary.manualValidation } : {}),
     primaryResult: 'no_op',
     strict: true,
     skipQueue: true,

package/lib/task/resolve-ref.ts

@@ -139,13 +139,18 @@ function enumerateTaskDirs(repoRoot: string): { taskId: string; taskDir: string
  */
 function enumerateAllTaskDirs(repoRoot: string): { taskId: string; taskDir: string; state: TaskWorkspaceState }[] {
   const out: { taskId: string; taskDir: string; state: TaskWorkspaceState }[] = [];
-  const seen = new Set<string>();
+  const seen = new Map<string, string>();
   const add = (taskId: string, taskDir: string, state: TaskWorkspaceState) => {
     if (!TASK_ID_RE.test(taskId)) return;
     const stat = fs.lstatSync(taskDir);
     if (!stat.isDirectory() || stat.isSymbolicLink() || !fs.existsSync(path.join(taskDir, 'task.md'))) return;
-    if (seen.has(taskId)) throw new Error(`duplicate task identity: ${taskId}`);
-    seen.add(taskId);
+    const canonicalDir = fs.realpathSync.native(taskDir);
+    const previousDir = seen.get(taskId);
+    if (previousDir !== undefined) {
+      if (previousDir === canonicalDir) return;
+      throw new Error(`duplicate task identity: ${taskId}`);
+    }
+    seen.set(taskId, canonicalDir);
     out.push({ taskId, taskDir, state });
   };
 

package/lib/task/runtime-paths.ts

@@ -0,0 +1,12 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { resolveTaskRef } from './resolve-ref.ts';
+
+export function resolveTaskRuntimeRoot(
+  taskRef: string,
+  options: Readonly<{ repoRoot?: string }> = {}
+): string {
+  const resolved = resolveTaskRef(taskRef, options);
+  if (!resolved.ok) throw new Error(`${resolved.code}: ${resolved.message}`);
+  return path.join(fs.realpathSync.native(resolved.taskDir), '.runtime');
+}

package/lib/task/verification-engine.ts

@@ -43,6 +43,7 @@ import { manualValidationFinalSummaryProjectionMatches } from "./manual-validati
 import { readManualValidationCompletion } from "./manual-validation-completion.ts";
 import { sha256File } from "./artifact-receipts.ts";
 import { inspectArtifactDirectory } from "./artifact-lifecycle.ts";
+import { getAgentClientAdapter } from "../agent-clients/registry.ts";
 import { parseArtifactName } from "./artifact-name.ts";
 import { summaryCommentState } from "../platform/pr-summary.ts";
 import { taskIssueIdentity } from "../platform/task-identities.ts";
@@ -147,7 +148,7 @@ async function runCheck(type: any, context: any, shared: any): Promise<any> {
 }
 
 function checkOrchestrationState({ taskDir }: any): any {
-  const file = path.join(taskDir, 'orchestration.json');
+  const file = path.join(taskDir, '.runtime', 'orchestration.json');
   const stat = safeStat(file);
   if (!stat?.isFile()) return failResult('orchestration-state', 'orchestration.json is missing');
   let run: OrchestrationRun | null;
@@ -160,6 +161,8 @@ function checkOrchestrationState({ taskDir }: any): any {
   if (!run || !['paused', 'completed'].includes(run.status)) {
     return failResult('orchestration-state', `Expected paused or completed run, received '${run?.status ?? 'missing'}'`);
   }
+  const adapterEvidenceError = validateAdapterReceiptEvidence(run);
+  if (adapterEvidenceError) return failResult('orchestration-state', adapterEvidenceError);
   if (run.status === 'paused' && (!run.pause?.code || !run.pause?.message)) {
     return failResult('orchestration-state', 'Paused run requires a stable pause code and message');
   }
@@ -215,8 +218,19 @@ function validateCleanCompletionEvidence(run: OrchestrationRun): string | null {
   return null;
 }
 
+function validateAdapterReceiptEvidence(run: OrchestrationRun): string | null {
+  const receipts = [...run.receipts, ...(run.pendingDelegation ? [run.pendingDelegation] : [])];
+  for (const receipt of receipts) {
+    const validate = getAgentClientAdapter(receipt.client).orchestrationAdapter?.validateReceiptEvidence;
+    if (validate && !validate(receipt)) {
+      return `Receipt '${receipt.id}' has invalid evidence from its agent adapter`;
+    }
+  }
+  return null;
+}
+
 function checkOrchestrationEvidence({ taskDir }: any): any {
-  const file = path.join(taskDir, 'orchestration.json');
+  const file = path.join(taskDir, '.runtime', 'orchestration.json');
   const stat = safeStat(file);
   if (!stat?.isFile()) return failResult('orchestration-evidence', 'orchestration.json is missing');
   let run: OrchestrationRun | null;
@@ -227,6 +241,8 @@ function checkOrchestrationEvidence({ taskDir }: any): any {
     return failResult('orchestration-evidence', `Invalid orchestration.json: ${message}`);
   }
   if (!run) return failResult('orchestration-evidence', 'orchestration.json is missing');
+  const adapterEvidenceError = validateAdapterReceiptEvidence(run);
+  if (adapterEvidenceError) return failResult('orchestration-evidence', adapterEvidenceError);
   // readRun validates the persisted schema, receipt identities and client provenance.
   const policy = run.modelPolicy;
   if (run.completionEvidence != null) {
@@ -249,20 +265,22 @@ function checkOrchestrationEvidence({ taskDir }: any): any {
     }
     const activated = ['activated', 'stage-completed', 'sealed', 'consumed'].includes(receipt.status);
     if (activated) {
-      const isClaudeCode = receipt.client === 'claude-code';
-      if (!isClaudeCode) {
+      const evidencePolicy = getAgentClientAdapter(receipt.client).delegationEvidence;
+      if (evidencePolicy.actualModelRequired !== false) {
         if (!exactText(receipt.actualModel)) {
           return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' has no host-observed actual model`);
         }
+      }
+      if (evidencePolicy.actualReasoningEffortRequired !== false) {
         if (!exactText(receipt.actualReasoningEffort)) {
           return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' has no host-observed actual reasoning effort`);
         }
       }
-      if (!isClaudeCode && receipt.spawnMode !== 'fresh') {
+      if (evidencePolicy.spawnModeRequired !== false && receipt.spawnMode !== 'fresh') {
         return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' has invalid fresh delegation identity`);
       }
       if (receipt.actualModel != null && receipt.actualModel !== receipt.requestedModel) {
-        if (!isClaudeCode && !exactText(receipt.modelFallbackReason)) {
+        if (evidencePolicy.fallbackReasonRequired !== false && !exactText(receipt.modelFallbackReason)) {
           return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' model fallback is not justified`);
         }
       }
@@ -273,7 +291,7 @@ function checkOrchestrationEvidence({ taskDir }: any): any {
         return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' has an unrelated model fallback reason`);
       }
       if (receipt.actualReasoningEffort != null && receipt.actualReasoningEffort !== receipt.requestedReasoningEffort) {
-        if (!isClaudeCode && !exactText(receipt.reasoningEffortFallbackReason)) {
+        if (evidencePolicy.fallbackReasonRequired !== false && !exactText(receipt.reasoningEffortFallbackReason)) {
           return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' reasoning-effort fallback is not justified`);
         }
       }
@@ -790,7 +808,6 @@ function checkActivityLog({ taskDir, config, skillName, artifactFile }: any): an
   const entries = section.entries;
   if (entries.length === 0) return failResult("activity-log", "Activity Log has no entries");
 
-  let previousTimestamp = "";
   let latestAction = "";
   let latestTimestamp = "";
   const doneActions: string[] = [];
@@ -798,14 +815,8 @@ function checkActivityLog({ taskDir, config, skillName, artifactFile }: any): an
   for (const entry of entries) {
     if (!entry.note.trim()) return failResult("activity-log", "Activity Log entry note is required");
     const { time: timestamp, step: action } = entry;
-    if (previousTimestamp && timestamp < previousTimestamp) {
-      return failResult("activity-log", "Activity Log timestamps are not in ascending order");
-    }
-
-    previousTimestamp = timestamp;
-    // Ascending order is checked over every entry, but a `[started]` marker is
-    // not a terminal action: keep latestAction/latestTimestamp on the most
-    // recent done entry so expected_action_pattern sees it.
+    // A `[started]` marker is not a terminal action: keep latestAction/latestTimestamp
+    // on the most recent done entry so expected_action_pattern sees it.
     if (!ACTIVITY_LOG_STARTED_RE.test(action)) {
       latestTimestamp = timestamp;
       latestAction = action;

package/lib/task/workspace-snapshot.ts

@@ -67,7 +67,7 @@ function taskFileFingerprints(stateRoot: string, taskId: string | null): TaskFil
       return;
     }
     if (!stat.isFile() && !stat.isSymbolicLink()) return;
-    if (relative.startsWith('.agents/workspace/active/') && path.posix.basename(relative) === 'orchestration.json') return;
+    if (/^\.agents\/workspace\/(?:active|blocked|completed)\/TASK-[0-9]{8}-[0-9]{6}\/\.runtime\/orchestration\.json$/u.test(relative)) return;
     const content = stat.isSymbolicLink()
       ? Buffer.from(fs.readlinkSync(absolute))
       : fs.readFileSync(absolute);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fitlab-ai/agent-infra",
-  "version": "0.11.10",
+  "version": "0.11.12",
   "description": "Bootstrap tool for AI multi-tool collaboration infrastructure — works with Claude Code, Codex, Antigravity CLI, and OpenCode",
   "license": "MIT",
   "type": "module",

package/templates/.agents/hooks/lifecycle-delegation.js

@@ -16,28 +16,6 @@ function internalCliInvocation(args) {
   return { command: 'agent-infra-internal', commandArgs: args, shell: process.platform === 'win32' };
 }
 
-function findCapabilityRef(value, depth = 0) {
-  if (depth > 5 || value == null) return '';
-  if (typeof value === 'string') {
-    const match = /agent-infra-codex-capability:([A-Za-z0-9_-]{20,})/.exec(value);
-    return match?.[1] || '';
-  }
-  if (Array.isArray(value)) {
-    for (const entry of value) {
-      const found = findCapabilityRef(entry, depth + 1);
-      if (found) return found;
-    }
-    return '';
-  }
-  if (typeof value === 'object') {
-    for (const entry of Object.values(value)) {
-      const found = findCapabilityRef(entry, depth + 1);
-      if (found) return found;
-    }
-  }
-  return '';
-}
-
 let input = '';
 process.stdin.setEncoding('utf8');
 process.stdin.on('data', (chunk) => {
@@ -77,11 +55,10 @@ process.stdin.on('end', () => {
       process.exit(1);
     }
     const managedAgent = /^agent-infra-lifecycle-(executor|reviewer)$/.test(String(nativeAgent || ''));
-    const capabilityRef = hook === 'post-tool' ? findCapabilityRef(toolResponse) : '';
     const parentReconcile = hook === 'post-tool'
       && toolName === 'collaborationwait_agent'
       && toolResponse.timed_out !== true;
-    if (!managedAgent && !parentReconcile && !capabilityRef) process.exit(0);
+    if (!managedAgent && !parentReconcile) process.exit(0);
     const hookDefinitionHash = createHash('sha256').update(readFileSync(codexHooks)).digest('hex');
     const normalized = {
       sessionId: String(event.session_id || ''),
@@ -96,7 +73,6 @@ process.stdin.on('end', () => {
       taskName: String(toolInput.task_name || ''),
       transcriptPath: String(event.transcript_path || '')
     };
-    if (capabilityRef) normalized.capabilityRef = capabilityRef;
     const args = ['codex-lifecycle', 'hook-event', '--event', hook, '--bridge', 'true'];
     try {
       const { command, commandArgs, shell } = internalCliInvocation(args);

package/templates/.agents/rules/README.en.md

@@ -8,8 +8,8 @@ so you can quickly find "which ones to read" without opening each file.
 
 ## General Principles
 
-- [`no-mid-flow-questions.md`](no-mid-flow-questions.md) — Silence during SKILL runs: no user questions by default, plus the exceptions the rule lists.
-- [`next-step-output.md`](next-step-output.md) — "Next step" output rules: task short-id rendering and the `Completed at` trailer.
+- [`no-mid-flow-questions.md`](no-mid-flow-questions.md) — Question boundaries, error diagnosis order, and autonomous recovery during SKILL runs.
+- [`next-step-output.md`](next-step-output.md) — "Next step" output rules: task short-id rendering, pending human decisions, and workflow warnings.
 - [`version-stamp.md`](version-stamp.md) — How and when to stamp `agent_infra_version`.
 - [`debugging-guide.md`](debugging-guide.md) — Structured debugging flow: gather evidence → form hypothesis → verify hypothesis → fix the root cause; no blind patch-and-retry.
 - [`compatibility-policy.md`](compatibility-policy.md) — Compatibility by exception: admission evidence, implementation boundaries, exit conditions, and lifecycle review requirements.

package/templates/.agents/rules/README.zh-CN.md

@@ -7,8 +7,8 @@
 
 ## 通用准则
 
-- [`no-mid-flow-questions.md`](no-mid-flow-questions.md) — SKILL 执行期禁言：默认不向用户提问，及规则列明的例外。
-- [`next-step-output.md`](next-step-output.md) — 「下一步」输出规则：任务短号渲染与 `Completed at` 收尾行。
+- [`no-mid-flow-questions.md`](no-mid-flow-questions.md) — SKILL 执行期提问边界、错误诊断顺序和自主恢复原则。
+- [`next-step-output.md`](next-step-output.md) — 「下一步」输出规则：任务短号、人工裁决提示与工作流告警。
 - [`version-stamp.md`](version-stamp.md) — `agent_infra_version` 版本戳的取值命令与写入时机。
 - [`debugging-guide.md`](debugging-guide.md) — 结构化调试流程：收集证据→形成假设→验证假设→修复根因，禁止盲目改代码重试。
 - [`compatibility-policy.md`](compatibility-policy.md) — 兼容性默认关闭：准入证据、实现边界、退出条件与生命周期审查要求。

package/templates/.agents/rules/issue-sync.en.md

@@ -35,7 +35,7 @@ The task comment synchronizes only a deterministic current-task projection. Proc
 
 Recovery comments use `recovery-action`, `recovery-prepare`, and `recovery-commit` markers with a stable recovery id and a body file. Task sync publishes prepare, action, a task snapshot that is written and re-read, and then commit. Replaying identical content is a no-op; conflicting immutable content fails with `RECOVERY_IMMUTABLE_CONFLICT`. Restore accepts only an author-consistent, complete, phase/digest/marker-valid transaction bound to the current task comment body SHA-256.
 
-PR event `in:` synchronization uses `agent-infra-internal platform-pr sync-in-labels --pr <N> [--cwd <path>]`. PR files are the event evidence; a unique closing Issue is written and re-read before the PR. Zero or multiple closing Issues update only the PR and return `degraded`; unknown side effects or failed convergence return `blocked` with `IN_LABEL_SYNC_PARTIAL`.
+PR event `in:` synchronization uses `agent-infra-internal platform-pr sync-in-labels --pr <token> [--cwd <path>]`. The shared entry turns the token into a resource identity using the provider declaration, then passes that identity to the provider; the provider interprets the token for its platform. PR files are the event evidence; a unique closing Issue is written and re-read before the PR. Zero or multiple closing Issues update only the PR and return `degraded`; unknown side effects or failed convergence return `blocked` with `IN_LABEL_SYNC_PARTIAL`.
 
 `planned|applied|no-op|degraded` exit 0; `failed` exits 1; `blocked` exits 2.
 

package/templates/.agents/rules/issue-sync.zh-CN.md

@@ -76,7 +76,7 @@ agent-infra-internal platform-issue sync {task-id} --agent {standard-agent-token
 
 status labels 始终至多一个；关闭后不保留 status label。`in:` labels 只从项目允许映射与仓库实际 labels 交集产生。需求复选框以 task.md 原文为身份，歧义时 fail closed。
 
-PR event 的 `in:` 同步使用 `agent-infra-internal platform-pr sync-in-labels --pr <N> [--cwd <path>]`。PR files 是事件证据；唯一 closing Issue 按 Issue→PR 顺序写入并复读，零或多个 closing Issue 只写 PR 并返回 `degraded`。写入后副作用不明或复读未收敛必须返回 `blocked` 与 `IN_LABEL_SYNC_PARTIAL`。
+PR event 的 `in:` 同步使用 `agent-infra-internal platform-pr sync-in-labels --pr <token> [--cwd <path>]`。共享入口按 provider 声明把 token 转成资源 identity，再将 identity 交给 provider；token 的平台语义由 provider 处理。PR files 是事件证据；唯一 closing Issue 按 Issue→PR 顺序写入并复读，零或多个 closing Issue 只写 PR 并返回 `degraded`。写入后副作用不明或复读未收敛必须返回 `blocked` 与 `IN_LABEL_SYNC_PARTIAL`。
 
 ## 补发
 

package/templates/.agents/rules/next-step-output.en.md

@@ -1,11 +1,10 @@
 # Next-Step Output Rule
 
-This file defines four **independent** rules for a skill's "notify-user / Next steps" output (the 3rd applies to review-* only); read this file before rendering the final output and apply whichever rules apply:
+This file defines three **independent** rules for a skill's "notify-user / Next steps" output (the 2nd applies to review-* only); read this file before rendering the final output and apply whichever rules apply:
 
 1. **Next-step output structure**: how "Next steps" commands and the "Task info" block present the task ID (placeholders / short-id lookup / fallback).
-2. **Agent output trailing line (Completed at)**: the **very last line** of user-facing output, **independent of the "Next steps" block**, applying to normal / error / early-return paths alike.
-3. **Pending human-decision pre-block**: applies only to `review-analysis` / `review-plan` / `review-code` when this stage has pending rulings (`{h} > 0`) — expand the pending items before the "Next steps" commands and prompt to resolve them first.
-4. **Workflow Warnings output block**: applies when task.md has `status=open` rows in `## Workflow Warnings` — print the warning summary after all normal information and "Next steps" commands, and before `Completed at`.
+2. **Pending human-decision pre-block**: applies only to `review-analysis` / `review-plan` / `review-code` when this stage has pending rulings (`{h} > 0`) — expand the pending items before the "Next steps" commands and prompt to resolve them first.
+3. **Workflow Warnings output block**: applies when task.md has `status=open` rows in `## Workflow Warnings` — print the warning summary after all normal information and "Next steps" commands.
 
 ## Placeholder semantics
 
@@ -34,7 +33,7 @@ agent-infra-internal agent-client next-steps \
 - Pass the next skill name for the already-selected scenario. Include `--task-ref` only when that command needs a task reference.
 - Include `--version` only for a versioned release command. It must start with a digit and satisfy `semver.valid(raw) === raw`; never pass an action, complete command, shell fragment, whitespace, or a `v` / `V` / `=` prefix.
 - The helper lists enabled built-in clients, followed by selected sandbox custom tools with a valid `invoke` field in `sandbox.tools.ids` order.
-- Insert non-empty stdout verbatim at `{next-step-commands}` below the current "Next steps" heading. When stdout is empty, omit the client command block while still rendering reminders, warnings, and `Completed at`.
+- Insert non-empty stdout verbatim at `{next-step-commands}` below the current "Next steps" heading. When stdout is empty, omit the client command block while still rendering reminders and warnings.
 - If the helper writes stderr or exits non-zero, use the current skill's error path and stop; never fall back to a hard-coded client table.
 - A complex skill selects one scenario first and invokes the helper once for that scenario; it must not pre-render every branch.
 
@@ -69,21 +68,9 @@ process.stdout.write(hit?hit[0]:full);
 
 Short ids are always rendered as zero-padded bare digits `NN`. The removed `#NN` syntax must neither be generated nor accepted, avoiding bash comment interpretation.
 
-## Agent output trailing line (Completed at)
-
-This section is a standalone rule, **co-equal with the next-step output structure** and **not part of the "Next steps" block**. Every skill that renders user-facing output must append the completion-time line as the **very last line** of that output — including **complete-task, which renders no next-step commands**, and **error / early-return paths** where a precondition is unmet. This lets users scanning across tmux windows tell at a glance which agent finished most recently:
-
-```text
-Completed at: YYYY-MM-DD HH:mm:ss
-```
-
-- Value command (local timezone, no offset): `date "+%Y-%m-%d %H:%M:%S"`
-- Position: it must be the last line of the entire user-facing output, after all "Next steps" commands. If a scenario has a conditional reminder line after the commands (e.g. the manual-validation reminder), the completion line goes after that reminder.
-- This line is for terminal scanning only; it is never written to any artifact file or Issue/PR comment. The single source of truth for completion time remains the Activity Log in task.md.
-
 ## Workflow Warnings Output Block
 
-If the current task's `## Workflow Warnings` / `## 工作流告警` table has any `status=open` row, the skill's final user output must append a summary block after all normal information and "Next steps" commands, and before `Completed at`. When no open warning exists, do not render this block.
+If the current task's `## Workflow Warnings` / `## 工作流告警` table has any `status=open` row, the skill's final user output must append a summary block after all normal information and "Next steps" commands. When no open warning exists, do not render this block.
 
 Format:
 
@@ -96,7 +83,7 @@ Use `[ACTION REQUIRED]` when any open row has `severity=ACTION_REQUIRED`; otherw
 
 ## Pending human-decision pre-block (review-* only, when {h} > 0)
 
-This section is a **third standalone rule, co-equal with the two above**, used only by the "notify-user / report conclusion" step of `review-analysis` / `review-plan` / `review-code`.
+This section is the **second independent rule**, used only by the "notify-user / report conclusion" step of `review-analysis` / `review-plan` / `review-code`.
 
 `{h}` has the same meaning as the count line in each review skill's `reference/output-templates.md`: the number of rows in task.md `## 审查分歧账本` (Review Disagreement Ledger) for **this stage** (`stage ∈ {analysis|plan|code}`) whose `status = needs-human-decision` — **pending items only, excluding rows already `human-decided`**.
 

package/templates/.agents/rules/next-step-output.zh-CN.md

@@ -1,11 +1,10 @@
 # 下一步输出规则
 
-本文件定义 skill「告知用户 / 下一步」输出的四类**相互独立**的规则（第 3 类仅 review-* 适用）；渲染最终输出前先读取本文件并落实其中适用的规则：
+本文件定义 skill「告知用户 / 下一步」输出的三类**相互独立**的规则（第 2 类仅 review-* 适用）；渲染最终输出前先读取本文件并落实其中适用的规则：
 
 1. **下一步输出结构**：「下一步」命令与「任务信息」段如何呈现任务 ID 形态（占位符 / 取短号 / 回退）。
-2. **Agent 输出收尾行（Completed at）**：面向用户输出的**绝对最后一行**，**独立于「下一步」块**，正常 / 错误 / 早退路径都适用。
-3. **人工裁决待办前置块**：仅 `review-analysis` / `review-plan` / `review-code`，且本阶段存在待裁决项（`{h} > 0`）时适用——在「下一步」命令前展开待裁决项并提示先完成裁决。
-4. **Workflow Warnings 输出块**：当前 task.md 存在 `status=open` 的 `## 工作流告警` 行时适用——在所有常规信息和「下一步」命令之后、`Completed at` 之前输出告警摘要。
+2. **人工裁决待办前置块**：仅 `review-analysis` / `review-plan` / `review-code`，且本阶段存在待裁决项（`{h} > 0`）时适用——在「下一步」命令前展开待裁决项并提示先完成裁决。
+3. **Workflow Warnings 输出块**：当前 task.md 存在 `status=open` 的 `## 工作流告警` 行时适用——在所有常规信息和「下一步」命令之后输出告警摘要。
 
 ## 占位符语义
 
@@ -34,7 +33,7 @@ agent-infra-internal agent-client next-steps \
 - 静态传入当前已选场景的下一 skill 名；只有命令需要任务引用时才传 `--task-ref`。
 - 只有版本化发布命令需要版本时才传 `--version`；值必须是以数字开头且 `semver.valid(raw) === raw` 的规范 SemVer。不得传 action、完整命令、shell 片段、空白或 `v` / `V` / `=` 前缀。
 - helper 展示 `.agents/.airc.json` 中 `agentClients` 已启用的内建客户端，并按 `sandbox.tools.ids` 顺序追加具有有效 `invoke` 的已选自定义沙箱工具。
-- 将非空 stdout 原样放入当前“下一步”标题后的 `{next-step-commands}`；stdout 为空时省略整个客户端命令块，但继续输出提醒、告警和 `Completed at`。
+- 将非空 stdout 原样放入当前“下一步”标题后的 `{next-step-commands}`；stdout 为空时省略整个客户端命令块，但继续输出提醒和告警。
 - helper 写 stderr 或返回非零时，按当前 skill 的错误路径报告并停止；禁止回退到硬编码客户端表。
 - 复杂 skill 先选定唯一场景，再只为该场景调用一次 helper，不得提前渲染所有分支。
 
@@ -69,21 +68,9 @@ process.stdout.write(hit?hit[0]:full);
 
 短号统一渲染为零填充裸数字 `NN`。已移除的 `#NN` 语法不得生成或接受，避免 bash 将其解释为注释。
 
-## Agent 输出收尾行（Completed at）
-
-本节是与「下一步输出结构」**并列的独立规则**，不隶属于「下一步」块。任何向用户渲染输出的 skill 都必须在面向用户输出的**绝对最后一行**追加完成时间收尾行——包括**声明「不渲染下一步命令」的 complete-task**，以及前置条件未满足而提前 return 的**错误 / 早退路径**。便于用户在 tmux 多窗口扫视时一眼判断各 Agent 的完成先后：
-
-```text
-Completed at: YYYY-MM-DD HH:mm:ss
-```
-
-- 取值命令（本地时区、不带偏移）：`date "+%Y-%m-%d %H:%M:%S"`
-- 位置：必须是整段面向用户输出的最后一行，排在所有「下一步」命令之后。若某场景在命令之后还有条件性提醒行（如 manual-validation 提醒），收尾行排在该提醒行之后。
-- 该行只用于终端扫视，不写入任何产物文件或 Issue/PR 评论；完成时刻的单一事实源仍是 task.md 的 Activity Log。
-
 ## Workflow Warnings 输出块
 
-若当前任务的 `## 工作流告警` / `## Workflow Warnings` 表中存在 `status=open` 行，skill 最终输出必须在所有常规信息和「下一步」命令之后、`Completed at` 之前追加摘要块；无 open 告警时不输出本块。
+若当前任务的 `## 工作流告警` / `## Workflow Warnings` 表中存在 `status=open` 行，skill 最终输出必须在所有常规信息和「下一步」命令之后追加摘要块；无 open 告警时不输出本块。
 
 格式：
 
@@ -96,7 +83,7 @@ Completed at: YYYY-MM-DD HH:mm:ss
 
 ## 人工裁决待办前置块（review-* 专用，{h} > 0 时）
 
-本节是与上面两类规则**并列的第三类独立规则**，仅 `review-analysis` / `review-plan` / `review-code` 的「向用户汇报结论」步骤使用。
+本节是与下一步输出结构并列的第二类规则，仅 `review-analysis` / `review-plan` / `review-code` 的「向用户汇报结论」步骤使用。
 
 `{h}` 含义与各 review 技能 `reference/output-templates.md` 计数行一致：task.md `## 审查分歧账本` 中**本阶段**（`stage ∈ {analysis|plan|code}`）`status = needs-human-decision` 的行数——**只含待裁决项，不含已 `human-decided`**。
 

package/templates/.agents/rules/no-mid-flow-questions.en.md

@@ -57,6 +57,15 @@ SKILLs currently covered by this exemption:
 
 - `run-task`: may collect only the atomic model policy explicitly required by core
 
+### Exemption 6: Necessary facts or security accountability that cannot be inferred
+
+Only when the executor has checked the current task, configuration, code, Git, and platform records and still cannot safely infer a user-specific fact or security-accountability information required to proceed may it ask the user for that missing information. Keep the question limited to the missing fact itself. Do not ask for ordinary implementation preferences that existing evidence can resolve, and do not turn an exhausted recovery budget into general permission to ask.
+
+SKILLs currently covered by this exemption:
+
+- `create-pr`: may request the target base branch when it cannot be derived from user input, configuration, Git history, or PR facts
+- `close-codescan` and `close-dependabot`: may request the reason or accountability statement required for a security-alert disposition; the final dismissal still follows its dedicated confirmation gate
+
 ## No-Mid-Flow-Questions Clause (default behavior)
 
 For every SKILL execution context not covered by any exemption above, the default behavior is:
@@ -98,6 +107,16 @@ If a key decision needs human judgment during execution, follow the rule above a
 
 The `run-task` orchestrator may continue after a child skill artifact only when core mechanical state permits it; this does not bypass human decisions. When core reports a human decision, manual validation, or another stable pause condition, the orchestrator must stop without asking mid-flow or approving it itself.
 
+## Error diagnosis and recovery order
+
+When a tool, gate, platform, or local operation fails, read the complete error and structured result first. Determine state from the operation identity, acceptance status, side effects, receipt, and explicit retryability. Do not infer network failure, non-execution, or a need for user intervention from an exit code, wording, or temporary lack of output alone.
+
+1. Correct Agent-generated formatting/schema errors explicitly rejected by a validator; preserve domain meaning, revalidate with the same validator, then retry within bounds.
+2. For operations explicitly known not to have executed and marked retryable, fix the diagnosed cause first and preserve the idempotency identity required by the contract; obey existing no-progress, repeated-diagnostic, and self-healing budgets.
+3. For accepted operations, unknown outcomes, or possible side effects, retain the original request identity and receipt and follow typed recovery to inspect or recover; do not change the payload, issue another business write, or claim success.
+4. For temporary blocks, record the exact state and recovery condition. Continue read-only, local, or other independent work that does not depend on the blocked operation. A blocked step remains incomplete and must not be treated as success.
+5. Ask for user action only when a safety boundary cannot be verified, recovery requires user-specific facts or authorization, user workspace changes cannot be safely preserved, or the allowed recovery budget is exhausted with no safe independent work remaining; necessary facts or security-accountability information follow the scope of Exemption 6. Continue to honor domain hard gates for security, permissions, human review, manual validation, explicit publish authorization, and delivery stages.
+
 ## Anchor Location
 
 This rule's sole global anchor lives in the project-level AGENTS.md "AI Behavior Principles" preamble, which every AI tool loads. Individual SKILL.md files no longer reference this rule, so no per-skill duplicate bullet needs to be maintained.

package/templates/.agents/rules/no-mid-flow-questions.zh-CN.md

@@ -57,6 +57,15 @@
 
 - `run-task`：仅补齐核心明确要求的原子模型策略
 
+### 例外 6：无法推导的必要事实或安全责任信息
+
+仅当已检查当前任务、配置、代码、Git 与平台记录后，仍无法安全推导继续执行所必需的用户专属事实或安全责任信息时，才可请求用户提供缺失内容。问题必须限定在缺失事实本身；不得询问可由现有证据决定的普通实现偏好，也不得把恢复预算耗尽泛化为提问许可。
+
+当前归入本例外的 SKILL：
+
+- `create-pr`：目标 base 无法从用户输入、配置、Git 历史或 PR 事实推导时，可请求目标分支
+- `close-codescan`、`close-dependabot`：安全告警处置需要用户提供理由或责任说明时，可请求该说明；最终关闭仍遵守专属确认门禁
+
 ## 禁言条款（默认行为）
 
 不属于上述任一例外的所有 SKILL 执行场景，遵循以下默认行为：
@@ -98,6 +107,16 @@
 
 `run-task` 总控可以在子技能产出后依据核心机械状态继续到下一阶段；这不构成绕过人工裁决。只要核心返回人工裁决、人工验证或其他稳定暂停条件，总控必须停止，不能向用户中途提问，也不能自行批准。
 
+## 错误诊断与恢复顺序
+
+遇到工具、校验、平台或本地操作失败时，先读取完整错误与结构化结果，再按当前操作的身份、是否接纳、已发生副作用、receipt 和明确的 retryability 判断状态。不得仅凭退出码、错误措辞或暂时无输出推断网络故障、操作未执行或需要用户介入。
+
+1. 修复由 Agent 自身生成且被 validator 明确拒绝的格式/schema 错误；保留领域含义，使用同一 validator 验证后再有限重试。
+2. 对明确未执行且允许重试的操作，先处理已诊断的根因，保留合同要求的幂等身份；遵守现有无进展、重复诊断和自愈预算。
+3. 对已接纳、结果未知或有副作用的操作，保留原请求身份和 receipt，按 typed recovery 检查或恢复；不得改 payload、另发业务写入或宣称成功。
+4. 对暂时阻塞，记录准确状态和恢复条件；继续不依赖该阻塞的只读、本地或其他独立工作。阻塞的步骤仍未完成，不得降格为成功。
+5. 仅当安全边界无法验证、恢复需要用户独有事实/授权、用户工作区改动无法安全保留，或允许的恢复预算耗尽且无安全的独立工作时，才请求用户动作；必要事实或安全责任信息遵循例外 6 的范围。遇到安全、权限、人工审查、人工验证、显式发布授权和交付阶段门时继续遵守其专属硬门禁。
+
 ## 锚点位置
 
 本规则的唯一全局锚点在项目级 AGENTS.md 的「AI 行为准则」preamble，所有 AI 工具加载 AGENTS.md 时即可见。各 SKILL.md 不再单独引用本规则，避免在每个 SKILL 顶部维护重复 bullet。

package/templates/.agents/rules/review-handshake.en.md

@@ -20,6 +20,8 @@ For each finding in the latest `review-*`, first Read/Grep the cited `file:line`
 | `refuted` | After verification, judged invalid / hallucinated / based on a wrong `file:line` | counter-evidence (`file:line` or raw command output); awaits reviewer confirmation |
 | `cannot-judge` | Insufficient evidence to decide | the verification path attempted; handed to reviewer/human |
 
+`finding-respond --round` is the finding's handshake round, independent of the current code/plan/analysis artifact round. The executor reads each finding's current ledger `round` from `task-ledger stage-status --stage {stage}` and submits current value plus one; different findings may require different response rounds.
+
 ## Reviewer hand-back duty (`review-*` skills, when re-reviewing the executor response)
 
 After the executor gives `adjusted` / `refuted` / `cannot-judge`, the reviewer must respond per item — never re-reading the original finding nor ignoring the hand-back:
@@ -64,6 +66,7 @@ The single source of truth for disagreement state is the fixed `## 审查分歧
 - **Terminal set (gate passes)**: `{confirmed, closed, human-decided}`; everything else is blocking.
 - **Same-round fix-and-close**: only when the reviewer fixes a `minor` finding during the current review round may `finding-review` move that row directly from `open` to `closed`. This transition does not increment `round`, and `evidence` must point to the fix in the current review artifact; it does not apply to `blocker` or `major` findings.
 - **Severity is independent from advancement**: `blocker` / `major` / `minor` express impact only. Every formal finding blocks approval until terminal. After all writes, review verdicts, event counts, and next steps must be derived from `task-ledger stage-status --stage {stage}`.
+- **Evidence correction on open findings**: `finding-review` may keep a finding `open` while updating its evidence anchor to correct or refine an unresolved report reference; this does not change the finding round or terminal state.
 - **Non-blocking advisories**: only future optimizations that do not affect the current artifact's completeness, correctness, or acceptance. Advisories stay in a separate report section and never enter this ledger, finding counts, or verdict; manual-validation remains a separate category.
 - **Write responsibility**: callers submit structured intents only; they do not scan ids, assemble table rows, or decide mechanical transitions. `review-*` uses `agent-infra-internal task-ledger {task-id} finding-upsert|finding-review ...`; `*-task` uses `finding-respond ...`; `ai decide` applies human rulings atomically. The core validates and commits each intent through one task write.
 - **Backward compatible**: when task.md has no such section the gate treats it as no open disagreements and passes.

package/templates/.agents/rules/review-handshake.zh-CN.md

@@ -20,6 +20,8 @@
 | `refuted` | 核实后判定不成立 / 幻觉 / 基于错误 `file:line` | 反证（`file:line` 或命令原文）；待检视方确认 |
 | `cannot-judge` | 证据不足，无法判断 | 已尝试的核实路径；交检视方/人工 |
 
+`finding-respond --round` 使用 finding 自身的握手轮次，不使用当前 code/plan/analysis artifact 的轮次。执行方先从 `task-ledger stage-status --stage {stage}` 读取该 finding 当前账本 `round`，响应时传入当前值加一；不同 finding 的响应轮次可能不同。
+
 ## 检视方回交义务（`review-*` 技能，对执行方响应复核时）
 
 执行方给出 `adjusted` / `refuted` / `cannot-judge` 后，检视方必须逐条回应，不得复读原意见或无视：
@@ -64,6 +66,7 @@
 - **终态集合（gate 放行）**：`{confirmed, closed, human-decided}`；其余为阻塞态。
 - **同轮 fix-and-close**：仅当检视方在当前审查轮当场修复 `minor` finding 时，可通过 `finding-review` 将该行从 `open` 直接置为 `closed`。此转换不增加 `round`，`evidence` 必须指向当前 review 产物中的修复证据；`blocker` / `major` 不适用。
 - **severity 与推进解耦**：`blocker` / `major` / `minor` 只表示影响大小。任何正式 finding 只要尚未进入终态就阻止当前阶段通过；review 结论、事件计数与下一步必须在全部写入后通过 `task-ledger stage-status --stage {stage}` 从同一语义导出。
+- **open finding 证据修正**：`finding-review` 可保持 finding 为 `open` 并更新证据锚点，以修正或细化未解决意见的报告引用；该操作不改变 finding 轮次或终态。
 - **非阻塞 advisory**：仅限不影响当前产物完整性、正确性和验收的后续优化。advisory 只写入报告的独立段落，不进入本账本、不进入 finding 计数、不影响 verdict；manual-validation 仍是独立分类。
 - **写入责任**：调用方只提交结构化意图，不扫描编号、不拼表格行、不自行判断机械状态迁移。`review-*` 用 `agent-infra-internal task-ledger {task-id} finding-upsert|finding-review ...`；`*-task` 用 `finding-respond ...`；人工裁决由 `ai decide` 原子完成。核心统一校验并通过一次任务写入提交。
 - **向后兼容**：task.md 无此段时，gate 视为无未决分歧而放行。

package/templates/.agents/rules/task-management.en.md

@@ -38,7 +38,7 @@ The seven internal commands (`task-event` / `task-lifecycle` / `task-finalizatio
 
 ## Platform Results and Skill Blocking Boundaries
 
-A `blocked` platform write means only that the operation is unfinished. Whether the skill stops depends on its delivery goal. The typed core handles write queuing, recovery, and idempotency; skills consume structured results and do not replay writes themselves.
+A `blocked` platform write or `task-verify` result means that operation or gate is incomplete; it does not by itself mean a network interruption, that the user must intervene, or success. Skills inspect the structured summary, preserve the blocked state and recovery condition, and continue only independent work. They do not replay platform writes; typed core owns their queuing, recovery, and idempotency.
 
 - `import-issue`: stop importing when the source Issue cannot be read.
 - `create-pr`: stop the creation flow when the PR was not created or its identity cannot be confirmed.

package/templates/.agents/rules/task-management.zh-CN.md

@@ -38,7 +38,7 @@
 
 ## 平台结果与技能阻塞边界
 
-平台写入返回 `blocked` 只表示该操作尚未完成；技能是否停止由当前技能的交付目标决定。平台写入的排队、恢复和幂等由 typed core 执行，技能只消费结构化结果，不自行重放。
+平台写入或 `task-verify` 返回 `blocked` 表示对应操作/校验尚未完成，不表示网络中断、用户必须介入或成功。技能按当前交付目标读取结构化摘要，保留 blocked 与恢复条件；只继续不依赖该阻塞的独立工作，不自行重放平台写入。平台写入的排队、恢复和幂等由 typed core 执行。
 
 - `import-issue`：源 Issue 读取失败时停止导入。
 - `create-pr`：PR 未创建或无法确认其身份时停止创建流程。