@fitlab-ai/agent-infra 0.8.5 → 0.9.1

package/dist/lib/task/events.js

@@ -0,0 +1,318 @@
+import fs from 'node:fs';
+import { appendActivityEntry, locateActivityLog, pairEntries } from './activity-log.js';
+import { buildArtifactLinkSection, artifactName, parseArtifactName, resolveArtifactContext, validateCompletedArtifact } from './artifact-lifecycle.js';
+import { parseTypedTaskFrontmatter } from './frontmatter.js';
+import { consumeImplementationInput, IMPLEMENTATION_INPUT_ALIASES, parseImplementationInputs, renderImplementationInputs } from './implementation-inputs.js';
+import { resolveTaskRef } from './resolve-ref.js';
+import { findSectionHeading } from './sections.js';
+import { captureTaskWriteMetadata, writeTask } from './write.js';
+const eventCatalog = [
+    'analyze.started', 'analyze.awaiting-input', 'analyze.completed',
+    'review-analysis.started', 'review-analysis.completed',
+    'plan.started', 'plan.completed',
+    'review-plan.started', 'review-plan.completed',
+    'code.started', 'code.completed',
+    'review-code.started', 'review-code.completed',
+    'manual-validation.started', 'manual-validation.completed'
+];
+const BASE_FIELDS = new Set(['taskRef', 'event', 'agent', 'dryRun']);
+const SCHEMAS = {
+    'analyze.started': { optional: ['round'] },
+    'analyze.awaiting-input': { required: ['question'] },
+    'analyze.completed': { required: ['artifact'], optional: ['round'] },
+    'review-analysis.started': { optional: ['round'] },
+    'review-analysis.completed': { required: ['artifact', 'verdict', 'blockers', 'major', 'minor', 'manualValidation'], optional: ['round'] },
+    'plan.started': { optional: ['round'] },
+    'plan.completed': { required: ['artifact'], optional: ['round'] },
+    'review-plan.started': { optional: ['round'] },
+    'review-plan.completed': { required: ['artifact', 'verdict', 'blockers', 'major', 'minor', 'manualValidation'], optional: ['round'] },
+    'code.started': { optional: ['round', 'fixFor', 'implementationInput'] },
+    'code.completed': { required: ['artifact'], optional: ['round', 'fixFor', 'implementationInput', 'filesModified', 'testsPassed', 'blockers', 'major', 'minor', 'manualValidation'] },
+    'review-code.started': { optional: ['round'] },
+    'review-code.completed': { required: ['artifact', 'verdict', 'blockers', 'major', 'minor', 'manualValidation'], optional: ['round'] },
+    'manual-validation.started': { optional: ['round'] },
+    'manual-validation.completed': { required: ['artifact', 'summaryResult'], optional: ['round'] }
+};
+function validateTaskEventRequest(request) {
+    if (!eventCatalog.includes(request.event))
+        return { code: 'EVENT_UNKNOWN', message: `unknown task event '${request.event}'` };
+    if (!request.taskRef || !request.agent)
+        return { code: 'EVENT_PAYLOAD_INVALID', message: 'taskRef and agent are required' };
+    const schema = SCHEMAS[request.event];
+    const required = schema.required ?? [];
+    const allowed = new Set([...BASE_FIELDS, ...required, ...(schema.optional ?? [])]);
+    for (const [key, value] of Object.entries(request)) {
+        if (value !== undefined && !allowed.has(key))
+            return { code: 'EVENT_PAYLOAD_INVALID', message: `${request.event} does not accept '${key}'` };
+    }
+    for (const key of required)
+        if (request[key] === undefined)
+            return { code: 'EVENT_PAYLOAD_INVALID', message: `${request.event} requires '${key}'` };
+    for (const key of ['round', 'question', 'blockers', 'major', 'minor', 'manualValidation', 'filesModified', 'testsPassed']) {
+        const value = request[key];
+        if (value !== undefined && (!Number.isInteger(value) || value < (key === 'round' || key === 'question' ? 1 : 0)))
+            return { code: 'EVENT_PAYLOAD_INVALID', message: `'${key}' must be a ${key === 'round' || key === 'question' ? 'positive' : 'non-negative'} integer` };
+    }
+    if (request.verdict && !['approved', 'changes-requested', 'rejected'].includes(request.verdict))
+        return { code: 'EVENT_PAYLOAD_INVALID', message: 'verdict is invalid' };
+    if (request.event === 'code.completed') {
+        const fix = request.fixFor !== undefined || ['blockers', 'major', 'minor', 'manualValidation'].some((key) => request[key] !== undefined);
+        const modeRequired = fix ? ['fixFor', 'blockers', 'major', 'minor', 'manualValidation'] : ['filesModified', 'testsPassed'];
+        const forbidden = fix ? ['filesModified', 'testsPassed'] : ['fixFor', 'blockers', 'major', 'minor', 'manualValidation'];
+        if (modeRequired.some((key) => request[key] === undefined) || forbidden.some((key) => request[key] !== undefined))
+            return { code: 'EVENT_PAYLOAD_INVALID', message: 'code.completed requires either initial or fix completion payload' };
+    }
+    if (request.fixFor && !/^review-code(?:-r(?:[2-9]|[1-9]\d+))?\.md$/.test(request.fixFor))
+        return { code: 'EVENT_PAYLOAD_INVALID', message: 'fixFor must reference a canonical review-code artifact' };
+    if (request.implementationInput && !/^II-[1-9]\d*$/.test(request.implementationInput))
+        return { code: 'EVENT_PAYLOAD_INVALID', message: 'implementationInput must be a canonical II-N id' };
+    if (request.fixFor && request.implementationInput)
+        return { code: 'EVENT_PAYLOAD_INVALID', message: 'fixFor and implementationInput are mutually exclusive' };
+    if (request.summaryResult !== undefined && (!request.summaryResult.trim() || /[\r\n]/.test(request.summaryResult)))
+        return { code: 'EVENT_PAYLOAD_INVALID', message: 'summaryResult must be a non-empty single line' };
+    return null;
+}
+const FAMILY = {
+    analyze: { artifact: 'analysis', started: ['requirement-analysis', 'requirement-analysis-review', 'code'], completed: ['requirement-analysis', 'requirement-analysis-review', 'code'], target: 'requirement-analysis', label: 'Analyze Task' },
+    'review-analysis': { artifact: 'review-analysis', started: ['requirement-analysis', 'requirement-analysis-review'], completed: ['requirement-analysis', 'requirement-analysis-review'], target: 'requirement-analysis-review', label: 'Review Analysis' },
+    plan: { artifact: 'plan', started: ['requirement-analysis-review', 'technical-design-review'], completed: ['requirement-analysis-review', 'technical-design-review'], target: 'technical-design', label: 'Plan Task' },
+    'review-plan': { artifact: 'review-plan', started: ['technical-design', 'technical-design-review'], completed: ['technical-design', 'technical-design-review'], target: 'technical-design-review', label: 'Review Plan' },
+    code: { artifact: 'code', started: ['technical-design-review', 'code-review'], completed: ['technical-design-review', 'code-review'], target: 'code', label: 'Code Task' },
+    'review-code': { artifact: 'review-code', started: ['code', 'code-review', 'commit'], completed: ['code', 'code-review', 'commit'], target: 'code-review', label: 'Review Code' },
+    'manual-validation': { artifact: 'manual-validation', started: ['code-review', 'commit'], completed: ['code-review', 'commit'], target: null, label: 'Complete Manual Validation' }
+};
+function eventParts(event) {
+    const [family, suffix] = event.split('.');
+    return { family, phase: suffix === 'started' ? 'started' : suffix === 'awaiting-input' ? 'waiting' : 'completed' };
+}
+function identity(request) {
+    const { family, phase } = eventParts(request.event);
+    if (phase === 'waiting')
+        return { family, phase, action: 'Analyze Task (Brainstorming)', note: `Asked Q${request.question}, awaiting answer`, target: FAMILY.analyze.target };
+    const spec = FAMILY[family];
+    if (family === 'manual-validation') {
+        return {
+            family, phase, action: spec.label,
+            note: phase === 'started' ? 'started' : `Manual validation passed → ${request.artifact}; ${request.summaryResult}`,
+            target: null
+        };
+    }
+    const qualifier = request.fixFor
+        ? `, fix for ${request.fixFor}`
+        : request.implementationInput ? `, decision ${request.implementationInput}` : '';
+    const action = `${spec.label} (Round ${request.round}${qualifier})`;
+    if (phase === 'started')
+        return { family, phase, action, note: 'started', target: null };
+    let note = '';
+    if (family === 'analyze')
+        note = `Analysis completed → ${request.artifact}`;
+    else if (family === 'plan')
+        note = `Plan completed, awaiting human review → ${request.artifact}`;
+    else if (family === 'code' && request.fixFor)
+        note = `Fixed ${request.blockers} blockers, ${request.major} major, ${request.minor} minor issues${request.manualValidation ? `, skipped ${request.manualValidation} manual-validation` : ''} → ${request.artifact}`;
+    else if (family === 'code')
+        note = `Code implemented, ${request.filesModified} files modified, ${request.testsPassed} tests passed → ${request.artifact}`;
+    else {
+        const verdict = request.verdict === 'approved' ? 'Approved' : request.verdict === 'changes-requested' ? 'Changes Requested' : 'Rejected';
+        note = `Verdict: ${verdict}, blockers: ${request.blockers}, major: ${request.major}, minor: ${request.minor}, Manual-validation: ${request.manualValidation} → ${request.artifact}`;
+    }
+    return { family, phase, action, note, target: spec.target };
+}
+function failed(request, error, extra = {}) {
+    return {
+        status: 'failed', changed: false, event: request.event, requestRef: request.taskRef,
+        taskId: null, taskMdPath: null, fromStep: null, toStep: null, action: null,
+        phase: null, round: request.round ?? null, artifact: request.artifact ?? null,
+        fixFor: request.fixFor ?? null, implementationInput: request.implementationInput ?? null,
+        artifactContext: null, timestamp: null,
+        agentInfraVersion: null, operations: [], error, ...extra
+    };
+}
+function normalizeStarted(request, repoRoot) {
+    const family = eventParts(request.event).family;
+    const context = resolveArtifactContext(request.taskRef, FAMILY[family].artifact, { repoRoot });
+    if (context.status !== 'ready' || !context.next) {
+        return { error: { code: context.error?.code ?? 'EVENT_ARTIFACT_CONFLICT', message: context.error?.message ?? context.codeMode?.message ?? 'artifact context is not writable' }, context };
+    }
+    const round = context.next.round;
+    if (request.round !== undefined && request.round !== round)
+        return { error: { code: 'EVENT_ARTIFACT_CONFLICT', message: `round ${request.round} conflicts with expected round ${round}` }, context };
+    const expectedFix = family === 'code' && context.codeMode?.mode === 'fix' ? context.codeMode.reviewArtifact ?? undefined : undefined;
+    const expectedImplementation = family === 'code' && context.codeMode?.mode === 'decision'
+        ? context.codeMode.implementationInput ?? undefined : undefined;
+    if (request.fixFor !== undefined && request.fixFor !== expectedFix)
+        return { error: { code: 'EVENT_ARTIFACT_CONFLICT', message: `fixFor '${request.fixFor}' conflicts with artifact context` }, context };
+    if (request.implementationInput !== expectedImplementation)
+        return { error: { code: 'EVENT_ARTIFACT_CONFLICT', message: `implementationInput '${request.implementationInput ?? ''}' conflicts with artifact context` }, context };
+    return { request: { ...request, round, artifact: context.next.name, fixFor: expectedFix, implementationInput: expectedImplementation }, context };
+}
+function openStartedIdentity(rows, family) {
+    const spec = FAMILY[family];
+    if (family === 'manual-validation') {
+        const row = rows.filter((item) => item.step === spec.label && item.started && !item.done).at(-1);
+        const completed = rows.filter((item) => item.step === spec.label && item.done).length;
+        return row ? { row, round: completed + 1, fixFor: undefined, implementationInput: undefined } : null;
+    }
+    const escaped = spec.label.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const pattern = new RegExp(`^${escaped} \\(Round (\\d+)(?:(?:, fix for (review-code(?:-r\\d+)?\\.md))|(?:, decision (II-[1-9]\\d*)))?\\)$`);
+    const matches = rows.flatMap((row) => {
+        if (!row.started || row.done)
+            return [];
+        const match = pattern.exec(row.step);
+        return match ? [{ row, round: Number(match[1]), fixFor: match[2], implementationInput: match[3] }] : [];
+    });
+    return matches.length === 1 ? matches[0] : matches.length > 1 ? { conflict: true } : null;
+}
+function applyTaskEvent(request, options = {}) {
+    const invalid = validateTaskEventRequest(request);
+    if (invalid)
+        return failed(request, invalid);
+    const resolved = resolveTaskRef(request.taskRef, { repoRoot: options.repoRoot });
+    if (!resolved.ok)
+        return failed(request, { code: resolved.code, message: resolved.message }, { taskId: resolved.taskId });
+    if (resolved.state !== 'active')
+        return failed(request, { code: 'TASK_STATE_MISMATCH', message: `task ${resolved.taskId} is ${resolved.state}, expected active` }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath });
+    let content;
+    try {
+        content = fs.readFileSync(resolved.taskMdPath, 'utf8');
+    }
+    catch (error) {
+        return failed(request, { code: 'TASK_READ_FAILED', message: String(error) }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath });
+    }
+    let frontmatter;
+    try {
+        frontmatter = parseTypedTaskFrontmatter(content);
+    }
+    catch (error) {
+        return failed(request, { code: 'TASK_DOCUMENT_INVALID', message: error instanceof Error ? error.message : String(error) }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath });
+    }
+    const section = locateActivityLog(content);
+    if (!section)
+        return failed(request, { code: 'EVENT_LOG_MISSING', message: 'task has no unique Activity Log section' }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath });
+    const rows = pairEntries(section.entries);
+    let normalized = request;
+    let artifactContext = null;
+    const initialParts = eventParts(request.event);
+    if (initialParts.phase === 'started') {
+        const openIdentity = openStartedIdentity(rows, initialParts.family);
+        if (openIdentity && 'conflict' in openIdentity)
+            return failed(request, { code: 'EVENT_LOG_CONFLICT', message: 'artifact family has more than one open started event' }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath });
+        if (openIdentity) {
+            if (openIdentity.row.agent !== request.agent)
+                return failed(request, { code: 'EVENT_LOG_CONFLICT', message: 'open started event has a different agent' }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath });
+            if (request.round !== undefined && request.round !== openIdentity.round)
+                return failed(request, { code: 'EVENT_ARTIFACT_CONFLICT', message: `round ${request.round} conflicts with open round ${openIdentity.round}` }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath });
+            if (request.fixFor !== undefined && request.fixFor !== openIdentity.fixFor)
+                return failed(request, { code: 'EVENT_ARTIFACT_CONFLICT', message: `fixFor '${request.fixFor}' conflicts with open event` }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath });
+            if (request.implementationInput !== openIdentity.implementationInput)
+                return failed(request, { code: 'EVENT_ARTIFACT_CONFLICT', message: `implementationInput '${request.implementationInput ?? ''}' conflicts with open event` }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath });
+            normalized = { ...request, round: openIdentity.round, artifact: artifactName(FAMILY[initialParts.family].artifact, openIdentity.round), fixFor: openIdentity.fixFor, implementationInput: openIdentity.implementationInput };
+            return successNoOp(normalized, resolved.taskId, resolved.taskMdPath, typeof frontmatter.current_step === 'string' ? frontmatter.current_step : '', identity(normalized), openIdentity.row.started, frontmatter, null);
+        }
+        const result = normalizeStarted(request, resolved.repoRoot);
+        artifactContext = result.context;
+        if ('error' in result)
+            return failed(request, result.error, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, artifactContext });
+        normalized = result.request;
+    }
+    else if (initialParts.phase === 'completed') {
+        const identity = request.artifact ? parseArtifactName(request.artifact) : null;
+        if (identity?.family === FAMILY[initialParts.family].artifact)
+            normalized = { ...request, round: identity.round };
+    }
+    const eventIdentity = identity(normalized);
+    const currentStep = typeof frontmatter.current_step === 'string' ? frontmatter.current_step : '';
+    const matchingRows = rows.filter((item) => item.step === eventIdentity.action);
+    const manual = eventIdentity.family === 'manual-validation';
+    if (!manual && matchingRows.length > 1)
+        return failed(normalized, { code: 'EVENT_LOG_CONFLICT', message: 'event identity appears more than once' }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase, artifactContext });
+    const openRows = matchingRows.filter((item) => item.started && !item.done);
+    const completedRows = matchingRows.filter((item) => item.done);
+    const row = manual ? openRows.at(-1) : matchingRows[0];
+    let completedArtifact = null;
+    if (eventIdentity.phase === 'started' && row) {
+        if (row.agent !== normalized.agent)
+            return failed(normalized, { code: 'EVENT_LOG_CONFLICT', message: 'open started event has a different agent' }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath });
+        return successNoOp(normalized, resolved.taskId, resolved.taskMdPath, currentStep, eventIdentity, row.started, frontmatter, artifactContext);
+    }
+    if (eventIdentity.phase === 'started' && !manual && completedRows.length > 0)
+        return failed(normalized, { code: 'EVENT_ALREADY_COMPLETED', message: 'event identity is already completed' }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath });
+    const done = completedRows.find((item) => item.note === eventIdentity.note);
+    if (eventIdentity.phase === 'completed' && done)
+        return successNoOp(normalized, resolved.taskId, resolved.taskMdPath, currentStep, eventIdentity, done.done, frontmatter, artifactContext);
+    if (eventIdentity.phase === 'completed' && completedRows.length > 0 && openRows.length === 0)
+        return failed(normalized, { code: 'EVENT_LOG_CONFLICT', message: 'event identity is already completed with a different payload' }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
+    if (eventIdentity.phase === 'completed' && !row?.started)
+        return failed(normalized, { code: 'EVENT_START_MISSING', message: 'completion requires one open matching started event' }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
+    if (eventIdentity.phase === 'completed') {
+        const validated = validateCompletedArtifact(resolved.taskDir, FAMILY[eventIdentity.family].artifact, normalized.artifact, normalized.round);
+        if (!validated.ok)
+            return failed(normalized, validated.error, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
+        completedArtifact = validated.artifact;
+    }
+    if (eventIdentity.phase === 'waiting' && section.entries.some((entry) => entry.step === eventIdentity.action && entry.note === eventIdentity.note)) {
+        const existing = section.entries.find((entry) => entry.step === eventIdentity.action && entry.note === eventIdentity.note);
+        return successNoOp(normalized, resolved.taskId, resolved.taskMdPath, currentStep, eventIdentity, existing.time, frontmatter, artifactContext);
+    }
+    const allowed = FAMILY[eventIdentity.family][eventIdentity.phase === 'started' ? 'started' : 'completed'];
+    if (!allowed.includes(currentStep))
+        return failed(normalized, { code: 'EVENT_TRANSITION_INVALID', message: `${normalized.event} is not allowed from '${currentStep}'` }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
+    let metadata;
+    try {
+        metadata = (options.metadataProvider ?? captureTaskWriteMetadata)();
+    }
+    catch (error) {
+        return failed(normalized, { code: 'METADATA_CAPTURE_FAILED', message: String(error) }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath });
+    }
+    const step = eventIdentity.phase === 'started' || eventIdentity.target === null ? currentStep : eventIdentity.target;
+    const logStep = eventIdentity.phase === 'started' ? `${eventIdentity.action} [started]` : eventIdentity.action;
+    const body = appendActivityEntry(section, { time: metadata.timestamp, step: logStep, agent: normalized.agent, note: eventIdentity.note });
+    const frontmatterSet = { current_step: step, assigned_to: normalized.agent };
+    if (eventIdentity.phase === 'started' && normalized.implementationInput)
+        frontmatterSet.last_reviewed_commit = '';
+    const mutations = [
+        { kind: 'frontmatter', set: frontmatterSet }
+    ];
+    if (completedArtifact) {
+        const link = buildArtifactLinkSection(content, completedArtifact);
+        mutations.push({ kind: 'section', aliases: link.aliases, heading: link.heading, body: link.body });
+    }
+    if (eventIdentity.phase === 'completed' && normalized.implementationInput) {
+        let implementationRows;
+        try {
+            implementationRows = consumeImplementationInput(parseImplementationInputs(content).rows, normalized.implementationInput, normalized.artifact);
+        }
+        catch (error) {
+            return failed(normalized, { code: 'EVENT_ARTIFACT_CONFLICT', message: error instanceof Error ? error.message : String(error) }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
+        }
+        mutations.push({
+            kind: 'section', aliases: IMPLEMENTATION_INPUT_ALIASES,
+            heading: findSectionHeading(content, [...IMPLEMENTATION_INPUT_ALIASES]),
+            body: renderImplementationInputs(implementationRows)
+        });
+    }
+    mutations.push({ kind: 'section', aliases: ['活动日志', 'Activity Log'], heading: section.heading, body });
+    const result = writeTask({ taskRef: normalized.taskRef, expectedState: 'active', dryRun: normalized.dryRun, mutations }, { ...options, metadataProvider: () => metadata });
+    if (result.status === 'failed')
+        return failed(normalized, result.error, { taskId: result.taskId, taskMdPath: result.taskMdPath, fromStep: currentStep, toStep: step, action: eventIdentity.action, phase: eventIdentity.phase, timestamp: result.timestamp, agentInfraVersion: result.agentInfraVersion, operations: result.operations, artifactContext });
+    return {
+        status: result.status, changed: result.changed, event: normalized.event,
+        requestRef: normalized.taskRef, taskId: result.taskId, taskMdPath: result.taskMdPath,
+        fromStep: currentStep, toStep: step, action: eventIdentity.action, phase: eventIdentity.phase,
+        round: normalized.round ?? null, artifact: normalized.artifact ?? null,
+        fixFor: normalized.fixFor ?? null, implementationInput: normalized.implementationInput ?? null,
+        artifactContext, timestamp: result.timestamp,
+        agentInfraVersion: result.agentInfraVersion, operations: result.operations, error: null
+    };
+}
+function successNoOp(request, taskId, taskMdPath, currentStep, eventIdentity, timestamp, frontmatter, artifactContext) {
+    return {
+        ...failed(request, { code: 'EVENT_LOG_CONFLICT', message: '' }), status: 'no-op', error: null,
+        taskId, taskMdPath, fromStep: currentStep, toStep: currentStep,
+        action: eventIdentity.action, phase: eventIdentity.phase, timestamp,
+        agentInfraVersion: typeof frontmatter.agent_infra_version === 'string' ? frontmatter.agent_infra_version : null,
+        artifactContext
+    };
+}
+export { eventCatalog, validateTaskEventRequest, applyTaskEvent };
+//# sourceMappingURL=events.js.map

package/dist/lib/task/frontmatter.js

@@ -1,3 +1,58 @@
+import { parse, stringify } from 'yaml';
+class FrontmatterError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'FrontmatterError';
+        this.code = code;
+    }
+}
+function locateFrontmatter(content) {
+    const opening = /^---(\r?\n)/.exec(content);
+    if (!opening) {
+        throw new FrontmatterError('TASK_DOCUMENT_INVALID', 'task.md frontmatter is missing');
+    }
+    const eol = opening[1];
+    const bodyStart = opening[0].length;
+    const closing = /^---\r?$/gm;
+    closing.lastIndex = bodyStart;
+    const match = closing.exec(content);
+    if (!match) {
+        throw new FrontmatterError('TASK_DOCUMENT_INVALID', 'task.md frontmatter is unclosed');
+    }
+    return { eol, bodyStart, bodyEnd: match.index };
+}
+function parseFrontmatterLines(content, block) {
+    const body = content.slice(block.bodyStart, block.bodyEnd);
+    const lines = body.split(block.eol);
+    return lines.map((raw, index) => {
+        if (!raw.trim() || raw.trimStart().startsWith('#')) {
+            return { raw, index, key: null, value: null };
+        }
+        const match = /^([^\s:#][^:]*):(?:[ \t]*(.*))?$/.exec(raw);
+        if (!match || !match[1]) {
+            throw new FrontmatterError('TASK_DOCUMENT_INVALID', `unsupported frontmatter structure on line ${index + 2}`);
+        }
+        return {
+            raw,
+            index,
+            key: match[1].trim(),
+            value: match[2] ?? ''
+        };
+    });
+}
+function serializeScalar(value) {
+    if (typeof value === 'number' && !Number.isFinite(value)) {
+        throw new FrontmatterError('MUTATION_INVALID', 'frontmatter numbers must be finite');
+    }
+    if (value === '')
+        return '';
+    const serialized = stringify(value).trimEnd();
+    if (serialized.includes('\n') || serialized.includes('\r')) {
+        throw new FrontmatterError('MUTATION_INVALID', 'frontmatter values must be scalar');
+    }
+    return serialized;
+}
 function parseTaskFrontmatter(content) {
     const result = {};
     if (!content.startsWith('---'))
@@ -20,6 +75,109 @@ function parseTaskFrontmatter(content) {
     }
     return result;
 }
+function parseTypedTaskFrontmatter(content) {
+    const block = locateFrontmatter(content);
+    const result = {};
+    for (const line of parseFrontmatterLines(content, block)) {
+        if (!line.key || line.value === null)
+            continue;
+        if (Object.hasOwn(result, line.key)) {
+            throw new FrontmatterError('TASK_DOCUMENT_INVALID', `duplicate frontmatter key '${line.key}'`);
+        }
+        if (line.value === '') {
+            result[line.key] = '';
+            continue;
+        }
+        let value;
+        try {
+            value = parse(line.value);
+        }
+        catch {
+            throw new FrontmatterError('TASK_DOCUMENT_INVALID', `frontmatter key '${line.key}' is not a valid scalar`);
+        }
+        if (value !== null &&
+            typeof value !== 'string' &&
+            typeof value !== 'number' &&
+            typeof value !== 'boolean') {
+            throw new FrontmatterError('TASK_DOCUMENT_INVALID', `frontmatter key '${line.key}' is not a scalar`);
+        }
+        if (typeof value === 'number' && !Number.isFinite(value)) {
+            throw new FrontmatterError('TASK_DOCUMENT_INVALID', `frontmatter key '${line.key}' is not a finite scalar`);
+        }
+        result[line.key] = value;
+    }
+    return result;
+}
+function updateTaskFrontmatter(content, set, remove = []) {
+    if (!set || typeof set !== 'object' || Array.isArray(set)) {
+        throw new FrontmatterError('MUTATION_INVALID', 'frontmatter set must be an object');
+    }
+    const entries = Object.entries(set);
+    if (!Array.isArray(remove)) {
+        throw new FrontmatterError('MUTATION_INVALID', 'frontmatter remove must be an array');
+    }
+    const removeSet = new Set(remove);
+    if (removeSet.size !== remove.length) {
+        throw new FrontmatterError('MUTATION_INVALID', 'frontmatter remove keys must be unique');
+    }
+    for (const [key, value] of entries) {
+        if (!key || /[\r\n:]/.test(key)) {
+            throw new FrontmatterError('MUTATION_INVALID', `invalid frontmatter key '${key}'`);
+        }
+        if (value !== null &&
+            typeof value !== 'string' &&
+            typeof value !== 'number' &&
+            typeof value !== 'boolean') {
+            throw new FrontmatterError('MUTATION_INVALID', `invalid scalar for '${key}'`);
+        }
+    }
+    for (const key of remove) {
+        if (!key || /[\r\n:]/.test(key)) {
+            throw new FrontmatterError('MUTATION_INVALID', `invalid frontmatter key '${key}'`);
+        }
+        if (Object.hasOwn(set, key)) {
+            throw new FrontmatterError('MUTATION_INVALID', `frontmatter key '${key}' cannot be set and removed together`);
+        }
+    }
+    const block = locateFrontmatter(content);
+    const lines = parseFrontmatterLines(content, block);
+    const indexes = new Map();
+    for (const line of lines) {
+        if (!line.key)
+            continue;
+        const positions = indexes.get(line.key) ?? [];
+        positions.push(line.index);
+        indexes.set(line.key, positions);
+    }
+    for (const key of [...entries.map(([entryKey]) => entryKey), ...remove]) {
+        if ((indexes.get(key)?.length ?? 0) > 1) {
+            throw new FrontmatterError('TASK_DOCUMENT_INVALID', `duplicate frontmatter key '${key}'`);
+        }
+    }
+    const nextLines = lines.map((line) => line.raw);
+    const additions = [];
+    for (const [key, value] of entries) {
+        const serialized = serializeScalar(value);
+        const replacement = serialized === '' ? `${key}:` : `${key}: ${serialized}`;
+        const index = indexes.get(key)?.[0];
+        if (index === undefined)
+            additions.push(replacement);
+        else
+            nextLines[index] = replacement;
+    }
+    const retainedLines = nextLines.filter((_, index) => {
+        const key = lines[index]?.key;
+        return !key || !removeSet.has(key);
+    });
+    if (additions.length > 0) {
+        if (retainedLines.at(-1) === '')
+            retainedLines.splice(-1, 0, ...additions);
+        else
+            retainedLines.push(...additions);
+    }
+    const body = retainedLines.join(block.eol);
+    return content.slice(0, block.bodyStart) + body + content.slice(block.bodyEnd);
+}
 function extractTitle(content) {
     for (const line of content.split('\n')) {
         const m = /^#\s+(?:任务[:：]?\s*)?(.+)$/.exec(line.trim());
@@ -28,5 +186,5 @@ function extractTitle(content) {
     }
     return '';
 }
-export { parseTaskFrontmatter, extractTitle };
+export { parseTaskFrontmatter, parseTypedTaskFrontmatter, updateTaskFrontmatter, extractTitle };
 //# sourceMappingURL=frontmatter.js.map

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

@@ -0,0 +1,117 @@
+import { parseTable } from './sections.js';
+const SECTION_ALIASES = ['实现输入', 'Implementation Inputs'];
+const COLUMNS = [
+    'id', 'ledger_id', 'decision_evidence', 'stage', 'needs_implementation',
+    'decided_at', 'status', 'consumed_by'
+];
+const TIMESTAMP_RE = /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}[+-]\d{2}:\d{2}$/;
+const ARTIFACT_RE = /^code(?:-r(?:[2-9]|[1-9]\d+))?\.md$/;
+function validateInput(row) {
+    if (!/^II-[1-9]\d*$/.test(row.id))
+        throw new Error(`implementation input id '${row.id}' is invalid`);
+    if (!row.ledgerId || !row.decisionEvidence || /[\r\n]/.test(row.ledgerId) || /[\r\n]/.test(row.decisionEvidence))
+        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));
+    if (!valid)
+        throw new Error(`implementation input ${row.id} has an invalid state combination`);
+}
+function parseImplementationInputs(content) {
+    const table = parseTable(content, { sectionAliases: SECTION_ALIASES, columns: COLUMNS });
+    if (!table)
+        return { sectionFound: false, rows: [] };
+    const rows = [];
+    const seen = new Set();
+    for (const { values } of table.rows) {
+        const id = values.id;
+        const ledgerId = values.ledger_id;
+        const decisionEvidence = values.decision_evidence;
+        const stage = values.stage;
+        const needs = values.needs_implementation;
+        const decidedAt = values.decided_at;
+        const status = values.status;
+        const consumedBy = values.consumed_by;
+        if (needs !== 'true' && needs !== 'false')
+            throw new Error(`implementation input ${id} has invalid needs_implementation`);
+        const row = {
+            id: id, ledgerId: ledgerId, decisionEvidence: decisionEvidence, stage: stage,
+            needsImplementation: needs === 'true', decidedAt: decidedAt,
+            status: status, consumedBy: consumedBy
+        };
+        validateInput(row);
+        if (seen.has(row.id))
+            throw new Error(`duplicate implementation input id '${row.id}'`);
+        seen.add(row.id);
+        rows.push(row);
+    }
+    return { sectionFound: true, rows };
+}
+function nextId(rows) {
+    let max = 0;
+    for (const row of rows)
+        max = Math.max(max, Number.parseInt(row.id.slice(3), 10));
+    return `II-${max + 1}`;
+}
+function createImplementationInput(rows, draft) {
+    const row = {
+        id: nextId(rows), ledgerId: draft.ledgerId, decisionEvidence: draft.decisionEvidence,
+        stage: 'code', needsImplementation: draft.needsImplementation, decidedAt: draft.decidedAt,
+        status: draft.needsImplementation ? 'pending' : 'not-required', consumedBy: ''
+    };
+    validateInput(row);
+    return row;
+}
+function selectPendingImplementationInput(rows, reviewCompletedAt) {
+    const reviewEpoch = Date.parse(reviewCompletedAt.replace(' ', 'T'));
+    if (!Number.isFinite(reviewEpoch))
+        throw new Error('latest review completion time is invalid');
+    const pending = rows.filter((row) => row.needsImplementation && row.status === 'pending');
+    const stale = pending.find((row) => Date.parse(row.decidedAt.replace(' ', 'T')) <= reviewEpoch);
+    if (stale)
+        throw new Error(`implementation input ${stale.id} is not later than the latest approved review`);
+    return [...pending].sort((left, right) => {
+        const time = Date.parse(left.decidedAt.replace(' ', 'T')) - Date.parse(right.decidedAt.replace(' ', 'T'));
+        return time || Number.parseInt(left.id.slice(3), 10) - Number.parseInt(right.id.slice(3), 10);
+    })[0] ?? null;
+}
+function consumeImplementationInput(rows, id, artifact) {
+    if (!ARTIFACT_RE.test(artifact))
+        throw new Error(`implementation input artifact '${artifact}' is invalid`);
+    let found = false;
+    const next = rows.map((row) => {
+        if (row.id !== id)
+            return row;
+        found = true;
+        if (row.status !== 'pending' || !row.needsImplementation) {
+            throw new Error(`implementation input ${id} is not pending`);
+        }
+        return { ...row, status: 'consumed', consumedBy: artifact };
+    });
+    if (!found)
+        throw new Error(`implementation input ${id} was not found`);
+    next.forEach(validateInput);
+    return next;
+}
+function renderImplementationInputs(rows) {
+    rows.forEach(validateInput);
+    const ids = new Set(rows.map((row) => row.id));
+    if (ids.size !== rows.length)
+        throw new Error('implementation input ids must be unique');
+    return [
+        `| ${COLUMNS.join(' | ')} |`,
+        '|----|-----------|-------------------|-------|----------------------|------------|--------|-------------|',
+        ...rows.map((row) => {
+            const cells = [row.id, row.ledgerId, row.decisionEvidence, 'code', String(row.needsImplementation), row.decidedAt, row.status, row.consumedBy]
+                .map((value) => value.replace(/\\/g, '\\\\').replace(/\|/g, '\\|'));
+            return `| ${cells.join(' | ')} |`;
+        })
+    ].join('\n');
+}
+export { SECTION_ALIASES as IMPLEMENTATION_INPUT_ALIASES, createImplementationInput, consumeImplementationInput, parseImplementationInputs, renderImplementationInputs, selectPendingImplementationInput };
+//# sourceMappingURL=implementation-inputs.js.map

package/dist/lib/task/index.js

@@ -1,23 +1,26 @@
 const USAGE = `Usage: ai task <command> [options]
 
 Commands:
-  cat <ref> <artifact | N>               Print a task artifact (by name or number)
-  decisions, d <ref> [selector]          List human-decision (HD-) items, or show one's detail
-  files <ref>                            List artifacts in a task dir (numbered)
-  grep <pattern> [ref] [artifact | N]    Literal search across task artifacts (omit ref to scan all)
-  issue-body <ref> [--template <path>]   Print a deterministic Issue body from task.md (描述 + 需求, or an Issue Form)
-  log <ref>                              Render a task's activity log as a timeline
+  cat [--task <ref>] <artifact | N>      Print a task artifact (by name or number)
+  decisions, d [--task <ref>] [-i item]  List review decisions, or show one item's detail
+  files [--task <ref>]                   List artifacts in a task dir (numbered)
+  grep <pattern> [--current|--task <ref>] Literal search across task artifacts (global by default)
+  issue-body [--task <ref>] [--template] Print a deterministic Issue body from task.md
+  log [--task <ref>]                     Render a task's activity log as a timeline
   ls [--all | --blocked | --completed]   List tasks (default: active)
-  show <N | #N | TASK-id>                Print a task.md
-  status <ref>                           Aggregated status view (metadata / artifacts / git / platform)
+  show [--task <ref>]                    Print a task.md
+  status [--task <ref>]                  Aggregated status view (metadata / artifacts / git / platform)
 
 Examples:
   ai task cat 11 analysis
+  ai task cat analysis
   ai task cat 11 3
   ai task decisions 11
-  ai task d 11 HD-3 --format markdown
+  ai task decisions --item 1
+  ai task d 11 PL-3 --format markdown
   ai task files 11
   ai task grep resolveArtifact
+  ai task grep resolveArtifact --current
   ai task grep resolveArtifact 11
   ai task issue-body 11
   ai task issue-body 11 --template .github/ISSUE_TEMPLATE/05_other.yml