@fitlab-ai/agent-infra 0.9.3 → 0.9.5

package/lib/task/create-service.ts

@@ -0,0 +1,171 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { syncPlatformComment } from '../platform/issue-comments.ts';
+import { createPlatformIssue, syncPlatformIssue } from '../platform/issues.ts';
+import type { PlatformResult } from '../platform/types.ts';
+import { VERSION } from '../version.ts';
+import { applyWorkflowWarningIntent } from './workflow-warning-intents.ts';
+import { createLocalTask, type TaskCreateCandidateV1 } from './create.ts';
+import { verifyTaskEvent } from './verification.ts';
+
+type TaskCreateStatus = 'applied' | 'no-op' | 'degraded' | 'failed' | 'blocked';
+type TaskCreateOperation = { name: string; status: string; reasonCode: string | null };
+type TaskCreateWarning = { code: string; severity: string; action: string };
+type TaskCreateResult = Readonly<{
+  status: TaskCreateStatus;
+  changed: boolean;
+  task: { id: string | null; shortId: string | null };
+  issue: { number: number; url: string } | null;
+  operations: readonly TaskCreateOperation[];
+  warnings: readonly TaskCreateWarning[];
+  error: { code: string; message: string; retryable: boolean } | null;
+}>;
+
+type CreateTaskOptions = Readonly<{
+  repoRoot: string;
+  agentInfraVersion?: string;
+  dependencies?: Partial<TaskCreateDependencies>;
+}>;
+
+type TaskCreateDependencies = Readonly<{
+  createIssue: typeof createPlatformIssue;
+  syncIssue: typeof syncPlatformIssue;
+  syncComment: typeof syncPlatformComment;
+  addWarning: typeof applyWorkflowWarningIntent;
+}>;
+
+const DEFAULT_DEPENDENCIES: TaskCreateDependencies = {
+  createIssue: createPlatformIssue,
+  syncIssue: syncPlatformIssue,
+  syncComment: syncPlatformComment,
+  addWarning: applyWorkflowWarningIntent
+};
+
+function verifyCreatedTask(repoRoot: string, taskId: string): { operation: TaskCreateOperation; error: TaskCreateResult['error'] } {
+  const verification = verifyTaskEvent(
+    { taskRef: taskId, event: 'create-task.completed' },
+    { repoRoot }
+  );
+  if (verification.status === 'pass') {
+    return { operation: { name: 'task:verify', status: 'pass', reasonCode: null }, error: null };
+  }
+  const blocked = verification.status === 'blocked';
+  return {
+    operation: {
+      name: 'task:verify', status: verification.status,
+      reasonCode: verification.error?.code ?? 'TASK_CREATE_VERIFICATION_FAILED'
+    },
+    error: {
+      code: verification.error?.code ?? 'TASK_CREATE_VERIFICATION_FAILED',
+      message: `Created task did not pass the ${verification.event} gate`,
+      retryable: blocked
+    }
+  };
+}
+
+function platformOperations(prefix: string, operations: readonly { name: string; status: string; reasonCode?: string | null }[]): TaskCreateOperation[] {
+  return operations.map((operation) => ({
+    name: `${prefix}:${operation.name}`,
+    status: operation.status,
+    reasonCode: operation.reasonCode ?? null
+  }));
+}
+
+function issueFromTask(repoRoot: string, taskId: string): { number: number; url: string } | null {
+  const content = fs.readFileSync(path.join(repoRoot, '.agents', 'workspace', 'active', taskId, 'task.md'), 'utf8');
+  const match = /^issue_number:\s*(\d+)\s*$/m.exec(content);
+  return match ? { number: Number(match[1]), url: '' } : null;
+}
+
+function createTask(value: unknown, options: CreateTaskOptions): TaskCreateResult {
+  const dependencies = { ...DEFAULT_DEPENDENCIES, ...options.dependencies };
+  let candidate: TaskCreateCandidateV1;
+  let local;
+  try {
+    candidate = value as TaskCreateCandidateV1;
+    local = createLocalTask(candidate, {
+      repoRoot: options.repoRoot,
+      agentInfraVersion: options.agentInfraVersion ?? VERSION
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const code = /^([A-Z][A-Z0-9_]+)/.exec(message)?.[1] ?? 'TASK_CREATE_FAILED';
+    return {
+      status: 'failed', changed: false, task: { id: null, shortId: null }, issue: null,
+      operations: [], warnings: [], error: { code, message, retryable: code === 'TASK_CREATE_LOCK_TIMEOUT' }
+    };
+  }
+
+  const operations: TaskCreateOperation[] = [{
+    name: 'task:local', status: local.status, reasonCode: null
+  }];
+  let issue = issueFromTask(options.repoRoot, local.task.id);
+  const created = dependencies.createIssue(local.task.id, { cwd: options.repoRoot, agent: candidate.agent });
+  operations.push(...platformOperations('platform-create', created.operations));
+  if (created.issue) issue = { number: created.issue.number, url: created.issue.url };
+
+  let platformFailure: PlatformResult | null = created.status === 'failed' || created.status === 'blocked' ? created : null;
+  if (!platformFailure && (created.task.issueNumber || issue)) {
+    const synced = dependencies.syncIssue(local.task.id, {
+      cwd: options.repoRoot,
+      agent: candidate.agent,
+      status: 'waiting-for-triage',
+      assignees: 'current',
+      milestone: 'initial',
+      issueType: true,
+      fields: true
+    });
+    operations.push(...platformOperations('platform-sync', synced.operations));
+    if (synced.issue) issue = { number: synced.issue.number, url: synced.issue.url };
+    if (synced.status === 'failed' || synced.status === 'blocked') platformFailure = synced;
+    if (!platformFailure) {
+      const commented = dependencies.syncComment(local.task.id, { cwd: options.repoRoot, kind: 'task', agent: candidate.agent });
+      operations.push(...platformOperations('platform-comment', commented.operations));
+      if (commented.status === 'failed' || commented.status === 'blocked') platformFailure = commented;
+    }
+  }
+
+  if (platformFailure) {
+    const error = platformFailure.error ?? { code: 'ISSUE_CREATE_FAILED', message: 'Platform operation failed', retryable: false };
+    dependencies.addWarning({
+      kind: 'add', taskRef: local.task.id, step: 'create-task', severity: 'ACTION_REQUIRED',
+      code: 'ISSUE_CREATE_FAILED', target: 'issue', message: `${error.code}: ${error.message}`,
+      action: 'Fix platform authentication or connectivity, then retry Issue creation for this task.'
+    }, { repoRoot: options.repoRoot });
+    const verified = verifyCreatedTask(options.repoRoot, local.task.id);
+    operations.push(verified.operation);
+    if (verified.error) return {
+      status: verified.error.retryable ? 'blocked' : 'failed', changed: local.changed,
+      task: local.task, issue, operations, warnings: [], error: verified.error
+    };
+    return {
+      status: platformFailure.status === 'blocked' ? 'blocked' : 'degraded',
+      changed: local.changed,
+      task: local.task,
+      issue,
+      operations,
+      warnings: [{ code: 'ISSUE_CREATE_FAILED', severity: 'ACTION_REQUIRED', action: 'Retry Issue creation after fixing the platform failure.' }],
+      error
+    };
+  }
+
+  const verified = verifyCreatedTask(options.repoRoot, local.task.id);
+  operations.push(verified.operation);
+  if (verified.error) return {
+    status: verified.error.retryable ? 'blocked' : 'failed', changed: local.changed,
+    task: local.task, issue, operations, warnings: [], error: verified.error
+  };
+  return {
+    status: local.status,
+    changed: local.changed,
+    task: local.task,
+    issue,
+    operations,
+    warnings: [],
+    error: null
+  };
+}
+
+export { createTask };
+export type { CreateTaskOptions, TaskCreateDependencies, TaskCreateOperation, TaskCreateResult, TaskCreateStatus, TaskCreateWarning };

package/lib/task/create.ts

@@ -0,0 +1,372 @@
+import { createHash, randomUUID } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { loadShortIdByTaskId, mutateShortIdRegistry } from './short-id.ts';
+import { TaskExecutionLockError, withTaskExecutionLock } from './task-execution-lock.ts';
+
+const AGENTS = ['claude', 'codex', 'antigravity', 'opencode', 'cursor'] as const;
+const TYPES = ['feature', 'bugfix', 'refactor', 'docs', 'chore'] as const;
+const PRIORITIES = ['Urgent', 'High', 'Medium', 'Low'] as const;
+const EFFORTS = ['High', 'Medium', 'Low'] as const;
+const TASK_INPUT_KEYS = [
+  'sources', 'facts', 'constraints', 'decisions', 'alternatives',
+  'acceptanceCriteria', 'openQuestions'
+] as const;
+
+type TaskAgent = typeof AGENTS[number];
+type TaskType = typeof TYPES[number];
+type TaskPriority = typeof PRIORITIES[number];
+type TaskEffort = typeof EFFORTS[number];
+
+type TaskCreateCandidateV1 = Readonly<{
+  version: 1;
+  idempotencyKey: string;
+  agent: TaskAgent;
+  title: string;
+  type: TaskType;
+  branchSlug: string;
+  priority: TaskPriority;
+  effort: TaskEffort;
+  description: string;
+  taskInput: Readonly<Record<typeof TASK_INPUT_KEYS[number], readonly string[]>>;
+}>;
+
+type LocalTaskCreateResult = Readonly<{
+  status: 'applied' | 'no-op';
+  changed: boolean;
+  task: { id: string; shortId: string };
+}>;
+
+type LocalTaskCreateOptions = Readonly<{
+  repoRoot: string;
+  now?: () => Date;
+  agentInfraVersion?: string;
+}>;
+
+function payloadError(message: string): never {
+  throw new Error(`TASK_CREATE_PAYLOAD_INVALID: ${message}`);
+}
+
+function exactKeys(value: Record<string, unknown>, expected: readonly string[], label: string): void {
+  const actual = Object.keys(value).sort();
+  const wanted = [...expected].sort();
+  if (actual.length !== wanted.length || actual.some((key, index) => key !== wanted[index])) {
+    payloadError(`${label} has unknown or missing fields`);
+  }
+}
+
+function cleanString(value: unknown, label: string, maxBytes: number, oneLine = false): string {
+  if (typeof value !== 'string' || value.length === 0 || Buffer.byteLength(value, 'utf8') > maxBytes) {
+    payloadError(`${label} must be a non-empty string within ${maxBytes} bytes`);
+  }
+  if (/\0|[\u0001-\u0008\u000b\u000c\u000e-\u001f\u007f]/u.test(value) || (oneLine && /[\r\n]/u.test(value))) {
+    payloadError(`${label} contains unsupported control characters`);
+  }
+  return value;
+}
+
+function enumValue<T extends string>(value: unknown, allowed: readonly T[], label: string): T {
+  if (typeof value !== 'string' || !allowed.includes(value as T)) payloadError(`${label} is invalid`);
+  return value as T;
+}
+
+function validateTaskCreateCandidate(value: unknown): TaskCreateCandidateV1 {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) payloadError('candidate must be an object');
+  const candidate = value as Record<string, unknown>;
+  exactKeys(candidate, [
+    'version', 'idempotencyKey', 'agent', 'title', 'type', 'branchSlug',
+    'priority', 'effort', 'description', 'taskInput'
+  ], 'candidate');
+  if (candidate.version !== 1) payloadError('version must be 1');
+  const idempotencyKey = cleanString(candidate.idempotencyKey, 'idempotencyKey', 64, true);
+  if (!/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(idempotencyKey)) {
+    payloadError('idempotencyKey must be a UUID v4');
+  }
+  const title = cleanString(candidate.title, 'title', 400, true);
+  if ([...title].length > 100) payloadError('title exceeds 100 Unicode code points');
+  const branchSlug = cleanString(candidate.branchSlug, 'branchSlug', 64, true);
+  if (!/^[a-z0-9]+(?:-[a-z0-9]+)+$/.test(branchSlug) || branchSlug.length < 3) {
+    payloadError('branchSlug must be lowercase ASCII kebab-case with length 3-64');
+  }
+  const description = cleanString(candidate.description, 'description', 8 * 1024);
+  if (!candidate.taskInput || typeof candidate.taskInput !== 'object' || Array.isArray(candidate.taskInput)) {
+    payloadError('taskInput must be an object');
+  }
+  const rawInput = candidate.taskInput as Record<string, unknown>;
+  exactKeys(rawInput, TASK_INPUT_KEYS, 'taskInput');
+  const taskInput = Object.fromEntries(TASK_INPUT_KEYS.map((key) => {
+    const list = rawInput[key];
+    if (!Array.isArray(list) || list.length > 50) payloadError(`taskInput.${key} must contain at most 50 items`);
+    return [key, list.map((item, index) => cleanString(item, `taskInput.${key}[${index}]`, 2 * 1024, true))];
+  })) as unknown as TaskCreateCandidateV1['taskInput'];
+  return {
+    version: 1,
+    idempotencyKey,
+    agent: enumValue(candidate.agent, AGENTS, 'agent'),
+    title,
+    type: enumValue(candidate.type, TYPES, 'type'),
+    branchSlug,
+    priority: enumValue(candidate.priority, PRIORITIES, 'priority'),
+    effort: enumValue(candidate.effort, EFFORTS, 'effort'),
+    description,
+    taskInput
+  };
+}
+
+function canonicalTaskCreateCandidate(candidate: TaskCreateCandidateV1): string {
+  const valid = validateTaskCreateCandidate(candidate);
+  return JSON.stringify({
+    version: valid.version,
+    idempotencyKey: valid.idempotencyKey,
+    agent: valid.agent,
+    title: valid.title,
+    type: valid.type,
+    branchSlug: valid.branchSlug,
+    priority: valid.priority,
+    effort: valid.effort,
+    description: valid.description,
+    taskInput: Object.fromEntries(TASK_INPUT_KEYS.map((key) => [key, valid.taskInput[key]]))
+  });
+}
+
+function sha256(value: string): string {
+  return createHash('sha256').update(value).digest('hex');
+}
+
+function formatTimestamp(date: Date): string {
+  const pad = (value: number) => String(value).padStart(2, '0');
+  const offsetMinutes = -date.getTimezoneOffset();
+  const sign = offsetMinutes >= 0 ? '+' : '-';
+  const offset = Math.abs(offsetMinutes);
+  return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())} ${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}${sign}${pad(Math.floor(offset / 60))}:${pad(offset % 60)}`;
+}
+
+function taskIdFor(date: Date): string {
+  const pad = (value: number) => String(value).padStart(2, '0');
+  return `TASK-${date.getFullYear()}${pad(date.getMonth() + 1)}${pad(date.getDate())}-${pad(date.getHours())}${pad(date.getMinutes())}${pad(date.getSeconds())}`;
+}
+
+function yamlString(value: string): string {
+  return JSON.stringify(value);
+}
+
+function markdownBlock(value: string): string {
+  return value.split(/\r?\n/).map((line) => /^(?:#{1,6}\s|```)/.test(line) ? `\\${line}` : line).join('\n');
+}
+
+function renderList(items: readonly string[]): string {
+  return items.map((item) => `- ${item}`).join('\n');
+}
+
+function replaceEmptySubsection(content: string, heading: string, items: readonly string[]): string {
+  if (items.length === 0) return content;
+  return content.replace(`${heading}\n`, `${heading}\n\n${renderList(items)}\n`);
+}
+
+function renderTask(params: Readonly<{
+  template: string;
+  candidate: TaskCreateCandidateV1;
+  taskId: string;
+  project: string;
+  timestamp: string;
+  agentInfraVersion: string;
+  keyDigest: string;
+  candidateDigest: string;
+}>): string {
+  const { candidate } = params;
+  const workflow = candidate.type === 'bugfix' ? 'bug-fix' : candidate.type === 'refactor' ? 'refactoring' : 'feature-development';
+  const branch = `${params.project}-${candidate.type}-${candidate.branchSlug}`;
+  const frontmatter = [
+    '---',
+    `id: ${params.taskId}`,
+    `type: ${candidate.type}`,
+    `branch: ${branch}`,
+    `workflow: ${workflow}`,
+    'status: active',
+    `created_at: ${params.timestamp}`,
+    `updated_at: ${params.timestamp}`,
+    `agent_infra_version: ${params.agentInfraVersion}`,
+    `priority: ${candidate.priority}`,
+    `effort: ${candidate.effort}`,
+    'start_date:',
+    'target_date:',
+    'current_step: requirement-analysis',
+    `assigned_to: ${candidate.agent}`,
+    'pr_status: pending',
+    `task_create_key_digest: ${params.keyDigest}`,
+    `task_create_candidate_digest: ${params.candidateDigest}`,
+    '---'
+  ].join('\n');
+  let content = params.template.replace(/^---\n[\s\S]*?\n---/, frontmatter);
+  content = content.replace('# 任务：[标题]', `# 任务：${candidate.title}`);
+  content = content.replace('[清晰简洁地描述任务。]', markdownBlock(candidate.description));
+  const sections: Array<[string, keyof TaskCreateCandidateV1['taskInput']]> = [
+    ['### 来源', 'sources'], ['### 已确认事实与证据', 'facts'], ['### 约束', 'constraints'],
+    ['### 已确认决策', 'decisions'], ['### 候选与否决方案', 'alternatives'],
+    ['### 验收标准', 'acceptanceCriteria'], ['### 未决事项', 'openQuestions']
+  ];
+  for (const [heading, key] of sections) content = replaceEmptySubsection(content, heading, candidate.taskInput[key]);
+  content = content.replace('- **关联 Issue**：#XXX', '- **关联 Issue**：N/A');
+  content = content.replace('- **关联 PR**：#XXX', '- **关联 PR**：N/A');
+  content = content.replace('- **分支**：`feature/xxx`', `- **分支**：\`${branch}\``);
+  const log = [
+    `- ${params.timestamp} — **Create Task [started]** by ${candidate.agent} — started`,
+    `- ${params.timestamp} — **Create Task** by ${candidate.agent} — Task created from structured candidate`
+  ].join('\n');
+  content = content.replace('\n## 完成检查清单', `\n${log}\n\n## 完成检查清单`);
+  return `${content.trimEnd()}\n`;
+}
+
+function readProject(repoRoot: string): string {
+  const config = JSON.parse(fs.readFileSync(path.join(repoRoot, '.agents', '.airc.json'), 'utf8')) as { project?: unknown };
+  if (typeof config.project !== 'string' || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(config.project)) {
+    throw new Error('TASK_CREATE_CONFIG_INVALID: project is missing or invalid');
+  }
+  return config.project;
+}
+
+function assertRealDirectory(directory: string, code: string): void {
+  const stat = fs.lstatSync(directory);
+  if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error(code);
+}
+
+function withCreateLock<T>(repoRoot: string, workspaceRoot: string, operation: () => T): T {
+  const lockRoot = path.join(workspaceRoot, '.task-create.lock');
+  fs.mkdirSync(lockRoot, { recursive: true, mode: 0o700 });
+  assertRealDirectory(lockRoot, 'TASK_CREATE_LOCK_FAILED');
+  let callbackError: unknown;
+  try {
+    return withTaskExecutionLock(repoRoot, 'task-create', 'task-create', () => {
+      try { return operation(); }
+      catch (error) { callbackError = error; throw error; }
+    }, { lockRoot });
+  } catch (error) {
+    if (callbackError !== undefined) throw callbackError;
+    if (error instanceof TaskExecutionLockError && error.code === 'ORCHESTRATION_LOCK_BUSY') {
+      throw new Error('TASK_CREATE_LOCK_TIMEOUT');
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`TASK_CREATE_LOCK_FAILED: ${message}`);
+  }
+}
+
+function writeReceipt(receiptPath: string, value: unknown): void {
+  const temporary = `${receiptPath}.tmp.${process.pid}.${randomUUID()}`;
+  fs.writeFileSync(temporary, `${JSON.stringify(value)}\n`, { flag: 'wx', mode: 0o600 });
+  try { fs.renameSync(temporary, receiptPath); }
+  catch (error) {
+    try { fs.unlinkSync(temporary); } catch { /* best effort */ }
+    throw error;
+  }
+}
+
+function recoverPublishedTask(activeRoot: string, repoRoot: string, keyDigest: string, candidateDigest: string): { taskId: string; shortId: string } | null {
+  for (const name of fs.readdirSync(activeRoot)) {
+    if (!/^TASK-\d{8}-\d{6}$/.test(name)) continue;
+    const taskDir = path.join(activeRoot, name);
+    const stat = fs.lstatSync(taskDir);
+    if (!stat.isDirectory() || stat.isSymbolicLink()) continue;
+    const taskMd = path.join(taskDir, 'task.md');
+    if (!fs.existsSync(taskMd)) continue;
+    const taskStat = fs.lstatSync(taskMd);
+    if (!taskStat.isFile() || taskStat.isSymbolicLink()) continue;
+    const content = fs.readFileSync(taskMd, 'utf8');
+    if (!content.includes(`task_create_key_digest: ${keyDigest}`)) continue;
+    if (!content.includes(`task_create_candidate_digest: ${candidateDigest}`)) {
+      throw new Error('TASK_CREATE_IDEMPOTENCY_CONFLICT');
+    }
+    const shortId = loadShortIdByTaskId(repoRoot).get(name)
+      ?? mutateShortIdRegistry(repoRoot, name, 'alloc').shortId;
+    if (!shortId) throw new Error('TASK_CREATE_RECEIPT_INVALID');
+    return { taskId: name, shortId };
+  }
+  return null;
+}
+
+function createLocalTask(value: unknown, options: LocalTaskCreateOptions): LocalTaskCreateResult {
+  const candidate = validateTaskCreateCandidate(value);
+  const repoRoot = fs.realpathSync.native(options.repoRoot);
+  const workspaceRoot = path.join(repoRoot, '.agents', 'workspace');
+  const activeRoot = path.join(workspaceRoot, 'active');
+  assertRealDirectory(workspaceRoot, 'TASK_CREATE_WORKSPACE_INVALID');
+  assertRealDirectory(activeRoot, 'TASK_CREATE_WORKSPACE_INVALID');
+  const project = readProject(repoRoot);
+  const canonical = canonicalTaskCreateCandidate(candidate);
+  const candidateDigest = sha256(canonical);
+  const keyDigest = sha256(candidate.idempotencyKey);
+  const receipts = path.join(workspaceRoot, '.task-create');
+
+  return withCreateLock(repoRoot, workspaceRoot, () => {
+    if (fs.existsSync(receipts)) assertRealDirectory(receipts, 'TASK_CREATE_RECEIPT_INVALID');
+    else fs.mkdirSync(receipts, { mode: 0o700 });
+    const receiptPath = path.join(receipts, `${keyDigest}.json`);
+    if (fs.existsSync(receiptPath)) {
+      const stat = fs.lstatSync(receiptPath);
+      if (!stat.isFile() || stat.isSymbolicLink()) throw new Error('TASK_CREATE_RECEIPT_INVALID');
+      const receipt = JSON.parse(fs.readFileSync(receiptPath, 'utf8')) as { candidateDigest?: string; taskId?: string; shortId?: string };
+      if (receipt.candidateDigest !== candidateDigest) throw new Error('TASK_CREATE_IDEMPOTENCY_CONFLICT');
+      if (!receipt.taskId || !receipt.shortId || !fs.existsSync(path.join(activeRoot, receipt.taskId, 'task.md'))) {
+        throw new Error('TASK_CREATE_RECEIPT_INVALID');
+      }
+      return { status: 'no-op', changed: false, task: { id: receipt.taskId, shortId: receipt.shortId } };
+    }
+
+    const recovered = recoverPublishedTask(activeRoot, repoRoot, keyDigest, candidateDigest);
+    if (recovered) {
+      writeReceipt(receiptPath, {
+        version: 1, candidateDigest, taskId: recovered.taskId, shortId: recovered.shortId, status: 'recovered'
+      });
+      return { status: 'no-op', changed: false, task: { id: recovered.taskId, shortId: recovered.shortId } };
+    }
+
+    const base = options.now?.() ?? new Date();
+    let taskDate = new Date(base.getTime());
+    let taskId = taskIdFor(taskDate);
+    while (fs.existsSync(path.join(activeRoot, taskId))) {
+      taskDate = new Date(taskDate.getTime() + 1_000);
+      taskId = taskIdFor(taskDate);
+    }
+    const timestamp = formatTimestamp(base);
+    const templatePath = path.join(repoRoot, '.agents', 'templates', 'task.md');
+    const templateStat = fs.lstatSync(templatePath);
+    if (!templateStat.isFile() || templateStat.isSymbolicLink()) throw new Error('TASK_CREATE_TEMPLATE_INVALID');
+    const rendered = renderTask({
+      template: fs.readFileSync(templatePath, 'utf8'), candidate, taskId, project, timestamp,
+      agentInfraVersion: options.agentInfraVersion ?? 'unknown', keyDigest, candidateDigest
+    });
+    const temporary = path.join(workspaceRoot, `.task-create.tmp.${process.pid}.${randomUUID()}`);
+    fs.mkdirSync(temporary, { mode: 0o700 });
+    fs.writeFileSync(path.join(temporary, 'task.md'), rendered, { flag: 'wx', mode: 0o600 });
+    const destination = path.join(activeRoot, taskId);
+    fs.renameSync(temporary, destination);
+    let shortId: string;
+    try {
+      const allocated = mutateShortIdRegistry(repoRoot, taskId, 'alloc');
+      if (!allocated.shortId) throw new Error('TASK_CREATE_SHORT_ID_FAILED');
+      shortId = allocated.shortId;
+    } catch (error) {
+      fs.rmSync(destination, { recursive: true, force: true });
+      throw error;
+    }
+    try {
+      writeReceipt(receiptPath, { version: 1, candidateDigest, taskId, shortId, status: 'created' });
+    } catch (error) {
+      mutateShortIdRegistry(repoRoot, taskId, 'release');
+      fs.rmSync(destination, { recursive: true, force: true });
+      throw error;
+    }
+    return { status: 'applied', changed: true, task: { id: taskId, shortId } };
+  });
+}
+
+export {
+  canonicalTaskCreateCandidate,
+  createLocalTask,
+  validateTaskCreateCandidate
+};
+export type {
+  LocalTaskCreateOptions,
+  LocalTaskCreateResult,
+  TaskCreateCandidateV1
+};

