@fitlab-ai/agent-infra 0.11.15 → 0.12.0

package/lib/task/verification-engine.ts

@@ -69,9 +69,7 @@ const DEFAULT_REQUIRED_FIELDS = [
 ];
 
 const DATE_TIME_PATTERN = /^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}(?:[+-]\d{2}:\d{2})?$/;
-// Start markers (action suffixed with ` [started]`) are excluded from the
-// "latest action" / freshness computation so a step's in-flight marker never
-// satisfies a skill's expected_action_pattern; the matching done entry does.
+// Started rows do not represent completed lifecycle actions.
 const ACTIVITY_LOG_STARTED_RE = /\s*\[started\]\s*$/;
 const BRANCH_SLUG_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 
@@ -358,16 +356,10 @@ function checkTaskMeta({ taskDir, config, repositoryRoot, skillName, artifactFil
   if (expectedStep && metadata.current_step !== expectedStep) {
     let validLifecycleArtifact = false;
     if (currentTask) {
-      const activityConfig = loadVerificationConfig(repositoryRoot, skillName).checks?.["activity-log"];
       const { section, invalidEntries } = inspectActivityLog(task.content);
-      if (activityConfig && section && invalidEntries.length === 0) {
-        let latestAction = "";
-        for (const entry of section.entries) {
-          if (!ACTIVITY_LOG_STARTED_RE.test(entry.step)) latestAction = entry.step;
-        }
+      if (section && invalidEntries.length === 0) {
         validLifecycleArtifact = checkArtifactLifecycleActivityLog(
-          taskDir, artifactFile, skillName,
-          activityConfig, task, section.entries, latestAction
+          taskDir, artifactFile, skillName, task, section.entries
         )?.status === "pass";
       }
     }
@@ -725,16 +717,16 @@ function checkImplementationInput({ taskDir, artifactFile }: any): any {
   return passResult("implementation-input", `${actionDecision} matches Activity Log, report, and task table`);
 }
 
-const ARTIFACT_ACTIVITY_STAGES: Readonly<Record<string, { family: string; event: string }>> = {
-  "analyze-task": { family: "analysis", event: "analyze.completed" },
-  "plan-task": { family: "plan", event: "plan.completed" },
-  "review-analysis": { family: "review-analysis", event: "review-analysis.completed" },
-  "review-plan": { family: "review-plan", event: "review-plan.completed" },
-  "code-task": { family: "code", event: "code.completed" },
-  "review-code": { family: "review-code", event: "review-code.completed" }
+const ARTIFACT_ACTIVITY_STAGES: Readonly<Record<string, { family: string; event: string; action: string }>> = {
+  "analyze-task": { family: "analysis", event: "analyze.completed", action: "Analyze Task" },
+  "plan-task": { family: "plan", event: "plan.completed", action: "Plan Task" },
+  "review-analysis": { family: "review-analysis", event: "review-analysis.completed", action: "Review Analysis" },
+  "review-plan": { family: "review-plan", event: "review-plan.completed", action: "Review Plan" },
+  "code-task": { family: "code", event: "code.completed", action: "Code Task" },
+  "review-code": { family: "review-code", event: "review-code.completed", action: "Review Code" }
 };
 
-function checkArtifactLifecycleActivityLog(taskDir: string, artifactFile: string | undefined, skillName: string, config: any, task: any, entries: any[], latestAction: string): any {
+function checkArtifactLifecycleActivityLog(taskDir: string, artifactFile: string | undefined, skillName: string, task: any, entries: any[]): any {
   const stage = ARTIFACT_ACTIVITY_STAGES[skillName];
   if (!stage) return null;
   const inventory = inspectArtifactDirectory(taskDir, stage.family as any);
@@ -772,25 +764,19 @@ function checkArtifactLifecycleActivityLog(taskDir: string, artifactFile: string
     }
   }
 
-  const expectedAction = new RegExp(config.expected_action_pattern);
+  const roundActionPattern = new RegExp(`^${stage.action} \\(Round ${identity.round}(?:, [^)]+)?\\)$`);
   const roundAction = entries.find((entry) => {
-    if (ACTIVITY_LOG_STARTED_RE.test(entry.step)) return false;
-    if (!expectedAction.test(entry.step)) return false;
-    expectedAction.lastIndex = 0;
-    const actionRound = /\(Round (\d+)/.exec(entry.step)?.[1];
-    return actionRound === String(identity.round) && entry.note.includes(`→ ${output}`);
+    return !ACTIVITY_LOG_STARTED_RE.test(entry.step)
+      && roundActionPattern.test(entry.step)
+      && entry.note.includes(`→ ${output}`);
   });
   if (!roundAction) {
     return failResult("activity-log", `No completed Activity Log row records '${output}' for ${skillName} Round ${identity.round}`);
   }
-  if (skillName === "plan-task" && /^(?:Human Decision|Decision)\b/.test(latestAction)
-    && expectedAction.test(latestAction)) {
-    return passResult("activity-log", `Plan completion '${output}' is current; latest action '${latestAction}' is a human decision`);
-  }
   return passResult("activity-log", `Current ${stage.family} completion '${output}' is valid for Round ${identity.round}`);
 }
 
-function checkActivityLog({ taskDir, config, skillName, artifactFile }: any): any {
+function checkActivityLog({ taskDir, skillName, artifactFile }: any): any {
   const task = loadTask(taskDir);
   if (!task.ok) {
     return failResult("activity-log", task.message);
@@ -802,44 +788,16 @@ 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 latestAction = "";
-  let latestTimestamp = "";
-  const doneActions: string[] = [];
-
   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;
-    // 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;
-      doneActions.push(action);
-    }
   }
 
   const artifactLifecycleResult = checkArtifactLifecycleActivityLog(
-    taskDir, artifactFile, skillName, config, task, entries, latestAction
+    taskDir, artifactFile, skillName, task, entries
   );
   if (artifactLifecycleResult) return artifactLifecycleResult;
 
-  if (config.expected_action_pattern && !new RegExp(config.expected_action_pattern).test(latestAction)) {
-    const expected = new RegExp(config.expected_action_pattern);
-    let index = doneActions.length - 1;
-    while (index >= 0 && doneActions[index] === 'Commit' && !expected.test(doneActions[index]!)) index -= 1;
-    if (index >= 0 && expected.test(doneActions[index]!)) {
-      latestAction = doneActions[index]!;
-    }
-  }
-
-  if (config.expected_action_pattern && !new RegExp(config.expected_action_pattern).test(latestAction)) {
-    return failResult(
-      "activity-log",
-      `Latest action '${latestAction}' does not match '${config.expected_action_pattern}'`
-    );
-  }
-
-  return passResult("activity-log", `Latest entry '${latestAction}' at ${latestTimestamp}`);
+  return passResult("activity-log", "Activity Log is valid");
 }
 
 function checkCompletionChecklist({ taskDir, config }: any): any {
@@ -1042,9 +1000,9 @@ async function checkPostReviewCommit({ taskDir, config, repositoryRoot }: any):
 
   let gitRoot;
   try {
-    gitRoot = execFileSync("git", ["-C", taskDir, "rev-parse", "--show-toplevel"], { encoding: "utf8" }).trim();
+    gitRoot = execFileSync("git", ["-C", repositoryRoot, "rev-parse", "--show-toplevel"], { encoding: "utf8" }).trim();
   } catch {
-    return blockedResult("post-review-commit", "git unavailable or task directory is not inside a git repository");
+    return blockedResult("post-review-commit", "git unavailable or repository root is not inside a git repository");
   }
 
   const task = loadTask(taskDir);

package/lib/task/workspace-root.ts

@@ -0,0 +1,78 @@
+import path from 'node:path';
+import fs from 'node:fs';
+import os from 'node:os';
+import { isSandbox } from '../sandbox/environment.ts';
+
+export type ExecutionBoundary = 'host' | 'container';
+
+/**
+ * Resolve the physical task-workspace boundary from the verified process
+ * execution context. Sandbox mode (task-bound / branch-only) does not affect
+ * the task workspace mount location.
+ */
+export function resolveTaskWorkspaceExecutionBoundary(
+  env: NodeJS.ProcessEnv = process.env
+): ExecutionBoundary {
+  if (env.AGENT_INFRA_SANDBOX !== '1') return 'host';
+  const statusMountPath = env.AGENT_INFRA_CONTROL_STATUS_DIR;
+  if (!statusMountPath || !isSandbox(env, { statusMountPath })) {
+    throw new Error('task workspace boundary requires a verified sandbox execution context');
+  }
+  return 'container';
+}
+
+export interface TaskWorkspaceLayout {
+  projectKey: string;
+  boundary: ExecutionBoundary;
+  root: string;
+  active: string;
+  blocked: string;
+  completed: string;
+  archive: string;
+  shortIds: string;
+}
+
+export function resolveTaskWorkspaceLayout(input: {
+  project: string;
+  boundary: ExecutionBoundary;
+  home?: string;
+}): TaskWorkspaceLayout {
+  const { project, boundary } = input;
+  if (!project || project === '.' || project === '..' || /[\\/\u0000-\u001f\u007f]/u.test(project)) {
+    throw new TypeError('project must be a safe single path segment');
+  }
+  let root: string;
+  if (boundary === 'container') {
+    root = '/task-workspace';
+  } else if (boundary === 'host') {
+    if (!input.home) throw new TypeError('home is required for host task workspace resolution');
+    if (!path.isAbsolute(input.home)) throw new TypeError('home must be an absolute path for host task workspace resolution');
+    root = path.join(input.home, '.agent-infra', 'task-workspaces', project);
+  } else {
+    throw new TypeError(`unsupported task workspace boundary: ${String(boundary)}`);
+  }
+  return {
+    projectKey: project,
+    boundary,
+    root,
+    active: path.join(root, 'active'),
+    blocked: path.join(root, 'blocked'),
+    completed: path.join(root, 'completed'),
+    archive: path.join(root, 'archive'),
+    shortIds: path.join(root, 'active', '.short-ids.json')
+  };
+}
+
+export function resolveProjectTaskWorkspaceLayout(
+  repoRoot: string,
+  boundary: ExecutionBoundary = resolveTaskWorkspaceExecutionBoundary()
+): TaskWorkspaceLayout {
+  const configPath = path.join(repoRoot, '.agents', '.airc.json');
+  const config = JSON.parse(fs.readFileSync(configPath, 'utf8')) as { project?: unknown };
+  if (typeof config.project !== 'string') throw new TypeError(`project is missing from ${configPath}`);
+  return resolveTaskWorkspaceLayout({ project: config.project, boundary, home: process.env.HOME || os.homedir() });
+}
+
+export function resolveProjectTaskWorkspaceRoot(repoRoot: string): string {
+  return resolveProjectTaskWorkspaceLayout(repoRoot).root;
+}

package/lib/task/workspace-snapshot.ts

@@ -3,6 +3,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
+import { resolveProjectTaskWorkspaceRoot } from './workspace-root.ts';
 
 function git(repoRoot: string, indexFile: string | null, args: string[]): string {
   const env = indexFile ? { ...process.env, GIT_INDEX_FILE: indexFile } : process.env;
@@ -55,7 +56,7 @@ function captureWorktreeTree(repoRoot: string, forcedPath: string | null): strin
 }
 
 function taskFileFingerprints(stateRoot: string, taskId: string | null): TaskFileFingerprint[] {
-  const activeRoot = path.join(stateRoot, '.agents', 'workspace', 'active');
+  const activeRoot = path.join(resolveProjectTaskWorkspaceRoot(stateRoot), 'active');
   const roots = taskId ? [path.join(activeRoot, taskId)] : [activeRoot];
   const records: TaskFileFingerprint[] = [];
   const visit = (absolute: string, relative: string): void => {
@@ -67,7 +68,7 @@ function taskFileFingerprints(stateRoot: string, taskId: string | null): TaskFil
       return;
     }
     if (!stat.isFile() && !stat.isSymbolicLink()) return;
-    if (/^\.agents\/workspace\/(?:active|blocked|completed)\/TASK-[0-9]{8}-[0-9]{6}\/\.runtime\/orchestration\.json$/u.test(relative)) return;
+    if (/^task-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);
@@ -80,7 +81,7 @@ function taskFileFingerprints(stateRoot: string, taskId: string | null): TaskFil
   };
   for (const root of roots) {
     if (!fs.existsSync(root)) continue;
-    const relative = path.posix.join('.agents/workspace/active', path.relative(activeRoot, root).split(path.sep).join('/'));
+    const relative = path.posix.join('task-workspace/active', path.relative(activeRoot, root).split(path.sep).join('/'));
     visit(root, relative.replace(/\/$/, ''));
   }
   return records.sort((left, right) => left.path.localeCompare(right.path));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fitlab-ai/agent-infra",
-  "version": "0.11.15",
+  "version": "0.12.0",
   "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/QUICKSTART.en.md

@@ -53,16 +53,23 @@ Built-in templates take priority over external templates. Later external templat
 
 ## Creating Your First Task
 
+Resolve the host task root once for these examples:
+
+```bash
+TASK_WORKSPACE_ROOT=$(agent-infra-internal task-workspace resolve --boundary host | node -e 'let input="";process.stdin.setEncoding("utf8");process.stdin.on("data",chunk=>input+=chunk);process.stdin.on("end",()=>process.stdout.write(JSON.parse(input).root));')
+```
+
 1. Copy the task template to the active workspace:
 
 ```bash
-cp .agents/templates/task.md .agents/workspace/active/task-001.md
+mkdir -p "$TASK_WORKSPACE_ROOT/active/TASK-20260101-120000"
+cp .agents/templates/task.md "$TASK_WORKSPACE_ROOT/active/TASK-20260101-120000/task.md"
 ```
 
 2. Fill in the task metadata:
 
 ```yaml
-id: task-001
+id: TASK-20260101-120000
 type: feature          # feature | bugfix | refactor | docs | review
 status: open           # open | in-progress | review | blocked | completed
 assigned_to: claude    # claude | codex | antigravity | opencode | human
@@ -92,7 +99,7 @@ Claude Code excels at codebase exploration and understanding complex relationshi
 agy
 
 # Example prompt:
-# "Based on the analysis in .agents/workspace/active/task-001.md,
+# "Based on the analysis in $TASK_WORKSPACE_ROOT/active/TASK-20260101-120000/task.md,
 #  create a technical design. Define interfaces and outline the approach."
 ```
 
@@ -103,7 +110,7 @@ agy
 codex
 
 # Example prompt:
-# "Implement the changes described in .agents/workspace/active/task-001.md.
+# "Implement the changes described in $TASK_WORKSPACE_ROOT/active/TASK-20260101-120000/task.md.
 #  Follow the design section. Create a new branch for this work."
 ```
 
@@ -130,7 +137,8 @@ claude
 
 ```bash
 # Quick bug fix workflow
-cp .agents/templates/task.md .agents/workspace/active/bugfix-001.md
+mkdir -p "$TASK_WORKSPACE_ROOT/active/TASK-20260101-120000"
+cp .agents/templates/task.md "$TASK_WORKSPACE_ROOT/active/TASK-20260101-120000/task.md"
 # Edit the task, then:
 # 1. Use Claude Code to analyze
 # 2. Use Codex/OpenCode to fix
@@ -144,7 +152,8 @@ cp .agents/templates/task.md .agents/workspace/active/bugfix-001.md
 3. **Report**: Generate review report from template.
 
 ```bash
-cp .agents/templates/review-report.md .agents/workspace/active/review-pr-42.md
+mkdir -p "$TASK_WORKSPACE_ROOT/active/TASK-20260101-120001"
+cp .agents/templates/review-report.md "$TASK_WORKSPACE_ROOT/active/TASK-20260101-120001/review-report.md"
 # Use Claude Code to fill in the review
 ```
 
@@ -156,7 +165,8 @@ cp .agents/templates/review-report.md .agents/workspace/active/review-pr-42.md
 4. **Verify** (Claude Code): Ensure no regressions, run tests.
 
 ```bash
-cp .agents/templates/task.md .agents/workspace/active/refactor-001.md
+mkdir -p "$TASK_WORKSPACE_ROOT/active/TASK-20260101-120002"
+cp .agents/templates/task.md "$TASK_WORKSPACE_ROOT/active/TASK-20260101-120002/task.md"
 # Follow the refactoring workflow in .agents/workflows/refactoring.yaml
 ```
 
@@ -165,7 +175,8 @@ cp .agents/templates/task.md .agents/workspace/active/refactor-001.md
 When switching between AI tools, create a handoff document:
 
 ```bash
-cp .agents/templates/handoff.md .agents/workspace/active/handoff-task-001-phase2.md
+mkdir -p "$TASK_WORKSPACE_ROOT/active/TASK-20260101-120003"
+cp .agents/templates/handoff.md "$TASK_WORKSPACE_ROOT/active/TASK-20260101-120003/handoff.md"
 ```
 
 Fill in:

package/templates/.agents/QUICKSTART.zh-CN.md

@@ -53,16 +53,23 @@ node -p "'v' + require('./package.json').version"
 
 ## 创建第一个任务
 
+先通过统一 resolver 取得宿主任务根，供以下示例使用：
+
+```bash
+TASK_WORKSPACE_ROOT=$(agent-infra-internal task-workspace resolve --boundary host | node -e 'let input="";process.stdin.setEncoding("utf8");process.stdin.on("data",chunk=>input+=chunk);process.stdin.on("end",()=>process.stdout.write(JSON.parse(input).root));')
+```
+
 1. 将任务模板复制到活跃工作区：
 
 ```bash
-cp .agents/templates/task.md .agents/workspace/active/task-001.md
+mkdir -p "$TASK_WORKSPACE_ROOT/active/TASK-20260101-120000"
+cp .agents/templates/task.md "$TASK_WORKSPACE_ROOT/active/TASK-20260101-120000/task.md"
 ```
 
 2. 填写任务元数据：
 
 ```yaml
-id: task-001
+id: TASK-20260101-120000
 type: feature          # feature | bugfix | refactor | docs | chore
 status: active         # active | blocked | completed
 assigned_to: claude    # claude | codex | antigravity | opencode | human
@@ -92,7 +99,7 @@ Claude Code 擅长代码库探索和理解文件间的复杂关系。
 agy
 
 # 示例提示：
-# "基于 .agents/workspace/active/task-001.md 中的分析结果，
+# "基于 $TASK_WORKSPACE_ROOT/active/TASK-20260101-120000/task.md 中的分析结果，
 #  创建技术设计方案。定义接口并概述实现思路。"
 ```
 
@@ -103,7 +110,7 @@ agy
 codex
 
 # 示例提示：
-# "实现 .agents/workspace/active/task-001.md 中描述的变更。
+# "实现 $TASK_WORKSPACE_ROOT/active/TASK-20260101-120000/task.md 中描述的变更。
 #  遵循设计部分。为此工作创建新分支。"
 ```
 
@@ -130,7 +137,8 @@ claude
 
 ```bash
 # 快速缺陷修复工作流
-cp .agents/templates/task.md .agents/workspace/active/bugfix-001.md
+mkdir -p "$TASK_WORKSPACE_ROOT/active/TASK-20260101-120000"
+cp .agents/templates/task.md "$TASK_WORKSPACE_ROOT/active/TASK-20260101-120000/task.md"
 # 编辑任务，然后：
 # 1. 使用 Claude Code 分析
 # 2. 使用 Codex/OpenCode 修复
@@ -144,7 +152,8 @@ cp .agents/templates/task.md .agents/workspace/active/bugfix-001.md
 3. **报告**：从模板生成审查报告。
 
 ```bash
-cp .agents/templates/review-report.md .agents/workspace/active/review-pr-42.md
+mkdir -p "$TASK_WORKSPACE_ROOT/active/TASK-20260101-120001"
+cp .agents/templates/review-report.md "$TASK_WORKSPACE_ROOT/active/TASK-20260101-120001/review-report.md"
 # 使用 Claude Code 填写审查内容
 ```
 
@@ -156,7 +165,8 @@ cp .agents/templates/review-report.md .agents/workspace/active/review-pr-42.md
 4. **验证**（Claude Code）：确保没有回归问题，运行测试。
 
 ```bash
-cp .agents/templates/task.md .agents/workspace/active/refactor-001.md
+mkdir -p "$TASK_WORKSPACE_ROOT/active/TASK-20260101-120002"
+cp .agents/templates/task.md "$TASK_WORKSPACE_ROOT/active/TASK-20260101-120002/task.md"
 # 按照 .agents/workflows/refactoring.yaml 中的重构工作流执行
 ```
 
@@ -165,7 +175,8 @@ cp .agents/templates/task.md .agents/workspace/active/refactor-001.md
 在 AI 工具之间切换时，创建交接文档：
 
 ```bash
-cp .agents/templates/handoff.md .agents/workspace/active/handoff-task-001-phase2.md
+mkdir -p "$TASK_WORKSPACE_ROOT/active/TASK-20260101-120003"
+cp .agents/templates/handoff.md "$TASK_WORKSPACE_ROOT/active/TASK-20260101-120003/handoff.md"
 ```
 
 填写：

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

@@ -35,24 +35,19 @@ This dual-config approach ensures every AI tool receives appropriate project con
     code-review.yaml            # Code review workflow
     refactoring.yaml            # Refactoring workflow
   rules/                        # Collaboration rule index (see rules/README.md)
-  workspace/                    # Runtime workspace (git-ignored)
-    active/                     # Currently active tasks
-    blocked/                    # Blocked tasks
-    completed/                  # Completed tasks
-    logs/                       # Collaboration logs
-
 .claude/                        # Claude Code specific config
   CLAUDE.md                     # Project instructions for Claude
   commands/                     # Slash commands
   settings.json                 # Claude settings
 ```
 
-The whole `.agents/workspace/` tree is runtime-only and git-ignored. `active/`
-contains current tasks, `blocked/` contains paused tasks, `completed/` contains
-finished tasks, and `archive/` stores archived history. Runtime logs and process
-evidence may also be created below this root. Do not place content here that must
-be shared through Git; collaboration rules, templates, and workflows belong in
-the version-controlled `.agents/` tree.
+The host task workspace root is `~/.agent-infra/task-workspaces/<project-key>`;
+the container root is `/task-workspace`. Resolve the current host root with
+`agent-infra-internal task-workspace resolve --boundary host` and a task's exact
+directory with `agent-infra-internal task-context resolve --task <task-id>`.
+`active/`, `blocked/`, `completed/`, `archive/`, and `active/.short-ids.json` live
+under that root and contain runtime data. The `<task-workspace>` placeholder used
+in these guides means the resolver's returned root; it is not a repository path.
 
 ## Collaboration Model
 
@@ -101,7 +96,7 @@ Each AI tool has different strengths. Use them accordingly:
 ## Quick Start
 
 1. **Read the quick start guide**: See `QUICKSTART.md` for step-by-step instructions.
-2. **Create a task**: Copy `.agents/templates/task.md` to `.agents/workspace/active/`.
+2. **Create a task**: Use the `create-task` workflow; the host writes task data to the project task root.
 3. **Assign to an AI**: Update the `assigned_to` field in the task metadata.
 4. **Run the workflow**: Follow the appropriate workflow in `.agents/workflows/`.
 5. **Hand off**: When switching AIs, create a handoff document from the template.
@@ -386,7 +381,7 @@ No. Claude Code reads from `.claude/CLAUDE.md`, and all other tools read from `A
 
 ### Q: How do tasks get passed between AI tools?
 
-Through handoff documents stored in `.agents/workspace/`. Each handoff includes context, progress, and next steps so the receiving AI can continue seamlessly.
+Through handoff documents stored in `<task-workspace>/`. Each handoff includes context, progress, and next steps so the receiving AI can continue seamlessly.
 
 ### Q: What if an AI tool doesn't support AGENTS.md?
 
@@ -398,4 +393,4 @@ It's not recommended. The workflow model is sequential -- one AI per phase. Para
 
 ### Q: Where are runtime files stored?
 
-In `.agents/workspace/`, which is git-ignored. Only templates and workflow definitions in `.agents/` are version-controlled.
+In `<task-workspace>/`, which is git-ignored. Only templates and workflow definitions in `.agents/` are version-controlled.

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

@@ -35,22 +35,18 @@
     code-review.yaml            # 代码审查工作流
     refactoring.yaml            # 重构工作流
   rules/                        # 协作规则索引（见 rules/README.md）
-  workspace/                    # 运行时工作区（已被 git ignore）
-    active/                     # 当前活跃任务
-    blocked/                    # 被阻塞的任务
-    completed/                  # 已完成的任务
-    logs/                       # 协作日志
-
 .claude/                        # Claude Code 专属配置
   CLAUDE.md                     # Claude 项目指令
   commands/                     # 斜杠命令
   settings.json                 # Claude 设置
 ```
 
-整个 `.agents/workspace/` 目录树都只保存运行时数据，并被 git ignore。`active/`
-保存当前任务，`blocked/` 保存暂停任务，`completed/` 保存已完成任务，`archive/`
-保存归档历史；运行时日志和过程证据也可能出现在该根目录下。不要在这里存放必须
-通过 Git 共享的内容；协作规则、模板和工作流应放在受版本控制的 `.agents/` 目录中。
+宿主任务根为 `~/.agent-infra/task-workspaces/<project-key>`，容器任务根为
+`/task-workspace`。使用 `agent-infra-internal task-workspace resolve --boundary host`
+取得当前项目的宿主根，使用 `agent-infra-internal task-context resolve --task <task-id>`
+取得某个任务的精确目录。`active/`、`blocked/`、`completed/`、`archive/` 和
+`active/.short-ids.json` 都位于任务根中；这些路径只保存运行时数据，不通过 Git
+共享。文中的 `<task-workspace>` 表示由上述 resolver 返回的根，不是仓库内目录。
 
 ## 协作模型
 
@@ -99,7 +95,7 @@
 ## 快速入门
 
 1. **阅读快速入门指南**：参见 `QUICKSTART.md` 获取分步说明。
-2. **创建任务**：将 `.agents/templates/task.md` 复制到 `.agents/workspace/active/`。
+2. **创建任务**：通过 `create-task` 工作流创建任务；任务数据由宿主写入项目任务根。
 3. **分配给 AI**：更新任务元数据中的 `assigned_to` 字段。
 4. **执行工作流**：按照 `.agents/workflows/` 中相应的工作流执行。
 5. **交接**：切换 AI 时，从模板创建交接文档。
@@ -384,7 +380,7 @@ agent-infra-internal task-verify {task-id} <verification-event> [--artifact <art
 
 ### Q：任务如何在 AI 工具之间传递？
 
-通过存储在 `.agents/workspace/` 中的交接文档。每份交接文档包含上下文、进度和后续步骤，让接收方 AI 能无缝接续。
+通过存储在 `<task-workspace>/` 中的交接文档。每份交接文档包含上下文、进度和后续步骤，让接收方 AI 能无缝接续。
 
 ### Q：如果某个 AI 工具不支持 AGENTS.md 怎么办？
 
@@ -396,4 +392,4 @@ agent-infra-internal task-verify {task-id} <verification-event> [--artifact <art
 
 ### Q：运行时文件存储在哪里？
 
-在 `.agents/workspace/` 中，该目录已被 git ignore。只有 `.agents/` 中的模板和工作流定义受版本控制。
+在 `<task-workspace>/` 中，该目录已被 git ignore。只有 `.agents/` 中的模板和工作流定义受版本控制。

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

@@ -22,7 +22,7 @@ Comments use `platform-comment`; Issue resources use `platform-issue`:
 ```bash
 agent-infra-internal platform-comment list --issue <issue-token> [--cwd <path>]
 agent-infra-internal platform-comment recover --issue <issue-token> --task-id <TASK-id> \
-  --output <.agents/workspace/.restore-staging-*/task.md> [--cwd <path>]
+  --output <<task-workspace>/.restore-staging-*/task.md> [--cwd <path>]
 agent-infra-internal platform-issue inspect {task-id}
 agent-infra-internal platform-issue create {task-id} --agent {standard-agent-token}
 agent-infra-internal platform-issue bind {task-id} --issue {issue-token} --agent {standard-agent-token}

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

@@ -26,7 +26,7 @@
 agent-infra-internal platform-context resolve [--cwd <path>]
 agent-infra-internal platform-comment list --issue <issue-token> [--cwd <path>]
 agent-infra-internal platform-comment recover --issue <issue-token> --task-id <TASK-id> \
-  --output <.agents/workspace/.restore-staging-*/task.md> [--cwd <path>]
+  --output <<task-workspace>/.restore-staging-*/task.md> [--cwd <path>]
 agent-infra-internal platform-comment owner <task-ref>
 agent-infra-internal platform-comment sync <task-ref> \
   --kind task|artifact|summary|cancel --agent {standard-agent-token} \

package/templates/.agents/rules/lifecycle-orchestration.en.md

@@ -10,7 +10,7 @@
 
 ## Current Execution Records
 
-`orchestration.json` records stages, model policy, child identity, and actual outcomes. Records use the current structure; trusted local operators may correct them and rerun validation. Existing task write locks and atomic writes protect updates.
+`orchestration.json` records stages, model policy, child identity, and actual outcomes. Records use the current structure; trusted local operators may correct them and rerun validation. Stages for one task run sequentially; atomic writes and identity/state validation continue to protect state updates.
 
 ## Current Host
 

package/templates/.agents/rules/lifecycle-orchestration.zh-CN.md

@@ -10,7 +10,7 @@
 
 ## 当前执行记录
 
-`orchestration.json` 记录阶段、模型策略、child 身份及实际执行结果。记录必须符合当前结构；本地操作者可直接修正后重新校验。已有任务写锁与原子写入继续保护写操作。
+`orchestration.json` 记录阶段、模型策略、child 身份及实际执行结果。记录必须符合当前结构；本地操作者可直接修正后重新校验。同一任务的阶段按序调用；原子写入、身份校验和状态校验继续保护状态更新。
 
 ## 当前宿主
 

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

@@ -17,7 +17,7 @@ This file defines three **independent** rules for a skill's "notify-user / Next
 
 - **Next-step TUI commands** (`/analyze-task`, `/{{project}}:review-code`, `$create-pr`, etc., including commands inside Markdown table cells) → always use `{task-ref}` (short id).
 - **"Task info" / "Task status" structured field lines** → show full id and short id together: `- Task ID: {task-id} (short id {task-ref})`.
-- **Report titles** (`Task {task-id} ... completed`) and **artifact paths** (`.agents/workspace/active/{task-id}/...`) → keep the full `{task-id}` (physical path and archive key, must not change).
+- **Report titles** (`Task {task-id} ... completed`) and **artifact paths** (`<task-workspace>/active/{task-id}/...`) → keep the full `{task-id}` (physical path and archive key, must not change).
 
 ## Unified Client Command Rendering
 
@@ -39,7 +39,7 @@ agent-infra-internal agent-client next-steps \
 
 ## Obtaining the short id (`{task-ref}`)
 
-The single source of truth for short ids is the registry `.agents/workspace/active/.short-ids.json` (via `task-short-id.js`). **Never** read the `short_id` field from task.md frontmatter (that field is not authoritative).
+The single source of truth for short ids is the registry `<task-workspace>/active/.short-ids.json` (via `task-short-id.js`). **Never** read the `short_id` field from task.md frontmatter (that field is not authoritative).
 
 Once the full `$task_id` is resolved, use the snippet below to look up the short id; it returns bare `NN` on hit and falls back to the full `TASK-id` on miss:
 

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

@@ -17,7 +17,7 @@
 
 - **下一步 TUI 命令**（`/analyze-task`、`/{{project}}:review-code`、`$create-pr` 等，含 Markdown 表格单元格内的命令）→ 一律用 `{task-ref}`（短号）。
 - **「任务信息」/「任务状态」结构化字段行** → 完整 ID 与短号同显：`- 任务 ID：{task-id}（短号 {task-ref}）`。
-- **报告标题**（`任务 {task-id} ... 完成`）与**产出文件路径**（`.agents/workspace/active/{task-id}/...`）→ 保持完整 `{task-id}`（物理路径与归档键，不可改）。
+- **报告标题**（`任务 {task-id} ... 完成`）与**产出文件路径**（`<task-workspace>/active/{task-id}/...`）→ 保持完整 `{task-id}`（物理路径与归档键，不可改）。
 
 ## 统一客户端命令渲染
 
@@ -39,7 +39,7 @@ agent-infra-internal agent-client next-steps \
 
 ## 取短号（`{task-ref}`）
 
-短号唯一真源是注册表 `.agents/workspace/active/.short-ids.json`（经 `task-short-id.js`）。**禁止**读取 task.md frontmatter 的 `short_id` 字段（该字段不可信）。
+短号唯一真源是注册表 `<task-workspace>/active/.short-ids.json`（经 `task-short-id.js`）。**禁止**读取 task.md frontmatter 的 `short_id` 字段（该字段不可信）。
 
 在已解析出完整 `$task_id` 后，用以下片段反查短号；命中返回裸数字 `NN`，未命中自动回退完整 `TASK-id`：
 

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

@@ -21,7 +21,7 @@ agent-infra-internal platform-pr change-report {task-id} \
 
 agent-infra-internal platform-pr summary-sync {task-id} \
   --agent {standard-agent-token} --body-file {summary-body-file} \
-  --change-report-file .agents/workspace/active/{task-id}/pr-change-report.json \
+  --change-report-file <task-workspace>/active/{task-id}/pr-change-report.json \
   --result {primary-result}
 ```
 

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

@@ -59,7 +59,7 @@ precheck 必须覆盖六项固定检查并提供文件证据；`formalReview`
 ```bash
 agent-infra-internal platform-pr summary-sync {task-id} \
   --agent {standard-agent-token} --body-file {summary-body-file} \
-  --change-report-file .agents/workspace/active/{task-id}/pr-change-report.json \
+  --change-report-file <task-workspace>/active/{task-id}/pr-change-report.json \
   --result {primary-result}
 ```