@fitlab-ai/agent-infra 0.9.3 → 0.9.5

package/dist/lib/task/create.js

@@ -0,0 +1,333 @@
+import { createHash, randomUUID } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { loadShortIdByTaskId, mutateShortIdRegistry } from './short-id.js';
+import { TaskExecutionLockError, withTaskExecutionLock } from './task-execution-lock.js';
+const AGENTS = ['claude', 'codex', 'antigravity', 'opencode', 'cursor'];
+const TYPES = ['feature', 'bugfix', 'refactor', 'docs', 'chore'];
+const PRIORITIES = ['Urgent', 'High', 'Medium', 'Low'];
+const EFFORTS = ['High', 'Medium', 'Low'];
+const TASK_INPUT_KEYS = [
+    'sources', 'facts', 'constraints', 'decisions', 'alternatives',
+    'acceptanceCriteria', 'openQuestions'
+];
+function payloadError(message) {
+    throw new Error(`TASK_CREATE_PAYLOAD_INVALID: ${message}`);
+}
+function exactKeys(value, expected, label) {
+    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, label, maxBytes, oneLine = false) {
+    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(value, allowed, label) {
+    if (typeof value !== 'string' || !allowed.includes(value))
+        payloadError(`${label} is invalid`);
+    return value;
+}
+function validateTaskCreateCandidate(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        payloadError('candidate must be an object');
+    const candidate = value;
+    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;
+    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))];
+    }));
+    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) {
+    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) {
+    return createHash('sha256').update(value).digest('hex');
+}
+function formatTimestamp(date) {
+    const pad = (value) => 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) {
+    const pad = (value) => 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) {
+    return JSON.stringify(value);
+}
+function markdownBlock(value) {
+    return value.split(/\r?\n/).map((line) => /^(?:#{1,6}\s|```)/.test(line) ? `\\${line}` : line).join('\n');
+}
+function renderList(items) {
+    return items.map((item) => `- ${item}`).join('\n');
+}
+function replaceEmptySubsection(content, heading, items) {
+    if (items.length === 0)
+        return content;
+    return content.replace(`${heading}\n`, `${heading}\n\n${renderList(items)}\n`);
+}
+function renderTask(params) {
+    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 = [
+        ['### 来源', '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) {
+    const config = JSON.parse(fs.readFileSync(path.join(repoRoot, '.agents', '.airc.json'), 'utf8'));
+    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, code) {
+    const stat = fs.lstatSync(directory);
+    if (!stat.isDirectory() || stat.isSymbolicLink())
+        throw new Error(code);
+}
+function withCreateLock(repoRoot, workspaceRoot, operation) {
+    const lockRoot = path.join(workspaceRoot, '.task-create.lock');
+    fs.mkdirSync(lockRoot, { recursive: true, mode: 0o700 });
+    assertRealDirectory(lockRoot, 'TASK_CREATE_LOCK_FAILED');
+    let callbackError;
+    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, value) {
+    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, repoRoot, keyDigest, candidateDigest) {
+    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, options) {
+    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'));
+            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;
+        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 };
+//# sourceMappingURL=create.js.map

package/dist/lib/task/decision-intents.js

@@ -1,7 +1,7 @@
 import fs from 'node:fs';
 import { appendActivityEntry, locateActivityLog } from './activity-log.js';
 import { isDecisionItem, listDecisionItems, selectDecisionItem } from './decision-items.js';
-import { createImplementationInput, IMPLEMENTATION_INPUT_ALIASES, parseImplementationInputs, renderImplementationInputs } from './implementation-inputs.js';
+import { createImplementationInput, finalizeImplementationInput, IMPLEMENTATION_INPUT_ALIASES, parseImplementationInputs, renderImplementationInputs, selectDeclaredImplementationInput } from './implementation-inputs.js';
 import { LEDGER_COLUMNS, LEDGER_HEADINGS, parseLedger } from './ledger.js';
 import { resolveTaskContext } from './resolve-ref.js';
 import { extractSection, extractSubSection, findSectionHeading } from './sections.js';
@@ -45,7 +45,7 @@ function existingDecision(content, row, decision, needsImplementation) {
             ? { 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 };
@@ -87,10 +87,29 @@ function applyHumanDecision(request, options = {}) {
         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 = null;
+    let declaredInput = 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)();
@@ -119,22 +138,17 @@ function applyHumanDecision(request, options = {}) {
     ];
     let implementationInputId = 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/dist/lib/task/delegation-receipts.js

@@ -1,4 +1,5 @@
 import { randomUUID } from 'node:crypto';
+import { normalizeAgentToken } from '../agent-clients/tokens.js';
 const MANAGED_AGENTS = {
     'agent-infra-lifecycle-executor': 'executor',
     'agent-infra-lifecycle-reviewer': 'reviewer'
@@ -83,8 +84,7 @@ function completeDelegationStage(receipt, event) {
     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 }) };

package/dist/lib/task/implementation-inputs.js

@@ -13,12 +13,11 @@ function validateInput(row) {
         throw new Error(`implementation input ${row.id} has incomplete decision identity`);
     if (row.stage !== 'code')
         throw new Error(`implementation input ${row.id} has invalid stage`);
-    if (!TIMESTAMP_RE.test(row.decidedAt) || !Number.isFinite(Date.parse(row.decidedAt.replace(' ', 'T')))) {
-        throw new Error(`implementation input ${row.id} has invalid decided_at`);
-    }
-    const valid = (row.needsImplementation && row.status === 'pending' && row.consumedBy === '') ||
-        (!row.needsImplementation && row.status === 'not-required' && row.consumedBy === '') ||
-        (row.needsImplementation && row.status === 'consumed' && ARTIFACT_RE.test(row.consumedBy));
+    const hasValidTimestamp = TIMESTAMP_RE.test(row.decidedAt) && Number.isFinite(Date.parse(row.decidedAt.replace(' ', 'T')));
+    const valid = (row.status === 'declared' && row.decidedAt === '' && row.consumedBy === '') ||
+        (hasValidTimestamp && row.needsImplementation && row.status === 'pending' && row.consumedBy === '') ||
+        (hasValidTimestamp && !row.needsImplementation && row.status === 'not-required' && row.consumedBy === '') ||
+        (hasValidTimestamp && row.needsImplementation && row.status === 'consumed' && ARTIFACT_RE.test(row.consumedBy));
     if (!valid)
         throw new Error(`implementation input ${row.id} has an invalid state combination`);
 }
@@ -67,6 +66,54 @@ function createImplementationInput(rows, draft) {
     validateInput(row);
     return row;
 }
+function declareImplementationInput(rows, draft) {
+    const existing = rows.filter((row) => row.ledgerId === draft.ledgerId && row.status === 'declared');
+    if (existing.length > 1)
+        throw new Error(`implementation input declaration for '${draft.ledgerId}' conflicts with existing rows`);
+    if (existing.length === 1) {
+        const row = existing[0];
+        if (row.decisionEvidence !== draft.decisionEvidence || row.needsImplementation !== draft.needsImplementation) {
+            throw new Error(`implementation input declaration for '${draft.ledgerId}' conflicts with the existing row`);
+        }
+        return row;
+    }
+    const row = {
+        id: nextId(rows), ledgerId: draft.ledgerId, decisionEvidence: draft.decisionEvidence,
+        stage: 'code', needsImplementation: draft.needsImplementation, decidedAt: '',
+        status: 'declared', consumedBy: ''
+    };
+    validateInput(row);
+    return row;
+}
+function selectDeclaredImplementationInput(rows, ledgerId, decisionEvidence) {
+    const forLedger = rows.filter((row) => row.ledgerId === ledgerId && row.status === 'declared');
+    if (forLedger.length > 1)
+        throw new Error(`implementation input declaration for '${ledgerId}' is ambiguous`);
+    if (forLedger.length === 0)
+        return null;
+    if (forLedger[0].decisionEvidence !== decisionEvidence) {
+        throw new Error(`implementation input declaration for '${ledgerId}' has conflicting evidence`);
+    }
+    return forLedger[0];
+}
+function finalizeImplementationInput(rows, id, decisionEvidence, decidedAt) {
+    let found = false;
+    const next = rows.map((row) => {
+        if (row.id !== id)
+            return row;
+        found = true;
+        if (row.status !== 'declared')
+            throw new Error(`implementation input ${id} is not declared`);
+        return {
+            ...row, decisionEvidence, decidedAt,
+            status: row.needsImplementation ? 'pending' : 'not-required'
+        };
+    });
+    if (!found)
+        throw new Error(`implementation input ${id} was not found`);
+    next.forEach(validateInput);
+    return next;
+}
 function selectPendingImplementationInput(rows, reviewCompletedAt) {
     const reviewEpoch = Date.parse(reviewCompletedAt.replace(' ', 'T'));
     if (!Number.isFinite(reviewEpoch))
@@ -113,5 +160,5 @@ function renderImplementationInputs(rows) {
         })
     ].join('\n');
 }
-export { SECTION_ALIASES as IMPLEMENTATION_INPUT_ALIASES, createImplementationInput, consumeImplementationInput, parseImplementationInputs, renderImplementationInputs, selectPendingImplementationInput };
+export { SECTION_ALIASES as IMPLEMENTATION_INPUT_ALIASES, createImplementationInput, consumeImplementationInput, declareImplementationInput, finalizeImplementationInput, parseImplementationInputs, renderImplementationInputs, selectDeclaredImplementationInput, selectPendingImplementationInput };
 //# sourceMappingURL=implementation-inputs.js.map

package/dist/lib/task/ledger-intents.js

@@ -1,5 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { declareImplementationInput, IMPLEMENTATION_INPUT_ALIASES, parseImplementationInputs, renderImplementationInputs } from './implementation-inputs.js';
 import { LEDGER_COLUMNS, LEDGER_HEADINGS, nextHdId, parseLedger, validateLedgerRows } from './ledger.js';
 import { resolveTaskRef } from './resolve-ref.js';
 import { writeTask } from './write.js';
@@ -66,6 +67,14 @@ function ledgerSectionMutation(content) {
             body: `| ${LEDGER_COLUMNS.join(' | ')} |\n|----|-------|-------|----------|--------|----------|`
         }];
 }