package/lib/task/decision-intents.ts

@@ -4,9 +4,11 @@ import { appendActivityEntry, locateActivityLog } from './activity-log.ts';
 import { isDecisionItem, listDecisionItems, selectDecisionItem } from './decision-items.ts';
 import {
   createImplementationInput,
+  finalizeImplementationInput,
   IMPLEMENTATION_INPUT_ALIASES,
   parseImplementationInputs,
-  renderImplementationInputs
+  renderImplementationInputs,
+  selectDeclaredImplementationInput
 } from './implementation-inputs.ts';
 import { LEDGER_COLUMNS, LEDGER_HEADINGS, parseLedger } from './ledger.ts';
 import type { LedgerRow } from './ledger.ts';
@@ -73,7 +75,7 @@ function existingDecision(
     ? { recordId, implementationInputId: null }
     : { conflict: '--needs-implementation is only valid for code-stage decisions' };
   const inputs = parseImplementationInputs(content).rows.filter((input) => input.ledgerId === row.id && input.decisionEvidence === row.evidence);
-  if (inputs.length !== 1 || inputs[0]!.needsImplementation !== needsImplementation) {
+  if (inputs.length !== 1 || (needsImplementation !== undefined && inputs[0]!.needsImplementation !== needsImplementation)) {
     return { conflict: `implementation intent for '${row.id}' conflicts with the existing decision` };
   }
   return { recordId, implementationInputId: inputs[0]!.id };
@@ -106,9 +108,28 @@ function applyHumanDecision(request: HumanDecisionRequest, options: TaskWriteOpt
     return failed('DECISION_TARGET_INVALID', message, resolved.taskId);
   }
   const row = selected.row;
-  if (row.stage === 'code' && request.needsImplementation === undefined) return failed('DECISION_PAYLOAD_INVALID', 'code-stage decisions require --needs-implementation true|false', resolved.taskId, row.id);
   if (row.stage !== 'code' && request.needsImplementation !== undefined) return failed('DECISION_PAYLOAD_INVALID', '--needs-implementation is only valid for code-stage decisions', resolved.taskId, row.id);
 
+  let parsedInputs: ReturnType<typeof parseImplementationInputs> | null = null;
+  let declaredInput: ReturnType<typeof selectDeclaredImplementationInput> = null;
+  let effectiveNeedsImplementation = request.needsImplementation;
+  if (row.stage === 'code') {
+    try {
+      parsedInputs = parseImplementationInputs(content);
+      declaredInput = selectDeclaredImplementationInput(parsedInputs.rows, row.id, row.evidence);
+    } catch (error) {
+      return failed('DECISION_DOCUMENT_INVALID', error instanceof Error ? error.message : String(error), resolved.taskId, row.id);
+    }
+    if (declaredInput) {
+      if (request.needsImplementation !== undefined && request.needsImplementation !== declaredInput.needsImplementation) {
+        return failed('DECISION_CONFLICT', `implementation intent for '${row.id}' conflicts with its declaration`, resolved.taskId, row.id);
+      }
+      effectiveNeedsImplementation = declaredInput.needsImplementation;
+    } else if (effectiveNeedsImplementation === undefined) {
+      return failed('DECISION_PAYLOAD_INVALID', 'code-stage decisions require --needs-implementation true|false when no implementation intent was declared', resolved.taskId, row.id);
+    }
+  }
+
   let metadata;
   try { metadata = (options.metadataProvider ?? captureTaskWriteMetadata)(); }
   catch (error) { return failed('METADATA_CAPTURE_FAILED', error instanceof Error ? error.message : String(error), resolved.taskId, row.id); }
@@ -132,18 +153,17 @@ function applyHumanDecision(request: HumanDecisionRequest, options: TaskWriteOpt
   ];
   let implementationInputId: string | null = null;
   if (row.stage === 'code') {
-    let parsed;
-    try { parsed = parseImplementationInputs(content); }
-    catch (error) { return failed('DECISION_DOCUMENT_INVALID', error instanceof Error ? error.message : String(error), resolved.taskId, row.id); }
-    const input = createImplementationInput(parsed.rows, {
-      ledgerId: row.id, decisionEvidence: evidence,
-      needsImplementation: request.needsImplementation!, decidedAt: metadata.timestamp
-    });
-    implementationInputId = input.id;
+    const nextInputs = declaredInput
+      ? finalizeImplementationInput(parsedInputs!.rows, declaredInput.id, evidence, metadata.timestamp)
+      : [...parsedInputs!.rows, createImplementationInput(parsedInputs!.rows, {
+          ledgerId: row.id, decisionEvidence: evidence,
+          needsImplementation: effectiveNeedsImplementation!, decidedAt: metadata.timestamp
+        })];
+    implementationInputId = declaredInput?.id ?? nextInputs[nextInputs.length - 1]!.id;
     mutations.push({
       kind: 'section', aliases: IMPLEMENTATION_INPUT_ALIASES,
       heading: findSectionHeading(content, [...IMPLEMENTATION_INPUT_ALIASES]),
-      body: renderImplementationInputs([...parsed.rows, input])
+      body: renderImplementationInputs(nextInputs)
     });
   }
   mutations.push({

package/lib/task/delegation-receipts.ts

@@ -1,6 +1,7 @@
 import { randomUUID } from 'node:crypto';
 
 import type { AgentClientId } from '../agent-clients/types.ts';
+import { normalizeAgentToken } from '../agent-clients/tokens.ts';
 
 type DelegationRole = 'executor' | 'reviewer';
 type DelegationStage = 'analysis' | 'review-analysis' | 'plan' | 'review-plan' | 'code' | 'review-code' | 'commit';
@@ -145,8 +146,7 @@ function completeDelegationStage(
   if (event.stage !== receipt.stage || event.round !== receipt.round || event.artifact !== receipt.artifact) {
     return fail('DELEGATION_STAGE_MISMATCH', 'stage completion identity does not match the active delegation');
   }
-  const acceptedAgents = receipt.client === 'claude-code' ? ['claude', 'claude-code'] : [receipt.client];
-  if (!acceptedAgents.includes(event.agent)) {
+  if (normalizeAgentToken(event.agent) !== normalizeAgentToken(receipt.client)) {
     return fail('DELEGATION_AGENT_MISMATCH', `stage agent '${event.agent}' does not match client '${receipt.client}'`);
   }
   return { ok: true, receipt: Object.freeze({ ...receipt, status: 'stage-completed', agent: event.agent }) };