@fitlab-ai/agent-infra 0.8.5 → 0.9.0

package/dist/lib/task/activity-log.js

@@ -0,0 +1,61 @@
+const HEADING_RE = /^##\s+(活动日志|Activity Log)\s*$/;
+const NEXT_H2_RE = /^##\s/;
+const ENTRY_RE = /^- (\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}[+-]\d{2}:\d{2}) — \*\*(.+?)\*\* by (.+?) — (.*)$/;
+const STARTED_SUFFIX_RE = /\s*\[started\]\s*$/;
+function parseActivityLog(content) {
+    const section = locateActivityLog(content);
+    return section ? { sectionFound: true, entries: section.entries } : { sectionFound: false, entries: [] };
+}
+function locateActivityLog(content) {
+    const lines = content.split('\n');
+    const headings = lines.map((line, index) => HEADING_RE.test(line) ? index : -1).filter((index) => index >= 0);
+    if (headings.length !== 1)
+        return null;
+    const i = headings[0];
+    let end = lines.length;
+    for (let j = i + 1; j < lines.length; j += 1) {
+        if (NEXT_H2_RE.test(lines[j])) {
+            end = j;
+            break;
+        }
+    }
+    const bodyLines = lines.slice(i + 1, end);
+    const parsed = [];
+    for (const line of bodyLines) {
+        const m = ENTRY_RE.exec(line);
+        if (!m)
+            continue;
+        parsed.push({ entry: { time: m[1], step: m[2], agent: m[3], note: m[4] }, epoch: Date.parse(m[1].replace(' ', 'T')), order: parsed.length });
+    }
+    parsed.sort((a, b) => a.epoch - b.epoch || a.order - b.order);
+    return { heading: HEADING_RE.exec(lines[i])[1], body: bodyLines.join('\n').replace(/^\n+|\n+$/g, ''), entries: parsed.map((item) => item.entry) };
+}
+function appendActivityEntry(section, entry) {
+    const line = `- ${entry.time} — **${entry.step}** by ${entry.agent} — ${entry.note}`;
+    return section.body ? `${section.body}\n${line}` : line;
+}
+function pairEntries(entries) {
+    const rows = [];
+    const open = new Map();
+    for (const entry of entries) {
+        const started = STARTED_SUFFIX_RE.test(entry.step);
+        const base = entry.step.replace(STARTED_SUFFIX_RE, '');
+        if (started) {
+            const row = { step: base, agent: entry.agent, started: entry.time, done: '', note: entry.note };
+            rows.push(row);
+            const queue = open.get(base) ?? [];
+            queue.push(row);
+            open.set(base, queue);
+        }
+        else {
+            const pending = open.get(base)?.shift();
+            if (pending)
+                Object.assign(pending, { done: entry.time, agent: entry.agent, note: entry.note });
+            else
+                rows.push({ step: base, agent: entry.agent, started: '', done: entry.time, note: entry.note });
+        }
+    }
+    return rows;
+}
+export { parseActivityLog, locateActivityLog, appendActivityEntry, pairEntries };
+//# sourceMappingURL=activity-log.js.map

package/dist/lib/task/artifact-lifecycle.js