+function implementationInputMutation(content, rows) {
+    const english = /^##\s+Activity Log\s*$/m.test(content);
+    return {
+        kind: 'section', aliases: IMPLEMENTATION_INPUT_ALIASES,
+        heading: english ? 'Implementation Inputs' : '实现输入',
+        body: renderImplementationInputs(rows)
+    };
+}
 function mapWrite(intent, entityId, before, after, result) {
     if (result.status === 'failed')
         return failed(intent, result.error.code, result.error.message, result.taskId, entityId);
@@ -174,9 +183,34 @@ function applyLedgerIntent(intent, options = {}) {
             }
         }
     }
+    let implementationMutation = null;
+    if (intent.kind === 'decision-upsert' || intent.kind === 'finding-review') {
+        const stage = intent.kind === 'decision-upsert' ? intent.stage : after.stage;
+        const escalates = intent.kind === 'decision-upsert' || intent.status === 'needs-human-decision';
+        if (stage === 'code' && escalates && intent.needsImplementation === undefined) {
+            return failed(intent, 'LEDGER_PAYLOAD_INVALID', 'code-stage decisions require --needs-implementation true|false', resolved.taskId, after.id);
+        }
+        if ((stage !== 'code' || !escalates) && intent.needsImplementation !== undefined) {
+            return failed(intent, 'LEDGER_PAYLOAD_INVALID', '--needs-implementation is only valid for code-stage escalation', resolved.taskId, after.id);
+        }
+        if (stage === 'code' && escalates) {
+            try {
+                const parsed = parseImplementationInputs(content);
+                const declaration = declareImplementationInput(parsed.rows, {
+                    ledgerId: after.id, decisionEvidence: after.evidence,
+                    needsImplementation: intent.needsImplementation
+                });
+                const nextRows = parsed.rows.includes(declaration) ? parsed.rows : [...parsed.rows, declaration];
+                implementationMutation = implementationInputMutation(content, nextRows);
+            }
+            catch (error) {
+                return failed(intent, 'LEDGER_DOCUMENT_INVALID', error instanceof Error ? error.message : String(error), resolved.taskId, after.id);
+            }
+        }
+    }
     const result = writeTask({
         taskRef: intent.taskRef, expectedState: 'active',
-        mutations: [...ledgerSectionMutation(content), rowMutation(after)],
+        mutations: [...ledgerSectionMutation(content), rowMutation(after), ...(implementationMutation ? [implementationMutation] : [])],
         dryRun: 'dryRun' in intent ? intent.dryRun : false
     }, { ...options, taskLocation: { repoRoot: resolved.repoRoot, taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, state: resolved.state } });
     return mapWrite(intent, after.id, before, after, result);