@fitlab-ai/agent-infra 0.11.12 → 0.11.13

package/lib/task/orchestration.ts

@@ -8,7 +8,7 @@ import { validateCurrentTaskContract } from './current-contract.ts';
 import { parseReviewSummary } from './review-artifacts.ts';
 import { LEDGER_SECTION_MISSING_CODE, LEDGER_SECTION_MISSING_MESSAGE, parseLedgerDocument, summarizeLedgerStage, validateLedgerRows } from './ledger.ts';
 import type { LedgerDocument } from './ledger.ts';
-import { resolveTaskRef } from './resolve-ref.ts';
+import { resolveTaskRef, TASK_ID_RE } from './resolve-ref.ts';
 import {
   activateDelegation,
   abortActivatedDelegation,
@@ -75,7 +75,6 @@ type ClientCapabilityRecovery = Readonly<{
     baselineEmpty: true;
     receiptCount: 0;
     pendingDelegation: false;
-    commitAuthorizationUnused: true;
     completionEvidenceAbsent: true;
   }>;
   resultingStatus: 'running';
@@ -105,7 +104,6 @@ type OrchestrationRun = Readonly<{
   pendingDelegation: DelegationReceipt | null;
   receipts: readonly DelegationReceipt[];
   pause: Readonly<{ code: string; message: string; recoverable: boolean }> | null;
-  commitAuthorization: Readonly<{ issuedAt: string | null; consumedAt: string | null }>;
   completionEvidence: CleanCompletionEvidence | null;
   createdAt: string;
   updatedAt: string;
@@ -249,7 +247,7 @@ function isModelPolicy(value: unknown): value is OrchestrationModelPolicy {
 
 const RECOVERY_GUARD_KEYS = [
   'stepCount', 'nextStage', 'baselineEmpty', 'receiptCount', 'pendingDelegation',
-  'commitAuthorizationUnused', 'completionEvidenceAbsent'
+  'completionEvidenceAbsent'
 ] as const;
 
 function isRecovery(value: unknown): value is OrchestrationRecovery {
@@ -269,7 +267,6 @@ function isRecovery(value: unknown): value is OrchestrationRecovery {
     && guards.baselineEmpty === true
     && guards.receiptCount === 0
     && guards.pendingDelegation === false
-    && guards.commitAuthorizationUnused === true
     && guards.completionEvidenceAbsent === true
     && value.resultingStatus === 'running';
 }
@@ -291,7 +288,7 @@ export function isCompletionEvidence(value: unknown): value is CleanCompletionEv
 const ORCHESTRATION_RUN_KEYS = [
   'taskId', 'runId', 'status', 'nextStage', 'stepCount', 'maxSteps', 'modelPolicy',
   'modelPolicySource', 'recoveryHistory', 'baseline', 'pendingDelegation', 'receipts',
-  'pause', 'commitAuthorization', 'completionEvidence', 'createdAt', 'updatedAt'
+  'pause', 'completionEvidence', 'createdAt', 'updatedAt'
 ] as const;
 
 function orchestrationStateReasonCodes(value: unknown): string[] {
@@ -313,12 +310,6 @@ function orchestrationStateReasonCodes(value: unknown): string[] {
   if (!(record.pendingDelegation === null || isDelegationReceipt(record.pendingDelegation))) reasons.push('pendingDelegation');
   if (!Array.isArray(record.receipts) || !record.receipts.every(isDelegationReceipt)) reasons.push('receipts');
   if (!(record.pause === null || isPause(record.pause))) reasons.push('pause');
-  if (!hasExactKeys(record.commitAuthorization, ['issuedAt', 'consumedAt'])) {
-    reasons.push('commitAuthorization');
-  } else {
-    if (!nullableText(record.commitAuthorization.issuedAt)) reasons.push('commitAuthorization.issuedAt');
-    if (!nullableText(record.commitAuthorization.consumedAt)) reasons.push('commitAuthorization.consumedAt');
-  }
   if (!(record.completionEvidence === null || isCompletionEvidence(record.completionEvidence))) reasons.push('completionEvidence');
   if (!exactText(record.createdAt)) reasons.push('createdAt');
   if (!exactText(record.updatedAt)) reasons.push('updatedAt');
@@ -584,8 +575,6 @@ function canRecoverUnsupportedClientPause(run: OrchestrationRun): boolean {
     && run.baseline === ''
     && run.pendingDelegation === null
     && run.receipts.length === 0
-    && run.commitAuthorization?.issuedAt === null
-    && run.commitAuthorization?.consumedAt === null
     && run.completionEvidence == null
     && run.recoveryHistory.length === 0;
 }
@@ -633,7 +622,6 @@ function beginOrResumeOrchestration(taskRef: string, options: OrchestrationOptio
           baselineEmpty: true,
           receiptCount: 0,
           pendingDelegation: false,
-          commitAuthorizationUnused: true,
           completionEvidenceAbsent: true
         },
         resultingStatus: 'running'
@@ -686,7 +674,6 @@ function beginOrResumeOrchestration(taskRef: string, options: OrchestrationOptio
     pendingDelegation: null,
     receipts: [],
     pause: null,
-    commitAuthorization: { issuedAt: null, consumedAt: null },
     completionEvidence: null,
     createdAt: now,
     updatedAt: now
@@ -1087,56 +1074,28 @@ function dispatchOrchestrationDelegation(
   }
 }
 
+type MatchingDelegationsResult =
+  | Readonly<{ ok: true; matches: readonly { taskId: string; run: OrchestrationRun }[] }>
+  | Readonly<{ ok: false; error: OrchestrationResult }>;
+
 function matchingDelegations(
   predicate: (receipt: DelegationReceipt) => boolean,
   options: OrchestrationOptions
-): Array<{ taskId: string; run: OrchestrationRun }> {
-  const repoRoot = options.repoRoot ?? process.cwd();
-  if (options.taskId) {
-    const taskDir = path.join(repoRoot, '.agents', 'workspace', 'active', options.taskId);
-    const run = readRun(taskDir, options);
-    return run && run.status === 'running' && run.pendingDelegation && predicate(run.pendingDelegation)
-      ? [{ taskId: options.taskId, run }]
-      : [];
+): MatchingDelegationsResult {
+  const taskId: unknown = options.taskId;
+  if (taskId === undefined || taskId === '') {
+    return { ok: false, error: failed('ORCHESTRATION_TASK_ID_REQUIRED', 'taskId is required for lifecycle matching') };
   }
-  const activeRoot = path.join(repoRoot, '.agents', 'workspace', 'active');
-  if (!fs.existsSync(activeRoot)) return [];
-  emitDiagnostic(options, 'orchestration-active-scan-start', {
-    activeRoot
-  });
-  const matches = fs.readdirSync(activeRoot, { withFileTypes: true })
-    .filter((entry) => entry.isDirectory())
-    .flatMap((entry) => {
-      const candidateTaskId = entry.name;
-      const candidateTaskDir = path.join(activeRoot, candidateTaskId);
-      emitDiagnostic(options, 'orchestration-active-scan-candidate', {
-        candidateTaskId,
-        candidateTaskDir,
-        orchestrationPath: orchestrationPath(candidateTaskDir)
-      });
-      let run: OrchestrationRun | null;
-      try {
-        run = readRun(candidateTaskDir, options);
-      } catch (error) {
-        emitDiagnostic(options, 'orchestration-active-scan-candidate-failed', {
-          candidateTaskId,
-          candidateTaskDir,
-          errorType: error instanceof Error ? error.name : typeof error,
-          reasonCodes: error instanceof OrchestrationStateError ? error.reasonCodes.join(',') : null
-        });
-        throw error;
-      }
-      if (!run || run.status !== 'running' || !run.pendingDelegation) return [];
-      const receipt = run.pendingDelegation;
-      return predicate(receipt)
-        ? [{ taskId: candidateTaskId, run }]
-        : [];
-    });
-  emitDiagnostic(options, 'orchestration-active-scan-finished', {
-    activeRoot,
-    matchingDelegations: matches.length
-  });
-  return matches;
+  if (typeof taskId !== 'string' || !TASK_ID_RE.test(taskId)) {
+    return { ok: false, error: failed('ORCHESTRATION_TASK_ID_INVALID', 'taskId must be a canonical TASK-id') };
+  }
+  const repoRoot = options.repoRoot ?? process.cwd();
+  const taskDir = path.join(repoRoot, '.agents', 'workspace', 'active', taskId);
+  const run = readRun(taskDir, options);
+  const matches = run && run.status === 'running' && run.pendingDelegation && predicate(run.pendingDelegation)
+    ? [{ taskId, run }]
+    : [];
+  return { ok: true, matches };
 }
 
 function uniqueMatchingDelegation(
@@ -1144,12 +1103,13 @@ function uniqueMatchingDelegation(
   predicate: (receipt: DelegationReceipt) => boolean,
   options: OrchestrationOptions
 ): { taskId: string; run: OrchestrationRun } | OrchestrationResult {
-  const matches = matchingDelegations(
+  const lookup = matchingDelegations(
     (receipt) => receipt.client === client && predicate(receipt),
     options
   );
+  if (!lookup.ok) return lookup.error;
+  const matches = lookup.matches;
   if (matches.length === 0) return failed('ORCHESTRATION_DELEGATION_MISSING', 'no matching lifecycle delegation exists');
-  if (matches.length > 1) return failed('ORCHESTRATION_DELEGATION_AMBIGUOUS', 'multiple lifecycle delegations match the native hook event');
   return matches[0]!;
 }
 
@@ -1158,13 +1118,14 @@ function hasActivatableOrchestrationDelegation(
   childId: string,
   options: OrchestrationOptions = {}
 ): boolean {
-  return matchingDelegations(
+  const lookup = matchingDelegations(
     (receipt) => receipt.client === client && (
       receipt.status === 'prepared'
       || (receipt.childId === childId && ['activated', 'stage-completed'].includes(receipt.status))
     ),
     options
-  ).length > 0;
+  );
+  return lookup.ok && lookup.matches.length > 0;
 }
 
 function hasSealableOrchestrationDelegation(
@@ -1172,12 +1133,13 @@ function hasSealableOrchestrationDelegation(
   childId: string,
   options: OrchestrationOptions = {}
 ): boolean {
-  return matchingDelegations(
+  const lookup = matchingDelegations(
     (receipt) => receipt.client === client
       && receipt.childId === childId
       && ['stage-completed', 'sealed'].includes(receipt.status),
     options
-  ).length > 0;
+  );
+  return lookup.ok && lookup.matches.length > 0;
 }
 
 function activateMatchingOrchestrationDelegation(

package/lib/task/short-id.ts

@@ -1,5 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { parseTypedTaskFrontmatter } from './frontmatter.ts';
 
 const REGISTRY_NAME = '.short-ids.json';
 const LOCK_NAME = '.short-ids.json.lock';
@@ -159,43 +160,35 @@ function resolveShortIdReadOnly(
   const taskId = ids[key];
   if (!taskId) {
     const message = Object.keys(ids).length === 0
-      ? `short id '${key}' not found; active task registry is empty.`
-      : `short id '${key}' not found in active task registry (it may have been cleaned up after archival; check 'task-short-id.js list').`;
+      ? `short id '${key}' not found; task short-id registry is empty.`
+      : `short id '${key}' not found in task short-id registry.`;
     return shortIdFailure('SHORT_ID_NOT_FOUND', message);
   }
-  const taskMdPath = path.join(
-    repoRoot,
-    '.agents',
-    'workspace',
-    'active',
-    taskId,
-    'task.md'
-  );
-  if (!fs.existsSync(taskMdPath)) {
-    const remainingActiveEntries = Object.values(ids).filter((candidateTaskId) =>
-      fs.existsSync(
-        path.join(
-          repoRoot,
-          '.agents',
-          'workspace',
-          'active',
-          candidateTaskId,
-          'task.md'
-        )
-      )
-    );
-    const message = remainingActiveEntries.length === 0
-      ? `short id '${key}' not found; active task registry is empty.`
-      : `short id '${key}' not found in active task registry (it may have been cleaned up after archival; check 'task-short-id.js list').`;
+  const activeTask = path.join(repoRoot, '.agents', 'workspace', 'active', taskId, 'task.md');
+  const completedTask = path.join(repoRoot, '.agents', 'workspace', 'completed', taskId, 'task.md');
+  let isValidCompletedTask = false;
+  try {
+    const task = parseTypedTaskFrontmatter(fs.readFileSync(completedTask, 'utf8'));
+    isValidCompletedTask = task.id === taskId && task.status === 'completed';
+  } catch { /* a mapping is valid only while its task content is present */ }
+  if (!fs.existsSync(activeTask) && !isValidCompletedTask) {
     return shortIdFailure(
       'SHORT_ID_STALE',
-      message,
+      `short id '${key}' points to no active or completed task content.`,
       taskId
     );
   }
   return { ok: true, taskId };
 }
 
+function hasRetainedCompletedTask(activeDir: string, taskId: string): boolean {
+  try {
+    const taskPath = path.join(path.dirname(activeDir), 'completed', taskId, 'task.md');
+    const task = parseTypedTaskFrontmatter(fs.readFileSync(taskPath, 'utf8'));
+    return task.id === taskId && task.status === 'completed';
+  } catch { return false; }
+}
+
 type RegistrySchema = {
   version: number;
   ids: Record<string, string>;
@@ -339,7 +332,8 @@ function mutateShortIdRegistryAt(
     const original = JSON.stringify(registry.ids);
     if (pruneOrphans) {
       for (const [key, candidate] of Object.entries(registry.ids)) {
-        if (candidate !== taskId && !fs.existsSync(path.join(activeDir, candidate, 'task.md'))) delete registry.ids[key];
+        if (candidate !== taskId && !fs.existsSync(path.join(activeDir, candidate, 'task.md'))
+          && !hasRetainedCompletedTask(activeDir, candidate)) delete registry.ids[key];
       }
     }
     const existing = Object.entries(registry.ids).find(([, candidate]) => candidate === taskId);
@@ -406,28 +400,27 @@ function executeShortIdCommand(request: ShortIdCommandRequest): ShortIdCommandRe
       if (normalized.kind !== 'shortId') {
         throw Object.assign(new Error(`invalid short id format '${request.argument}'`), { code: 'SHORT_ID_FORMAT_INVALID' });
       }
-      return withRegistryLock(request.activeDir, () => {
-        const registry = readRegistryStrict(registryPath, request.shortIdLength);
-        let changed = false;
-        for (const [key, taskId] of Object.entries(registry.ids)) {
-          if (!fs.existsSync(path.join(request.activeDir, taskId, 'task.md'))) { delete registry.ids[key]; changed = true; }
-        }
-        if (changed) writeRegistry(registryPath, registry);
-        const taskId = registry.ids[normalized.value];
-        if (!taskId) throw Object.assign(new Error(`short id '${normalized.value}' not found in active task registry`), { code: 'SHORT_ID_NOT_FOUND' });
-        return { status: changed ? 'applied' : 'no-op', changed, output: taskId, error: null };
-      });
+      const registry = readRegistryStrict(registryPath, request.shortIdLength);
+      const taskId = registry.ids[normalized.value];
+      if (!taskId) throw Object.assign(new Error(`short id '${normalized.value}' not found in task short-id registry`), { code: 'SHORT_ID_NOT_FOUND' });
+      if (!fs.existsSync(path.join(request.activeDir, taskId, 'task.md'))
+        && !hasRetainedCompletedTask(request.activeDir, taskId)) {
+        throw Object.assign(new Error(`short id '${normalized.value}' points to a task without active or completed task content`), { code: 'SHORT_ID_STALE' });
+      }
+      return { status: 'no-op', changed: false, output: taskId, error: null };
     }
     const registry = readRegistryStrict(registryPath, request.shortIdLength);
     if (request.verify) {
       const active = fs.existsSync(request.activeDir)
         ? fs.readdirSync(request.activeDir).filter((entry) => /^TASK-\d{8}-\d{6}$/.test(entry) && fs.existsSync(path.join(request.activeDir, entry, 'task.md')))
         : [];
+      const retained = Object.values(registry.ids).filter((taskId) => hasRetainedCompletedTask(request.activeDir, taskId));
+      const validTasks = new Set([...active, ...retained]);
       const registered = new Map<string, string[]>();
       for (const [key, taskId] of Object.entries(registry.ids)) registered.set(taskId, [...(registered.get(taskId) ?? []), key]);
       const diff = {
         missing_in_registry: active.filter((taskId) => !registered.has(taskId)).map((taskId) => ({ taskId })),
-        orphans_in_registry: Object.entries(registry.ids).filter(([, taskId]) => !active.includes(taskId)).map(([key, taskId]) => ({ key, taskId })),
+        orphans_in_registry: Object.entries(registry.ids).filter(([, taskId]) => !validTasks.has(taskId)).map(([key, taskId]) => ({ key, taskId })),
         duplicate_registry_keys: [...registered.entries()].filter(([, keys]) => keys.length > 1).map(([taskId, keys]) => ({ taskId, keys }))
       };
       const clean = Object.values(diff).every((items) => items.length === 0);

package/lib/task/verification-engine.ts

@@ -167,12 +167,8 @@ function checkOrchestrationState({ taskDir }: any): any {
     return failResult('orchestration-state', 'Paused run requires a stable pause code and message');
   }
   if (run.status === 'completed') {
-    if (run.completionEvidence != null) {
-      const evidenceError = validateCleanCompletionEvidence(run);
-      if (evidenceError) return failResult('orchestration-state', evidenceError);
-    } else if (run.pendingDelegation !== null || !run.commitAuthorization?.consumedAt) {
-      return failResult('orchestration-state', 'Completed run must consume commit authorization and clear pending delegation');
-    }
+    const evidenceError = validateCleanCompletionEvidence(run);
+    if (evidenceError) return failResult('orchestration-state', evidenceError);
   } else if (run.completionEvidence != null) {
     return failResult('orchestration-state', 'Clean completion evidence requires a completed run');
   } else if (run.pendingDelegation?.status === 'sealed') {
@@ -209,11 +205,9 @@ function validateCleanCompletionEvidence(run: OrchestrationRun): string | null {
   if (
     run.status !== 'completed'
     || run.pendingDelegation !== null
-    || run.commitAuthorization?.issuedAt !== null
-    || run.commitAuthorization?.consumedAt !== null
     || run.receipts.some((receipt) => receipt.stage === 'commit')
   ) {
-    return 'Clean completion evidence conflicts with commit delegation state';
+    return 'Clean completion evidence conflicts with pending delegation or commit receipt state';
   }
   return null;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fitlab-ai/agent-infra",
-  "version": "0.11.12",
+  "version": "0.11.13",
   "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/rules/README.en.md

@@ -17,6 +17,7 @@ so you can quickly find "which ones to read" without opening each file.
 - [`validation-output.md`](validation-output.md) — User-facing validation summaries, failure diagnostics, soft warnings, and consumer boundaries.
 - [`sync-content-generation.md`](sync-content-generation.md) — Producer-side Markdown constraints for task and lifecycle content synchronized to Issues.
 - [`decision-qualification.md`](decision-qualification.md) — Constraint, candidate, human-confirmation, and six-artifact qualification-audit contract.
+- [`strategy-pattern.md`](strategy-pattern.md) — Identify shared flows and different behaviors, then use interfaces and the Strategy Pattern to isolate implementation differences.
 
 ## Issue / PR
 

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

@@ -16,6 +16,7 @@
 - [`validation-output.md`](validation-output.md) — 面向用户的校验状态摘要、失败诊断、软警告及消费边界。
 - [`sync-content-generation.md`](sync-content-generation.md) — 同步到 Issue 的任务和生命周期 Markdown 生成约束。
 - [`decision-qualification.md`](decision-qualification.md) — 约束、候选、人工确认和六类 artifact 资格审计契约。
+- [`strategy-pattern.md`](strategy-pattern.md) — 识别共用流程和不同行为，通过接口与策略模式隔离实现差异。
 
 ## Issue / PR
 

package/templates/.agents/rules/strategy-pattern.en.md

@@ -0,0 +1,25 @@
+# Strategy Pattern
+
+This rule applies during technical design and implementation. When behavior differs by platform, client, protocol, workflow, business rule, or algorithm, use interfaces to isolate implementations so shared flows can reuse them instead of creating a dedicated path for every scenario.
+
+## Design Steps
+
+1. **Separate shared flows from different implementations**: identify common steps and the behavior that differs by platform, client, protocol, workflow, business rule, algorithm, or lifecycle.
+2. **Define the interface contract**: specify the inputs, outputs, error semantics, and invocation timing shared by implementations. The common flow depends on the interface, not a concrete implementation.
+3. **Apply the Strategy Pattern**: provide an implementation for each behavior and select a strategy at registration or assembly. The common flow orchestrates shared steps without spreading conditions that identify concrete implementations.
+4. **Verify substitutability**: a new implementation should connect through registration or assembly. Write shared tests for the interface contract and the necessary tests for strategy selection and full assembly.
+
+## Implementation Requirements
+
+- When the requirement clearly includes multiple behaviors, prefer the Strategy Pattern even if there is currently one implementation; the interface should express their stable shared contract.
+- When adding behavior, prefer adding a strategy implementation and registering or assembling it in one place. Do not copy a full business flow or repeat the same branch across callers.
+- If branches that identify implementations are already scattered across paths, consolidate those decisions at strategy selection and make callers depend on the interface.
+- Reuse existing interfaces and domain terms. Do not rename code to apply a pattern or add interfaces to stable behavior that has no meaningful alternatives.
+- Keep stable, single-purpose behavior direct when there is no evidence it will vary. Do not mechanically add interfaces, configuration, or extension points.
+
+## Design Review Questions
+
+- Which steps are shared by all implementations, and which behaviors differ by platform, client, or business rule?
+- Does the interface express the contract shared by the implementations?
+- Can a new behavior be added by implementing a strategy and assembling it in one place? If several call paths must change, is centralized strategy selection missing?
+- Can the same interface tests validate the shared contract while strategy differences are tested independently?

package/templates/.agents/rules/strategy-pattern.zh-CN.md

@@ -0,0 +1,25 @@
+# 策略模式
+
+本规则适用于方案设计和代码实现。当平台、客户端、协议、工作流、业务规则或算法存在多种行为时，用接口隔离这些实现，让共用流程能够复用不同实现，避免每种场景都形成一条专用链路。
+
+## 设计步骤
+
+1. **区分共用流程和不同实现**：找出所有实现共同执行的步骤，以及会因平台、客户端、协议、工作流、业务规则、算法或生命周期而不同的行为。
+2. **定义接口契约**：明确不同实现的输入、输出、错误语义和调用时机。共用流程依赖接口，不直接调用某个具体实现。
+3. **应用策略模式**：为每种行为提供独立实现，在注册或装配处选择策略。共用流程负责编排共同步骤，不散布识别具体实现的条件分支。
+4. **验证实现可替换**：新增实现应能通过注册或装配接入；为接口约定编写共享测试，并为策略选择和整体装配编写必要测试。
+
+## 实现要求
+
+- 需求明确包含多种行为时，优先使用策略模式，即使当前只有一个实现；接口应表达这些实现之间稳定的共同约定。
+- 新增行为时，优先增加一个策略实现并在统一位置注册或装配，不复制完整业务链，也不在多个调用方重复增加同类分支。
+- 如果识别不同实现的分支已经散落在多条路径，先把这些判断收敛到策略选择处，再让调用方依赖接口。
+- 复用现有接口和领域词汇；不要为了套用模式而改名，也不要为没有不同行为的稳定逻辑增加接口。
+- 对稳定、单一且没有证据表明会变化的逻辑，保持直接实现，不机械添加接口、配置或扩展点。
+
+## 设计审查问题
+
+- 所有实现共用哪些流程？哪些行为因平台、客户端或业务规则而不同？
+- 接口是否表达了不同实现共同遵守的约定？
+- 新实现能否只新增策略并在一个位置装配？如果必须修改多处调用链，是否缺少统一的策略选择？
+- 共用约定能否通过同一套接口测试验证，不同策略的差异能否独立验证？

package/templates/.agents/skills/code-task/reference/code-rules.en.md

@@ -19,6 +19,10 @@ Follow the `code` step in `.agents/workflows/feature-development.yaml`.
 3. **Keep testing continuously**: run the **fast smoke subset** continuously as work progresses (see the `test` skill)
 4. **Keep it simple**: do not add unplanned features
 
+## Strategy Pattern
+
+Read `.agents/rules/strategy-pattern.md` before implementation. When behavior differs by platform, client, protocol, workflow, business rule, or algorithm, follow the interface selected in the plan and make the core flow depend on that interface rather than concrete classes. Add each behavior as a strategy and select or assemble it in one place. If branches identifying implementations are scattered across paths, centralize strategy selection before editing callers. Keep stable behavior direct when it has no meaningful alternatives; do not add interfaces mechanically.
+
 ## Run Test Verification
 
 During implementation:

package/templates/.agents/skills/code-task/reference/code-rules.zh-CN.md

@@ -19,6 +19,10 @@
 3. **持续测试**：实现过程中持续运行 **fast smoke 子集**（参见 `test` skill）
 4. **保持简单**：不要加入未计划的功能
 
+## 策略模式
+
+实现前读取 `.agents/rules/strategy-pattern.md`。当实现涉及平台、客户端、协议、工作流、业务规则或算法的不同实现时，沿用方案确定的接口，让主流程依赖接口而不是具体类；新增行为应作为策略实现，在统一位置选择或装配。若识别不同实现的分支已散落在多条路径，先收敛策略选择，再修改调用方。行为稳定且没有明确替代实现时，保留直接实现，不机械增加接口。
+
 ## 运行测试验证
 
 实现过程中：

package/templates/.agents/skills/complete-task/SKILL.en.md

@@ -158,7 +158,7 @@ The core deduplicates the stable `step/code/target` tuple. Callers must not allo
 
 ### 5. Run the Active Pre-completion Hard Gate
 
-After platform writes succeed and before moving the directory or releasing the short id, run:
+After platform writes succeed and before moving the directory, run:
 
 ```bash
 agent-infra-internal task-verify {task-id} complete-task.preflight --format text
@@ -182,32 +182,11 @@ For an active task, finalization first recovers pending platform operations, the
 
 Finalization runs allowed artifact backfill -> lifecycle -> terminal task comment -> core verification -> warning task-comment update -> summary seal in a fixed order. Every backfill that actually runs must reach a successful terminal result before lifecycle starts; an ordinary replay with a complete receipt and no recovery fact does not rerun backfill, comments, verification, or summary. A completed recovery that may write a managed comment first persists a done summary as pending, then seals it only at the end. Summary seal always reads the durable staging record retained in the task directory; the platform entry point validates marker, owner, and digest, performs any required delete/recreate, and reads back final remote order. `result=completed` means the host safely completed the task from structured results and the receipt; if peripheral warnings or pending steps remain, return `result=completed_with_warnings`, warnings, and pending steps. Use `result=failed` or `result=blocked` only for hard or receipt/capability failures, then fix the cause and retry through the same entry point; do not claim completion or hand-repair partial state. A sandbox must not run `ls completed` or a local terminal verification against its historical mount to re-decide this result.
 
-### 7. Handle Finalization Retries and Results
+### 7. Handle the Finalization Result
 
-Both Scenario A and Scenario B `finalization-retry` run the same `task-finalization` entry point from the host. The receipt is only a re-entry hint, not canonical truth: every re-entry revalidates allowed artifact backfill, the terminal task comment, and completion verification, then repeats summary seal from the retained durable staging record; only an already `completed` task with its short-id registry entry released may skip the irreversible lifecycle. Do not split the operation into the former lifecycle, comment-sync, or completion-gate commands. If backfill, the task comment, summary seal, or verification is blocked by the network, preserve the receipt, durable staging record, and completed steps, fix the network, and rerun complete-task. If lifecycle has not completed, keep the task active and resume the pending steps from the receipt.
+The sandbox-local entry calls the existing finalization prepare/commit flow directly. Before lifecycle transfer, it stops this task's broker from accepting new requests and waits for accepted work to finish through its existing path. Transfer starts only after the broker owner exits. On success, use the structured result and receipt returned by this command. On failure or blocked status, preserve source data and the receipt, follow the returned error, and do not claim completion or manually rewrite terminal state.
 
-Consume the structured finalization result, receipt, and warning projection directly. Continue only for `completed` or `completed_with_warnings`. Treat `failed` and `blocked` as explicit host failure or blocked outcomes: preserve the receipt, stop the current flow, and follow the returned status and error; call finalization again only when the host state permits it and the cause has been fixed. If an `accepted=true` request is `unknown`, preserve the receipt and original request ID. Never resubmit task-finalization; query only the original request with `sandbox-control recover <same-request-id>`. Create a new request only when the request was rejected before acceptance and its error permits a retry. Do not run `ls completed` or `task-verify complete-task.completed` from a stale sandbox mount, and do not let that local result overrule the host result.
-
-### Recovering an accepted sandbox-control result
-
-When this skill runs in a sandbox and an accepted task-finalization request has
-no terminal result yet, the client automatically recovers under the same
-request ID. The five-minute total budget starts with the first unknown result;
-each recover call is limited to 30 seconds. While a published unknown response
-is present, the client rereads it every 25 ms during that call. When a recover
-call times out with unknown, the client continues immediately without an extra
-wait. The client prints `SANDBOX_CONTROL_REQUEST_ID: <request-id>` on stderr.
-
-If no terminal result arrives within five minutes, preserve the receipt and
-request ID and treat the result as pending/unknown. Do not resubmit
-task-finalization. Once the broker is healthy, continue querying only the
-original request ID:
-
-```bash
-agent-infra-internal sandbox-control recover <request-id>
-```
-
-Do not submit a new request for an accepted task finalization. If the request ID is missing or the receipt cannot be read, keep the result pending and recover the original ID only from stderr, a handoff, or the receipt; do not look it up by task key. The broker's `processing/<request-id>/result.json` is private transport evidence, not a task receipt, and cannot by itself prove completion. The finalization receipt and host completion gate remain authoritative. If recovery with the same ID still has no terminal result, inspect broker and host executor activity. Stop and preserve the original request ID while a request is active, the broker is busy, or status is unknown. Retry with a new request ID only after confirming that the original request never started or its executor has ended; the new request performs the full prepare and commit after broker admission. Only a request rejected before acceptance may be retried directly with a new request ID according to the error's retryability.
+Completion keeps the short-id mapping. Managed sandbox cleanup releases it only after the container is confirmed removed and cleanup succeeds. To clean up, pass the retained short id or full `{task-id}` to `ai sandbox rm`; do not release the short id separately during completion.
 
 ### 8. Inform User
 
@@ -230,7 +209,7 @@ Deliverables:
 Optional: clean up this task's sandbox
 (The task is completed; the sandbox container and per-branch config directory are not reclaimed automatically. Run this if you no longer need them:)
 
-ai sandbox rm {task-id}
+ai sandbox rm {task-id}  # or use the task's retained short id
 
 ```
 

package/templates/.agents/skills/complete-task/SKILL.zh-CN.md

@@ -157,7 +157,7 @@ agent-infra-internal task-warning {task-id} add --step complete-task --severity
 
 ### 5. 运行 active 预完成硬门禁
 
-平台写入成功后、移动目录和释放短号之前运行：
+平台写入成功后、移动目录前运行：
 
 ```bash
 agent-infra-internal task-verify {task-id} complete-task.preflight --format text
@@ -181,29 +181,11 @@ active 任务的 finalization 先恢复账本中的待处理平台操作，并
 
 finalization 按允许的 artifact backfill → lifecycle → task 评论 → core verification → warning task 评论更新 → summary seal 的固定顺序执行。每项实际运行的 backfill 必须取得成功终态，否则不得进入 lifecycle；完整 receipt 且无恢复事实的普通重入不执行 backfill、评论、验证或 summary。任何可能写入 managed comment 的 completed 恢复会先把 done summary 持久化为 pending，恢复末尾才重新 seal。summary seal 始终读取任务目录中保留的 durable staging record；平台入口负责校验 marker、owner 和 digest，必要时删除并重建摘要，再复读最终远端顺序。`result=completed` 即表示宿主已依据结构化结果和 receipt 安全完成；若还有外围 warning 或 pending step，返回 `result=completed_with_warnings`、warnings 和 pending steps。`result=failed` 或 `result=blocked` 仅用于硬失败或 receipt/capability 失败，修复原因后以同一入口重试，不得宣称完成或手工补写局部状态。沙箱不得从旧挂载执行 `ls completed` 或本地终态校验来重新裁决该结果。
 
-### 7. 处理 finalization 重试与结果
+### 7. 处理 finalization 结果
 
-场景 A 与场景 B `finalization-retry` 都从宿主执行同一个 `task-finalization` 入口。receipt 只是重入提示，不是 canonical truth：每次重入都要重新核对允许的 artifact 回填、终态 task 评论、完成校验，并使用保留的 durable staging record 重做 summary seal；只有任务已处于 `completed` 且短号 registry 已释放时，才可跳过不可逆的 lifecycle。不得拆开调用旧的 lifecycle、评论同步或完成校验命令。若回填、task 评论、summary seal 或校验因网络问题返回 `blocked`，保留 receipt、durable staging record 和已完成状态，修复网络后重跑 complete-task；若生命周期仍未完成，任务保持 active 并从 receipt 的待处理步骤继续。
+sandbox-local 入口直接执行已有 finalization prepare/commit。lifecycle 移动前，它先停止本任务 broker 接收新请求，并等待已接收操作按原路径完成；只有 broker owner 退出后才开始迁移 task 目录。成功时消费本次命令返回的结构化结果和 receipt。失败或阻塞时保留源数据与 receipt，按返回的错误处理，不输出完成消息，也不手工改写终态。
 
-完成结果必须直接消费本次宿主 finalization 的结构化输出、receipt 和 warning projection。只有 `completed` 或 `completed_with_warnings` 允许继续。`failed` / `blocked` 是宿主明确返回的失败或阻塞结果：保留 receipt，停止当前流程，并按宿主返回的状态和错误处理；只有宿主状态允许且原因已修复时，才重新调用 finalization。若 `accepted=true` 的请求结果为 `unknown`，保留 receipt 和原 request ID；不得重发 task-finalization，只能通过 `sandbox-control recover <同一 request-id>` 查询原请求。只有请求在 accepted 之前被拒绝，且错误允许重试时，才可创建新请求。不要在沙箱旧挂载中另行运行 `ls completed` 或 `task-verify complete-task.completed`，也不要用其结果推翻宿主结果。
-
-### accepted 后的 sandbox-control 结果恢复
-
-如果本技能在沙箱内执行，且 task-finalization 请求已经 accepted 但暂时没有
-terminal result，client 会从首次 unknown 开始自动按同一个 request ID 恢复，
-总预算为 5 分钟，每次 recover 最多 30 秒；published unknown 会在当前调用中
-按 25ms 间隔重读，预算用尽后立即继续 recover，不额外等待。client 会在 stderr
-输出 `SANDBOX_CONTROL_REQUEST_ID: <request-id>`。
-
-5 分钟后仍没有 terminal result 时，必须保留 receipt 和 request ID，并将结果视为
-pending/unknown；不得重发 task-finalization。broker 恢复健康后，只能继续查询原
-request ID：
-
-```bash
-agent-infra-internal sandbox-control recover <request-id>
-```
-
-accepted 的 task finalization 不得提交新请求。若 request ID 缺失或 receipt 无法读取，保持 pending；只从 stderr、handoff 或 receipt 中恢复原 ID，不按 task key 查询。broker 的 `processing/<request-id>/result.json` 只是私有 transport evidence，不是 task receipt，单凭它不能证明任务完成；finalization receipt 和宿主完成校验仍是权威。若同 ID 恢复仍没有 terminal result，必须检查 broker 和宿主 executor 的活动状态：活动请求、`busy` 或状态未知时停止并保留原 request ID。只有确认原请求从未启动或 executor 已结束后，才可用新的 request ID 重试；新请求会在 broker 接纳后执行完整 prepare 和 commit。仅当请求在 accepted 之前已被拒绝时，才可直接依据错误的 retryability 决定是否提交新的 request ID.
+complete 保留短号映射。它只会在受管 sandbox 清理确认容器已删除且清理成功后释放。需要清理时可用保留短号或完整 `{task-id}` 调用 `ai sandbox rm`；不要在 complete 中单独释放短号。
 
 ### 8. 告知用户
 
@@ -226,7 +208,7 @@ accepted 的 task finalization 不得提交新请求。若 request ID 缺失或
 可选：清理本任务的沙箱
 （任务已完成，沙箱容器和 per-branch 配置目录不会自动回收。如果不再需要可执行：）
 
-ai sandbox rm {task-id}
+ai sandbox rm {task-id}  # 或使用本任务仍保留的短号
 
 ```
 

package/templates/.agents/skills/plan-task/SKILL.en.md

@@ -91,6 +91,8 @@ Use it to understand:
 
 ### 5. Design the Technical Plan
 
+Before designing, read `.agents/rules/strategy-pattern.md`. Identify shared flows and behavior differences by platform, client, protocol, workflow, business rule, or algorithm; make the core flow depend on interfaces and put differences in strategy implementations instead of adding a dedicated branch to every path.
+
 Follow the `technical-design` step in `.agents/workflows/feature-development.yaml`:
 
 **Required tasks**:
@@ -105,10 +107,11 @@ When this round introduces a new key design decision, first run `agent-infra-int
 
 **Design principles**:
 1. **Architectural soundness**: choose the structurally correct approach; diff size is not the primary criterion. Do not pile changes onto an unsound structure just to keep the diff small
-2. **Simplicity**: given a sound architecture, prefer the simplest approach and avoid over-engineering
-3. **Consistency**: follow existing code patterns and conventions
-4. **Testability**: design for straightforward testing
-5. **Reversibility**: prefer changes that are easy to roll back
+2. **Strategy Pattern**: identify shared flows and different behaviors; make the core flow depend on interfaces, not concrete implementations, and select or assemble strategies in one place
+3. **Simplicity**: given a sound architecture, prefer the simplest approach; do not add strategy interfaces mechanically when behavior is stable and has no meaningful alternatives
+4. **Consistency**: follow existing code patterns and conventions
+5. **Testability**: design for straightforward testing
+6. **Reversibility**: prefer changes that are easy to roll back
 
 ### 6. Output Plan Document