@@ -0,0 +1,427 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { resolveTaskRef } from './resolve-ref.js';
+import { locateActivityLog } from './activity-log.js';
+import { parseImplementationInputs, selectPendingImplementationInput } from './implementation-inputs.js';
+import { extractSection, findSectionHeading } from './sections.js';
+const artifactFamilyCatalog = [
+    { family: 'analysis', sectionAliases: ['分析', 'Analysis'], heading: '分析', labels: ['需求分析报告', 'Requirements Analysis'] },
+    { family: 'review-analysis', sectionAliases: ['审查反馈', 'Review Feedback'], heading: '审查反馈', labels: ['需求分析审查', 'Analysis Review'] },
+    { family: 'plan', sectionAliases: ['设计', 'Design'], heading: '设计', labels: ['技术方案', 'Technical Plan'] },
+    { family: 'review-plan', sectionAliases: ['审查反馈', 'Review Feedback'], heading: '审查反馈', labels: ['技术方案审查', 'Plan Review'] },
+    { family: 'code', sectionAliases: ['实现备注', 'Implementation Notes'], heading: '实现备注', labels: ['实现报告', 'Implementation Report'] },
+    { family: 'review-code', sectionAliases: ['审查反馈', 'Review Feedback'], heading: '审查反馈', labels: ['代码审查', 'Code Review'] },
+    { family: 'manual-validation', sectionAliases: ['实现备注', 'Implementation Notes'], heading: '实现备注', labels: ['人工验证', 'Manual Validation'] }
+];
+const FAMILY_SET = new Set(artifactFamilyCatalog.map((item) => item.family));
+const BLOCKING_DIAGNOSTICS = new Set([
+    'NONCANONICAL_NAME', 'ROUND_OUT_OF_RANGE', 'MISSING_BASE', 'ROUND_GAP',
+    'DUPLICATE_LOGICAL_ROUND', 'NON_REGULAR_FILE', 'SYMBOLIC_LINK',
+    'FILESYSTEM_RACE', 'CATALOG_CONFLICT'
+]);
+function familySpec(family) {
+    return artifactFamilyCatalog.find((item) => item.family === family) ?? null;
+}
+function artifactName(family, round) {
+    if (!FAMILY_SET.has(family))
+        throw new Error(`unknown artifact family '${family}'`);
+    if (!Number.isSafeInteger(round) || round < 1)
+        throw new Error('artifact round must be a safe positive integer');
+    return round === 1 ? `${family}.md` : `${family}-r${round}.md`;
+}
+function parseArtifactName(name) {
+    if (path.basename(name) !== name)
+        return null;
+    const matches = [];
+    for (const spec of artifactFamilyCatalog) {
+        if (name === `${spec.family}.md`)
+            matches.push({ family: spec.family, round: 1, name });
+        const match = new RegExp(`^${escapeRegExp(spec.family)}-r([1-9]\\d*)\\.md$`).exec(name);
+        if (!match)
+            continue;
+        const round = Number(match[1]);
+        if (Number.isSafeInteger(round) && round >= 2 && String(round) === match[1]) {
+            matches.push({ family: spec.family, round, name });
+        }
+    }
+    return matches.length === 1 ? matches[0] : null;
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function failure(requestRef, family, error, extra = {}) {
+    return {
+        status: 'failed', changed: false, requestRef, taskId: null, taskDir: null,
+        taskState: null, family, artifacts: [], latest: null, next: null,
+        reviewedInput: null, diagnostics: [], error, ...extra
+    };
+}
+function diagnostic(code, family, name, message) {
+    return { code, family, name, message };
+}
+function inspectTaskArtifacts(taskRef, family, options = {}) {
+    const spec = familySpec(family);
+    if (!spec)
+        return failure(taskRef, family, { code: 'ARTIFACT_FAMILY_UNKNOWN', message: `unknown artifact family '${family}'` });
+    const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
+    if (!resolved.ok)
+        return failure(taskRef, family, { code: resolved.code, message: resolved.message }, { taskId: resolved.taskId });
+    return inspectArtifactDirectory(resolved.taskDir, spec.family, {
+        requestRef: taskRef, taskId: resolved.taskId, taskState: resolved.state
+    });
+}
+function inspectArtifactDirectory(taskDir, family, identity = {}) {
+    const requestRef = identity.requestRef ?? taskDir;
+    let entries;
+    try {
+        entries = fs.readdirSync(taskDir, { withFileTypes: true });
+    }
+    catch (error) {
+        return failure(requestRef, family, { code: 'ARTIFACT_DIRECTORY_READ_FAILED', message: String(error) }, {
+            taskId: identity.taskId ?? null, taskDir, taskState: identity.taskState ?? null
+        });
+    }
+    const artifacts = [];
+    const diagnostics = [];
+    for (const entry of entries) {
+        const parsed = parseArtifactName(entry.name);
+        const reserved = entry.name.toLowerCase().startsWith(`${family.toLowerCase()}-r`) || entry.name.toLowerCase() === `${family.toLowerCase()}.md`;
+        if (!parsed || parsed.family !== family) {
+            if (reserved) {
+                const roundText = new RegExp(`^${escapeRegExp(family)}-r(.+)\\.md$`, 'i').exec(entry.name)?.[1];
+                const code = roundText && /^\d+$/.test(roundText) && !Number.isSafeInteger(Number(roundText))
+                    ? 'ROUND_OUT_OF_RANGE' : 'NONCANONICAL_NAME';
+                diagnostics.push(diagnostic(code, family, entry.name, `noncanonical ${family} artifact candidate '${entry.name}' (verify whether this is an unrelated file with a reserved prefix)`));
+            }
+            continue;
+        }
+        const abs = path.join(taskDir, entry.name);
+        try {
+            const stat = fs.lstatSync(abs);
+            if (stat.isSymbolicLink()) {
+                diagnostics.push(diagnostic('SYMBOLIC_LINK', family, entry.name, `symbolic links are not workflow artifacts: ${entry.name}`));
+                continue;
+            }
+            if (!stat.isFile()) {
+                diagnostics.push(diagnostic('NON_REGULAR_FILE', family, entry.name, `artifact is not a regular file: ${entry.name}`));
+                continue;
+            }
+            try {
+                fs.accessSync(abs, fs.constants.R_OK);
+            }
+            catch {
+                diagnostics.push(diagnostic('FILESYSTEM_RACE', family, entry.name, `artifact is not readable: ${entry.name}`));
+                continue;
+            }
+            artifacts.push({ ...parsed, path: abs, size: stat.size, mtimeMs: stat.mtimeMs });
+        }
+        catch (error) {
+            diagnostics.push(diagnostic('FILESYSTEM_RACE', family, entry.name, String(error)));
+        }
+    }
+    artifacts.sort((left, right) => left.round - right.round);
+    const rounds = new Set(artifacts.map((item) => item.round));
+    if (artifacts.length > 0 && !rounds.has(1))
+        diagnostics.push(diagnostic('MISSING_BASE', family, null, `${family}.md is missing`));
+    const max = artifacts.at(-1)?.round ?? 0;
+    for (let round = 1; round <= max; round += 1) {
+        if (!rounds.has(round))
+            diagnostics.push(diagnostic('ROUND_GAP', family, null, `${artifactName(family, round)} is missing`));
+    }
+    const latest = artifacts.at(-1) ?? null;
+    const reviewedInput = family.startsWith('review-') && latest
+        ? resolveReviewedInput(taskDir, latest, family === 'review-analysis' ? 'analysis' : family === 'review-plan' ? 'plan' : 'code', diagnostics)
+        : null;
+    return {
+        status: 'ready', changed: false, requestRef, taskId: identity.taskId ?? null,
+        taskDir, taskState: identity.taskState ?? null, family, artifacts, latest,
+        next: { round: max + 1, name: artifactName(family, max + 1) },
+        reviewedInput, diagnostics, error: null
+    };
+}
+function resolveReviewedInput(taskDir, review, expectedFamily, diagnostics) {
+    let content;
+    try {
+        content = fs.readFileSync(review.path, 'utf8');
+    }
+    catch (error) {
+        diagnostics.push(diagnostic('BROKEN_REFERENCE', review.family, review.name, String(error)));
+        return null;
+    }
+    const lines = content.split(/\r?\n/);
+    const header = lines.findIndex((line) => /\*\*(?:审查输入|Review Input)\*\*[:：]/.test(line));
+    const referenceBlock = header >= 0 ? lines.slice(header, header + 12).join('\n') : '';
+    const candidates = [...referenceBlock.matchAll(/`([^`]+\.md)`/g)].map((match) => match[1]);
+    const parsed = candidates.map((name) => parseArtifactName(name)).find((item) => item?.family === expectedFamily);
+    if (!parsed) {
+        diagnostics.push(diagnostic('BROKEN_REFERENCE', review.family, review.name, `${review.name} does not reference a canonical ${expectedFamily} artifact`));
+        return null;
+    }
+    const abs = path.join(taskDir, parsed.name);
+    try {
+        const stat = fs.lstatSync(abs);
+        if (!stat.isFile() || stat.isSymbolicLink())
+            throw new Error('referenced input is not a regular file');
+        if (stat.mtimeMs > review.mtimeMs) {
+            diagnostics.push(diagnostic('BROKEN_REFERENCE', review.family, review.name, `${parsed.name} is newer than ${review.name}`));
+            return null;
+        }
+        return { ...parsed, path: abs, size: stat.size, mtimeMs: stat.mtimeMs };
+    }
+    catch (error) {
+        diagnostics.push(diagnostic('BROKEN_REFERENCE', review.family, review.name, `${parsed.name}: ${String(error)}`));
+        return null;
+    }
+}
+function extractMarkdownSection(content, names) {
+    const lines = content.split(/\r?\n/);
+    const allowed = new Set(names);
+    const start = lines.findIndex((line) => {
+        const match = /^##\s+(.+?)\s*$/.exec(line.trim());
+        return Boolean(match?.[1] && allowed.has(match[1]));
+    });
+    if (start === -1)
+        return '';
+    let end = lines.length;
+    for (let index = start + 1; index < lines.length; index += 1) {
+        if (/^##\s+/.test(lines[index])) {
+            end = index;
+            break;
+        }
+    }
+    return lines.slice(start + 1, end).join('\n');
+}
+function assertWritableInventory(inventory) {
+    if (inventory.status === 'failed')
+        return inventory.error;
+    const blockers = inventory.diagnostics.filter((item) => BLOCKING_DIAGNOSTICS.has(item.code));
+    return blockers.length === 0 ? null : {
+        code: 'ARTIFACT_TOPOLOGY_CONFLICT',
+        message: blockers.map((item) => `${item.code}: ${item.message}`).join('; ')
+    };
+}
+const REQUIRED_INPUT = {
+    'review-analysis': 'analysis', plan: 'analysis', 'review-plan': 'plan', 'review-code': 'code'
+};
+const OPTIONAL_CONTEXT = {
+    analysis: { family: 'review-analysis', requireReference: true },
+    plan: { family: 'review-plan', requireReference: true },
+    'review-code': { family: 'review-plan' },
+    'manual-validation': { family: 'review-code' }
+};
+function resolveArtifactContext(taskRef, family, options = {}) {
+    const inventory = inspectTaskArtifacts(taskRef, family, options);
+    if (inventory.status === 'failed')
+        return { ...inventory, inputs: [], codeMode: null };
+    const writableError = assertWritableInventory(inventory);
+    if (writableError)
+        return { ...inventory, status: 'failed', inputs: [], codeMode: null, error: writableError };
+    if (inventory.family === 'code')
+        return resolveCodeContext(inventory, options);
+    const required = REQUIRED_INPUT[inventory.family];
+    const inputs = [];
+    if (required) {
+        const input = inspectTaskArtifacts(taskRef, required, options);
+        if (input.status === 'failed' || !input.latest) {
+            return { ...inventory, status: 'failed', inputs, codeMode: null, error: { code: 'ARTIFACT_INPUT_MISSING', message: `latest ${required} artifact is required` } };
+        }
+        inputs.push(input.latest);
+    }
+    const optional = OPTIONAL_CONTEXT[inventory.family];
+    if (optional) {
+        const context = inspectTaskArtifacts(taskRef, optional.family, options);
+        if (context.status === 'ready' && context.latest) {
+            if (optional.requireReference && !context.reviewedInput) {
+                return { ...inventory, status: 'failed', inputs, codeMode: null, error: { code: 'ARTIFACT_REFERENCE_INVALID', message: `${context.latest.name} has no valid reviewed input` } };
+            }
+            inputs.push(context.latest);
+        }
+    }
+    return { ...inventory, inputs, codeMode: null };
+}
+function resolveCodeContext(inventory, options) {
+    const taskRef = inventory.requestRef;
+    const plan = inspectTaskArtifacts(taskRef, 'plan', options);
+    if (plan.status === 'failed' || !plan.latest)
+        return contextFailure(inventory, 'ARTIFACT_INPUT_MISSING', 'latest plan artifact is required');
+    const reviewPlan = inspectTaskArtifacts(taskRef, 'review-plan', options);
+    const reviewCode = inspectTaskArtifacts(taskRef, 'review-code', options);
+    const latestCode = inventory.latest;
+    const codeMax = latestCode?.round ?? 0;
+    const reviewMax = reviewCode.latest?.round ?? 0;
+    const inputs = [plan.latest];
+    if (!latestCode) {
+        if (!reviewPlan.latest || reviewPlan.reviewedInput?.name !== plan.latest.name) {
+            return contextFailure(inventory, 'ARTIFACT_INPUT_MISSING', `latest plan '${plan.latest.name}' requires a matching approved review-plan`);
+        }
+        const verdict = parseVerdict(reviewPlan.latest.path);
+        if (!verdict.ok)
+            return contextFailure(inventory, 'ARTIFACT_REFERENCE_INVALID', verdict.message, reviewPlan.latest.name);
+        if (verdict.verdict !== 'Approved') {
+            return contextFailure(inventory, 'ARTIFACT_REFERENCE_INVALID', `latest ${reviewPlan.latest.name} is not approved`, reviewPlan.latest.name);
+        }
+        return withCodeMode(inventory, inputs, 'ready', 'init', codeMax, reviewMax, null, null, 'No prior code artifact. Starting initial implementation (round 1 -> code.md).');
+    }
+    if (reviewPlan.latest && reviewPlan.reviewedInput?.name === plan.latest.name) {
+        const verdict = parseVerdict(reviewPlan.latest.path);
+        if (verdict.ok && verdict.verdict === 'Approved' && reviewPlan.latest.mtimeMs > latestCode.mtimeMs) {
+            return withCodeMode(inventory, inputs, 'ready', 'init', codeMax, reviewMax, verdict.verdict, reviewPlan.latest.name, `Latest ${reviewPlan.latest.name} is approved and newer than the latest code artifact. Entering replan-driven init.`);
+        }
+    }
+    if (reviewMax < codeMax) {
+        const expected = artifactName('review-code', codeMax);
+        return contextFailure(inventory, 'ARTIFACT_INPUT_MISSING', `${expected} is required before another code round`, expected);
+    }
+    const review = reviewCode.latest;
+    if (!review)
+        return contextFailure(inventory, 'ARTIFACT_INPUT_MISSING', 'latest review-code artifact is required');
+    const verdict = parseVerdict(review.path);
+    if (!verdict.ok)
+        return contextFailure(inventory, 'ARTIFACT_REFERENCE_INVALID', verdict.message);
+    if (verdict.verdict === 'Approved') {
+        const decision = resolveDecisionImplementationInput(inventory, review);
+        if ('error' in decision)
+            return contextFailure(inventory, 'ARTIFACT_REFERENCE_INVALID', decision.error, review.name);
+        if (decision.input) {
+            return withCodeMode(inventory, [...inputs, review], 'ready', 'decision', codeMax, reviewMax, verdict.verdict, review.name, `Implementation input ${decision.input.id} requires a new code round.`, decision.input.id, decision.input.ledgerId, decision.input.decisionEvidence);
+        }
+    }
+    if (verdict.verdict === 'Approved' || verdict.verdict === 'Rejected') {
+        return withCodeMode(inventory, [...inputs, review], 'refused', 'refused', codeMax, reviewMax, verdict.verdict, review.name, verdict.verdict === 'Approved'
+            ? `Latest ${review.name} verdict is Approved with no findings. Nothing to fix. Run /commit to proceed.`
+            : `Latest ${review.name} verdict is Rejected. Re-plan before re-running code-task.`);
+    }
+    return withCodeMode(inventory, [...inputs, review], 'ready', 'fix', codeMax, reviewMax, verdict.verdict, review.name, `Latest ${review.name} requires or permits fixes. Entering fix mode.`);
+}
+function contextFailure(inventory, code, message, reviewArtifact = null) {
+    return { ...inventory, status: 'failed', inputs: [], codeMode: { mode: 'error', codeMax: inventory.latest?.round ?? 0, reviewMax: 0, verdict: null, reviewArtifact, implementationInput: null, decisionId: null, decisionEvidence: null, message }, error: { code, message } };
+}
+function withCodeMode(inventory, inputs, status, mode, codeMax, reviewMax, verdict, reviewArtifact, message, implementationInput = null, decisionId = null, decisionEvidence = null) {
+    return { ...inventory, status, inputs, codeMode: { mode, codeMax, reviewMax, verdict, reviewArtifact, implementationInput, decisionId, decisionEvidence, message }, error: status === 'refused' ? { code: 'ARTIFACT_MODE_REFUSED', message } : null };
+}
+function resolveDecisionImplementationInput(inventory, review) {
+    if (!inventory.taskDir)
+        return { error: 'task directory is unavailable' };
+    let content;
+    try {
+        content = fs.readFileSync(path.join(inventory.taskDir, 'task.md'), 'utf8');
+    }
+    catch (error) {
+        return { error: String(error) };
+    }
+    let rows;
+    try {
+        rows = parseImplementationInputs(content).rows;
+    }
+    catch (error) {
+        return { error: error instanceof Error ? error.message : String(error) };
+    }
+    const pending = rows.filter((row) => row.needsImplementation && row.status === 'pending');
+    if (pending.length === 0)
+        return { input: null };
+    const activity = locateActivityLog(content);
+    if (!activity)
+        return { error: 'task has no unique Activity Log section' };
+    const reviewEntries = activity.entries.filter((entry) => /^Review Code \(Round \d+\)$/.test(entry.step) && entry.note.includes(`→ ${review.name}`));
+    const completed = reviewEntries.at(-1);
+    if (!completed)
+        return { error: `cannot find completed Activity Log identity for ${review.name}` };
+    try {
+        return { input: selectPendingImplementationInput(rows, completed.time) };
+    }
+    catch (error) {
+        return { error: error instanceof Error ? error.message : String(error) };
+    }
+}
+function normalizeVerdict(value) {
+    const normalized = value.trim().toLowerCase();
+    if (normalized === '通过' || normalized === 'approved')
+        return 'Approved';
+    if (normalized === '需要修改' || normalized === 'changes requested')
+        return 'Changes Requested';
+    if (normalized === '拒绝' || normalized === 'rejected')
+        return 'Rejected';
+    return null;
+}
+function parseVerdict(file) {
+    let content;
+    try {
+        content = fs.readFileSync(file, 'utf8');
+    }
+    catch (error) {
+        return { ok: false, message: String(error) };
+    }
+    const summary = extractMarkdownSection(content, ['审查摘要', 'Review Summary']);
+    const verdictMatch = /^[-*]?\s*\*\*(?:总体结论|Overall Verdict)\*\*[:：]\s*(.+?)\s*$/im.exec(summary);
+    const verdict = verdictMatch?.[1] ? normalizeVerdict(verdictMatch[1]) : null;
+    if (!verdict)
+        return { ok: false, message: `cannot parse verdict in ${path.basename(file)}` };
+    if (verdict !== 'Approved')
+        return { ok: true, verdict };
+    const findings = /^[-*]?\s*\*\*(?:发现（AI 可处理）|Findings \(AI-actionable\))\*\*[:：]\s*(.+?)\s*$/im.exec(summary)?.[1];
+    const counts = findings?.match(/(\d+)\s*(?:阻塞项|blockers?).*?(\d+)\s*(?:主要|majors?).*?(\d+)\s*(?:次要|minors?)/i);
+    if (!counts)
+        return { ok: false, message: `cannot parse findings count in ${path.basename(file)}` };
+    return { ok: true, verdict: counts.slice(1).some((value) => Number(value) > 0) ? 'Approved-with-issues' : 'Approved' };
+}
+function validateCompletedArtifact(taskDir, family, name, round) {
+    if (path.basename(name) !== name)
+        return { ok: false, error: { code: 'ARTIFACT_PATH_INVALID', message: 'artifact must be a top-level basename' } };
+    const parsed = parseArtifactName(name);
+    if (!parsed || parsed.family !== family || (round !== undefined && parsed.round !== round)) {
+        return { ok: false, error: { code: 'ARTIFACT_IDENTITY_INVALID', message: `artifact '${name}' does not match ${family}${round ? ` round ${round}` : ''}` } };
+    }
+    const abs = path.join(taskDir, name);
+    let stat;
+    try {
+        stat = fs.lstatSync(abs);
+    }
+    catch {
+        return { ok: false, error: { code: 'ARTIFACT_NOT_FOUND', message: `artifact '${name}' is not landed` } };
+    }
+    if (stat.isSymbolicLink() || !stat.isFile())
+        return { ok: false, error: { code: 'ARTIFACT_NOT_REGULAR', message: `artifact '${name}' is not a regular file` } };
+    try {
+        fs.accessSync(abs, fs.constants.R_OK);
+    }
+    catch {
+        return { ok: false, error: { code: 'ARTIFACT_NOT_READABLE', message: `artifact '${name}' is not readable` } };
+    }
+    const inventory = inspectArtifactDirectory(taskDir, family);
+    const topology = assertWritableInventory(inventory);
+    if (topology)
+        return { ok: false, error: topology };
+    const artifact = inventory.artifacts.find((item) => item.name === name);
+    return artifact ? { ok: true, artifact } : { ok: false, error: { code: 'ARTIFACT_NOT_FOUND', message: `artifact '${name}' is not in inventory` } };
+}
+function buildArtifactLinkSection(content, artifact) {
+    const spec = familySpec(artifact.family);
+    const aliases = [...spec.sectionAliases];
+    const heading = findSectionHeading(content, aliases);
+    const english = heading === spec.sectionAliases[1];
+    const label = english
+        ? `${spec.labels[1]} (Round ${artifact.round})`
+        : `${spec.labels[0]}（Round ${artifact.round}）`;
+    const link = `[${label}](${artifact.name})`;
+    let body = extractSection(content, aliases);
+    if (body.includes(`](${artifact.name})`))
+        return { aliases, heading, body };
+    const placeholders = new Set([
+        '[分析阶段的发现。哪些文件受影响？范围是什么？]',
+        '[Findings from the analysis phase. Which files are affected? What is the scope?]',
+        '[技术方案。接口、数据流、架构决策。]',
+        '[Technical approach. Interfaces, data flow, architecture decisions.]',
+        '[实现阶段的备注。做出的决策、权衡、与设计的偏差。]',
+        '[Notes from the code phase. Decisions made, trade-offs, deviations from design.]'
+    ]);
+    const lines = body.split(/\r?\n/);
+    const placeholder = lines.findIndex((line) => placeholders.has(line.trim()));
+    if (placeholder >= 0)
+        lines[placeholder] = link;
+    else
+        lines.push(...(body ? ['', link] : [link]));
+    body = lines.join('\n').replace(/^\n+|\n+$/g, '');
+    return { aliases, heading, body };
+}
+export { artifactFamilyCatalog, artifactName, parseArtifactName, familySpec, inspectTaskArtifacts, inspectArtifactDirectory, resolveArtifactContext, assertWritableInventory, validateCompletedArtifact, buildArtifactLinkSection };
+//# sourceMappingURL=artifact-lifecycle.js.map

package/dist/lib/task/command-options.js

@@ -0,0 +1,30 @@
+function parseTaskScope(args) {
+    const positionals = [];
+    let taskRef;
+    let explicit = false;
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        let value;
+        if (arg === '--task' || arg === '-t') {
+            value = args[++index];
+            if (value === undefined || value === '' || value.startsWith('-'))
+                throw new Error(`${arg} requires a value`);
+        }
+        else if (arg.startsWith('--task=')) {
+            value = arg.slice('--task='.length);
+            if (value === '')
+                throw new Error('--task requires a value');
+        }
+        else {
+            positionals.push(arg);
+            continue;
+        }
+        if (explicit)
+            throw new Error("duplicate option '--task'");
+        taskRef = value;
+        explicit = true;
+    }
+    return { taskRef, positionals, explicit };
+}
+export { parseTaskScope };
+//# sourceMappingURL=command-options.js.map

package/dist/lib/task/commands/cat.js

@@ -1,10 +1,14 @@
 import fs from 'node:fs';
-import { resolveTaskRef } from '../resolve-ref.js';
+import { parseTaskScope } from '../command-options.js';
+import { resolveTaskContext } from '../resolve-ref.js';
 import { resolveArtifact } from '../artifacts.js';
-const USAGE = `Usage: ai task cat <N | #N | TASK-id> <artifact | N>
+const USAGE = `Usage: ai task cat <artifact | N>
+       ai task cat (--task <ref> | -t <ref>) <artifact | N>
+       ai task cat <ref> <artifact | N>
 
 Prints a task artifact's raw content to stdout.
-  <ref>            Bare numeric / '#N' short id, or a full TASK-YYYYMMDD-HHMMSS id.
+  One positional    Uses current task context and treats the operand as the artifact.
+  <ref>            Bare numeric short id, or a full TASK-YYYYMMDD-HHMMSS id.
   <artifact | N>   Artifact filename (with or without '.md'), or the number from 'ai task files'.
 `;
 function cat(args = []) {
@@ -12,12 +16,38 @@ function cat(args = []) {
         process.stdout.write(USAGE);
         return;
     }
-    if (args.length < 2) {
+    let scope;
+    try {
+        scope = parseTaskScope(args);
+    }
+    catch (error) {
+        process.stderr.write(`ai task cat: ${error instanceof Error ? error.message : String(error)}\n`);
+        process.exitCode = 1;
+        return;
+    }
+    let taskRef;
+    let artifact;
+    if (scope.explicit) {
+        if (scope.positionals.length !== 1) {
+            process.stdout.write(USAGE);
+            process.exitCode = 1;
+            return;
+        }
+        taskRef = scope.taskRef;
+        artifact = scope.positionals[0];
+    }
+    else if (scope.positionals.length === 1) {
+        artifact = scope.positionals[0];
+    }
+    else if (scope.positionals.length === 2) {
+        [taskRef, artifact] = scope.positionals;
+    }
+    else {
         process.stdout.write(USAGE);
         process.exitCode = 1;
         return;
     }
-    const resolved = resolveTaskRef(args[0]);
+    const resolved = resolveTaskContext(taskRef);
     if (!resolved.ok) {
         process.stderr.write(`ai task cat: ${resolved.message}\n`);
         process.exitCode = 1;
@@ -25,7 +55,7 @@ function cat(args = []) {
     }
     let artifactPath;
     try {
-        artifactPath = resolveArtifact(resolved.taskDir, args[1]);
+        artifactPath = resolveArtifact(resolved.taskDir, artifact);
     }
     catch (e) {
         process.stderr.write(`ai task cat: ${e.message}\n`);