@fitlab-ai/agent-infra 0.9.2 → 0.9.4

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

@@ -0,0 +1,307 @@
+import fs from 'node:fs';
+import { normalizeAgentToken } from '../agent-clients/tokens.js';
+import { resolveTaskRef } from './resolve-ref.js';
+import { locateActivityLog, appendActivityEntry } from './activity-log.js';
+import { assertWritableInventory, buildArtifactLinkSection, inspectTaskArtifacts, parseArtifactName } from './artifact-lifecycle.js';
+import { TaskExecutionLockError, withTaskExecutionLock } from './task-execution-lock.js';
+import { captureTaskWriteMetadata, writeTask } from './write.js';
+const HEAD_RE = /^[0-9a-f]{40}$/;
+const REVIEW_ACTION_RE = /^Review PR \(Round ([1-9]\d*)\)( \[started\])?$/;
+const VERDICTS = new Set(['approved', 'changes-requested', 'commented']);
+const OUTCOMES = new Set(['aborted', 'superseded']);
+const SUCCESS_STATUSES = new Set(['applied', 'no-op']);
+const ARTIFACT_STATUSES = new Set([
+    'pending', 'applied', 'no-op', 'blocked', 'failed', 'aborted', 'superseded'
+]);
+function failed(intent, code, message, taskId = null) {
+    return {
+        status: 'failed', changed: false, intent: intent.kind, taskId,
+        artifact: intent.artifact, operations: [], error: { code, message }
+    };
+}
+function inspectionFailed(code, message, taskId = null) {
+    return {
+        status: 'failed', changed: false, intent: 'pr-review-inspect', taskId,
+        snapshot: null, error: { code, message }
+    };
+}
+function parseArtifactRecord(identity) {
+    let content;
+    try {
+        content = fs.readFileSync(identity.path, 'utf8');
+    }
+    catch (error) {
+        return { code: 'ACTIVITY_ARTIFACT_READ_FAILED', message: error instanceof Error ? error.message : String(error) };
+    }
+    const heads = [...content.matchAll(/^- \*\*(?:被审 head SHA|Reviewed Head SHA)\*\*[:：]\s*([0-9a-f]{40})\s*$/gm)];
+    if (heads.length !== 1) {
+        return { code: 'ACTIVITY_ARTIFACT_INVALID', message: `${identity.name} must contain exactly one reviewed head SHA` };
+    }
+    const statuses = [...content.matchAll(/^- \*\*(?:正式 Review 状态|Formal Review Status)\*\*[:：][ \t]*([a-z-]+)[^\r\n]*$/gm)];
+    const status = statuses[0]?.[1];
+    if (statuses.length !== 1 || !status || !ARTIFACT_STATUSES.has(status)) {
+        return { code: 'ACTIVITY_ARTIFACT_INVALID', message: `${identity.name} must contain exactly one supported formal review status` };
+    }
+    return { identity, head: heads[0][1], status: status };
+}
+function toIdentity(state, terminal = false) {
+    return {
+        round: state.identity.round,
+        artifact: state.identity.name,
+        head: state.head,
+        agent: terminal ? state.terminalAgent : state.startedAgent,
+        artifactStatus: state.status,
+        note: terminal ? state.terminalNote : null
+    };
+}
+function readSnapshot(taskRef, repoRoot) {
+    const resolved = resolveTaskRef(taskRef, { repoRoot });
+    if (!resolved.ok)
+        return { ok: false, code: resolved.code, message: resolved.message, taskId: resolved.taskId };
+    if (resolved.state !== 'active') {
+        return { ok: false, code: 'TASK_STATE_MISMATCH', message: `task ${resolved.taskId} is ${resolved.state}, expected active`, taskId: resolved.taskId };
+    }
+    const inventory = inspectTaskArtifacts(taskRef, 'pr-review', { repoRoot: resolved.repoRoot });
+    if (inventory.status === 'failed') {
+        return { ok: false, code: inventory.error?.code ?? 'ACTIVITY_ARTIFACT_INVALID', message: inventory.error?.message ?? 'artifact inspection failed', taskId: resolved.taskId };
+    }
+    const topology = assertWritableInventory(inventory);
+    if (topology)
+        return { ok: false, code: topology.code, message: topology.message, taskId: resolved.taskId };
+    let content;
+    try {
+        content = fs.readFileSync(resolved.taskMdPath, 'utf8');
+    }
+    catch (error) {
+        return { ok: false, code: 'TASK_READ_FAILED', message: error instanceof Error ? error.message : String(error), taskId: resolved.taskId };
+    }
+    const activity = locateActivityLog(content);
+    if (!activity)
+        return { ok: false, code: 'ACTIVITY_SECTION_MISSING', message: 'task has no unique Activity Log section', taskId: resolved.taskId };
+    const knownRounds = new Set(inventory.artifacts.map((artifact) => artifact.round));
+    for (const entry of activity.entries) {
+        const match = REVIEW_ACTION_RE.exec(entry.step);
+        if (match && !knownRounds.has(Number(match[1]))) {
+            return { ok: false, code: 'ACTIVITY_STATE_CONFLICT', message: `Activity Log round ${match[1]} has no canonical pr-review artifact`, taskId: resolved.taskId };
+        }
+    }
+    const states = [];
+    for (const identity of inventory.artifacts) {
+        const parsed = parseArtifactRecord(identity);
+        if ('code' in parsed)
+            return { ok: false, ...parsed, taskId: resolved.taskId };
+        const base = `Review PR (Round ${identity.round})`;
+        const started = activity.entries.filter((entry) => entry.step === `${base} [started]`);
+        const terminal = activity.entries.filter((entry) => entry.step === base);
+        if (started.length > 1 || terminal.length > 1) {
+            return { ok: false, code: 'ACTIVITY_STATE_CONFLICT', message: `${base} has duplicate started or terminal rows`, taskId: resolved.taskId };
+        }
+        if (terminal.length === 1 && started.length === 0 && !terminal[0].note.startsWith('receipt ')) {
+            return { ok: false, code: 'ACTIVITY_STATE_CONFLICT', message: `${base} has a terminal row without a matching started row`, taskId: resolved.taskId };
+        }
+        if (terminal.length === 1) {
+            const note = terminal[0].note;
+            const terminalMatchesStatus = (note.startsWith('Verdict: ') && SUCCESS_STATUSES.has(parsed.status))
+                || (note.startsWith('Outcome: Aborted, ') && parsed.status === 'aborted')
+                || (note.startsWith('Outcome: Superseded, ') && parsed.status === 'superseded')
+                || (note.startsWith('receipt ') && SUCCESS_STATUSES.has(parsed.status));
+            if (!terminalMatchesStatus) {
+                return { ok: false, code: 'ACTIVITY_STATE_CONFLICT', message: `${base} terminal note conflicts with artifact status ${parsed.status}`, taskId: resolved.taskId };
+            }
+        }
+        states.push({
+            ...parsed,
+            startedAgent: started[0]?.agent ?? null,
+            terminalAgent: terminal[0]?.agent ?? null,
+            terminalNote: terminal[0]?.note ?? null
+        });
+    }
+    const openStates = states.filter((state) => state.startedAgent !== null && state.terminalNote === null);
+    const preparedStates = states.filter((state) => state.status === 'pending' && state.startedAgent === null && state.terminalNote === null);
+    if (openStates.length > 1 || preparedStates.length > 1) {
+        return { ok: false, code: 'ACTIVITY_STATE_CONFLICT', message: 'multiple prepared or open PR review rounds exist', taskId: resolved.taskId };
+    }
+    const terminalStates = states.filter((state) => state.terminalNote !== null);
+    const successfulStates = states.filter((state) => SUCCESS_STATUSES.has(state.status));
+    const latestTerminal = terminalStates.at(-1) ?? null;
+    const latestSuccessful = successfulStates.at(-1) ?? null;
+    return {
+        ok: true,
+        taskId: resolved.taskId,
+        taskDir: resolved.taskDir,
+        taskMdPath: resolved.taskMdPath,
+        repoRoot: resolved.repoRoot,
+        content,
+        states,
+        snapshot: {
+            nextRound: inventory.next?.round ?? 1,
+            prepared: preparedStates[0] ? toIdentity(preparedStates[0]) : null,
+            open: openStates[0] ? toIdentity(openStates[0]) : null,
+            latestTerminal: latestTerminal ? toIdentity(latestTerminal, true) : null,
+            latestSuccessful: latestSuccessful ? toIdentity(latestSuccessful, true) : null
+        }
+    };
+}
+export function inspectPrReviewActivity(intent, options = {}) {
+    const state = readSnapshot(intent.taskRef, options.repoRoot);
+    if (!state.ok)
+        return inspectionFailed(state.code, state.message, state.taskId);
+    return { status: 'ready', changed: false, intent: intent.kind, taskId: state.taskId, snapshot: state.snapshot, error: null };
+}
+function validateIntent(intent) {
+    const agent = normalizeAgentToken(intent.agent);
+    if (!agent)
+        return { code: 'ACTIVITY_INTENT_INVALID', message: 'agent must be a supported collaborator token' };
+    const artifact = parseArtifactName(intent.artifact);
+    if (!artifact || artifact.family !== 'pr-review') {
+        return { code: 'ACTIVITY_ARTIFACT_INVALID', message: `artifact '${intent.artifact}' is not a canonical pr-review artifact` };
+    }
+    if (!HEAD_RE.test(intent.head))
+        return { code: 'ACTIVITY_INTENT_INVALID', message: 'head must be a lowercase 40-character SHA' };
+    if (intent.kind === 'pr-review-complete') {
+        if (!VERDICTS.has(intent.verdict))
+            return { code: 'ACTIVITY_INTENT_INVALID', message: 'verdict is invalid' };
+        if (![intent.blockers, intent.major, intent.minor].every((value) => Number.isSafeInteger(value) && value >= 0)) {
+            return { code: 'ACTIVITY_INTENT_INVALID', message: 'finding counts must be non-negative safe integers' };
+        }
+    }
+    if (intent.kind === 'pr-review-terminate') {
+        if (!OUTCOMES.has(intent.outcome))
+            return { code: 'ACTIVITY_INTENT_INVALID', message: 'outcome is invalid' };
+        if (!intent.reason.trim() || /[\r\n]/.test(intent.reason) || intent.reason !== intent.reason.trim()) {
+            return { code: 'ACTIVITY_INTENT_INVALID', message: 'reason must be a non-empty trimmed single-line value' };
+        }
+    }
+    return { agent, artifact };
+}
+function verdictLabel(verdict) {
+    if (verdict === 'approved')
+        return 'Approved';
+    if (verdict === 'changes-requested')
+        return 'Changes Requested';
+    return 'Commented';
+}
+function outcomeLabel(outcome) {
+    return outcome === 'aborted' ? 'Aborted' : 'Superseded';
+}
+function terminalNote(intent) {
+    if (intent.kind === 'pr-review-complete') {
+        return `Verdict: ${verdictLabel(intent.verdict)}, blockers: ${intent.blockers}, major: ${intent.major}, minor: ${intent.minor} → ${intent.artifact}`;
+    }
+    return `Outcome: ${outcomeLabel(intent.outcome)}, reason: ${intent.reason} → ${intent.artifact}`;
+}
+function applyLocked(intent, normalizedAgent, options) {
+    const state = readSnapshot(intent.taskRef, options.repoRoot);
+    if (!state.ok)
+        return failed(intent, state.code, state.message, state.taskId);
+    const parsed = parseArtifactName(intent.artifact);
+    const roundState = state.states.find((item) => item.identity.name === parsed.name);
+    if (!roundState)
+        return failed(intent, 'ACTIVITY_ARTIFACT_INVALID', `artifact '${intent.artifact}' is not landed`, state.taskId);
+    if (roundState.head !== intent.head) {
+        return failed(intent, 'ACTIVITY_IDENTITY_MISMATCH', `head does not match ${intent.artifact}`, state.taskId);
+    }
+    const base = `Review PR (Round ${parsed.round})`;
+    let step;
+    let note;
+    let linkArtifact = false;
+    if (intent.kind === 'pr-review-start') {
+        if (roundState.terminalNote !== null) {
+            return failed(intent, 'ACTIVITY_STATE_CONFLICT', `${base} is already terminal`, state.taskId);
+        }
+        if (roundState.startedAgent !== null) {
+            return { status: 'no-op', changed: false, intent: intent.kind, taskId: state.taskId, artifact: intent.artifact, operations: [], error: null };
+        }
+        if (roundState.status !== 'pending') {
+            return failed(intent, 'ACTIVITY_STATE_CONFLICT', `${intent.artifact} must be pending before start`, state.taskId);
+        }
+        if (state.snapshot.open && state.snapshot.open.artifact !== intent.artifact) {
+            return failed(intent, 'ACTIVITY_STATE_CONFLICT', `another PR review round is open: ${state.snapshot.open.artifact}`, state.taskId);
+        }
+        step = `${base} [started]`;
+        note = 'started';
+    }
+    else {
+        note = terminalNote(intent);
+        if (roundState.terminalNote !== null) {
+            if (roundState.terminalNote === note) {
+                return { status: 'no-op', changed: false, intent: intent.kind, taskId: state.taskId, artifact: intent.artifact, operations: [], error: null };
+            }
+            return failed(intent, 'ACTIVITY_STATE_CONFLICT', `${base} has a different terminal payload`, state.taskId);
+        }
+        if (roundState.startedAgent === null) {
+            return failed(intent, 'ACTIVITY_STATE_CONFLICT', `${base} has no matching started row`, state.taskId);
+        }
+        if (intent.kind === 'pr-review-complete' && !SUCCESS_STATUSES.has(roundState.status)) {
+            return failed(intent, 'ACTIVITY_STATE_CONFLICT', `${intent.artifact} must be applied or no-op before completion`, state.taskId);
+        }
+        if (intent.kind === 'pr-review-terminate' && roundState.status !== intent.outcome) {
+            return failed(intent, 'ACTIVITY_STATE_CONFLICT', `${intent.artifact} status must match outcome ${intent.outcome}`, state.taskId);
+        }
+        step = base;
+        linkArtifact = true;
+    }
+    let metadata;
+    try {
+        metadata = (options.metadataProvider ?? captureTaskWriteMetadata)();
+    }
+    catch (error) {
+        return failed(intent, 'METADATA_CAPTURE_FAILED', error instanceof Error ? error.message : String(error), state.taskId);
+    }
+    const section = locateActivityLog(state.content);
+    const mutations = [{
+            kind: 'section', aliases: ['活动日志', 'Activity Log'], heading: section.heading,
+            body: appendActivityEntry(section, { time: metadata.timestamp, step, agent: normalizedAgent, note })
+        }];
+    if (linkArtifact) {
+        const link = buildArtifactLinkSection(state.content, roundState.identity);
+        mutations.push({ kind: 'section', aliases: link.aliases, heading: link.heading, body: link.body });
+    }
+    const writeResult = writeTask({
+        taskRef: intent.taskRef,
+        expectedState: 'active',
+        mutations,
+        dryRun: intent.dryRun
+    }, {
+        ...options,
+        taskLocation: {
+            repoRoot: state.repoRoot,
+            taskId: state.taskId,
+            taskMdPath: state.taskMdPath,
+            state: 'active'
+        },
+        metadataProvider: () => metadata
+    });
+    if (writeResult.status === 'failed') {
+        return failed(intent, writeResult.error.code, writeResult.error.message, writeResult.taskId);
+    }
+    return {
+        status: writeResult.status,
+        changed: writeResult.changed,
+        intent: intent.kind,
+        taskId: writeResult.taskId,
+        artifact: intent.artifact,
+        operations: writeResult.operations,
+        error: null
+    };
+}
+export function applyPrReviewActivityIntent(intent, options = {}) {
+    const validated = validateIntent(intent);
+    if ('code' in validated)
+        return failed(intent, validated.code, validated.message);
+    const resolved = resolveTaskRef(intent.taskRef, { repoRoot: options.repoRoot });
+    if (!resolved.ok)
+        return failed(intent, resolved.code, resolved.message, resolved.taskId);
+    if (resolved.state !== 'active') {
+        return failed(intent, 'TASK_STATE_MISMATCH', `task ${resolved.taskId} is ${resolved.state}, expected active`, resolved.taskId);
+    }
+    try {
+        return withTaskExecutionLock(resolved.repoRoot, resolved.taskId, `task-activity:${intent.kind}`, () => applyLocked(intent, validated.agent, { ...options, repoRoot: resolved.repoRoot }), options.lockOptions);
+    }
+    catch (error) {
+        if (error instanceof TaskExecutionLockError)
+            return failed(intent, error.code, error.message, resolved.taskId);
+        return failed(intent, 'ACTIVITY_LOCK_FAILED', error instanceof Error ? error.message : String(error), resolved.taskId);
+    }
+}
+//# sourceMappingURL=activity-intent.js.map

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

@@ -12,7 +12,8 @@ const artifactFamilyCatalog = [
     { 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'] }
+    { family: 'manual-validation', sectionAliases: ['实现备注', 'Implementation Notes'], heading: '实现备注', labels: ['人工验证', 'Manual Validation'] },
+    { family: 'pr-review', sectionAliases: ['审查反馈', 'Review Feedback'], heading: '审查反馈', labels: ['PR 审查报告', 'PR Review Report'] }
 ];
 const FAMILY_SET = new Set(artifactFamilyCatalog.map((item) => item.family));
 const BLOCKING_DIAGNOSTICS = new Set([

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

@@ -1,4 +1,5 @@
 import fs from 'node:fs';
+import { classifyAgent } from '../../agent-clients/tokens.js';
 import { formatTable } from '../../table.js';
 import { parseTaskScope } from '../command-options.js';
 import { resolveTaskContext } from '../resolve-ref.js';
@@ -30,11 +31,11 @@ const TABLE_HEADERS = ['#', 'STEP', 'AGENT', 'STARTED', 'DONE', 'NOTE'];
 // with ` [started]`; the matching done entry carries the identical base action
 // without the suffix. Pairing therefore keys on the base action (including any
 // `(Round N)`), so every round and every repeated execution pairs on its own.
-// Short agent tokens that actually appear in activity logs for AI executors
-// (workflow recommended_agents claude/codex/gemini/cursor + enabled TUI opencode;
-// note these differ from the `.airc.json` long names claude-code/gemini-cli).
-// Any other executor token (a human name, possibly CJK) is treated as human.
-const KNOWN_AI_AGENTS = new Set(['claude', 'codex', 'gemini', 'opencode', 'cursor']);
+// Known AI tokens, long-name mapping, and loose rendering classification live
+// in lib/agent-clients/tokens.ts (single source of truth shared with the
+// write-side internal commands). Any other executor token (a human name,
+// possibly CJK, or an unknown value) is rendered as human with a visible
+// `(unknown)` marker.
 const REVIEW_STAGE_PREFIXES = [
     { prefix: 'Review Analysis', stage: 'analysis' },
     { prefix: 'Review Plan', stage: 'plan' },
@@ -83,12 +84,11 @@ function humanValidationCount(note) {
 function isHumanCountField(field) {
     return fieldNumber(field, 'manual-validation') !== undefined || fieldNumber(field, 'human-decision') !== undefined;
 }
-// A step is human-executed when its agent token is not a known AI token. Take
-// the first whitespace-delimited token and drop any trailing parenthetical
-// annotation (e.g. `张三 (executed on host)` -> `张三`) before the lookup.
-function isHumanAgent(agent) {
-    const token = agent.trim().split(/\s+/)[0]?.replace(/\(.*$/, '') ?? '';
-    return token !== '' && !KNOWN_AI_AGENTS.has(token);
+// A step is human-executed when its agent token is not a known AI token.
+// Known long names (claude-code -> claude, gemini-cli -> gemini) classify as
+// AI; empty or unknown tokens classify as non-AI (human).
+export function isHumanAgent(agent) {
+    return classifyAgent(agent).status !== 'ai';
 }
 // Fold the two human counts into a review row's verdict NOTE: comma-joined, right
 // after the blockers/major/minor list and before the ` → artifact` link, mirroring
@@ -148,8 +148,9 @@ function log(args = []) {
         const note = stage
             ? foldHumanCounts(s.note, humanDecisionCounts.get(stage) ?? 0, humanValidationCount(s.note))
             : s.note;
-        const human = isHumanAgent(s.agent);
-        const agent = human ? 'human' : s.agent;
+        const { status, display } = classifyAgent(s.agent);
+        const human = status !== 'ai';
+        const agent = status === 'unknown' ? `${display} (unknown)` : display;
         const started = s.started || (human ? '-' : '');
         return [String(idx + 1), s.step, agent, started, s.done || (s.started ? '(in progress)' : ''), note];
     });
@@ -158,5 +159,5 @@ function log(args = []) {
     }
     process.stdout.write(`Total: ${steps.length} steps\n`);
 }
-export { log, isHumanAgent };
+export { log };
 //# sourceMappingURL=log.js.map

package/dist/lib/task/commit-finalization.js

@@ -0,0 +1,267 @@
+import { execFileSync, spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { locateActivityLog, appendActivityEntry, pairEntries } from './activity-log.js';
+import { commitIntentPath, digest, readCommitIntent } from './commit-intent.js';
+import { parseTypedTaskFrontmatter } from './frontmatter.js';
+import { parseReviewSummary } from './review-artifacts.js';
+import { extractReviewBaseline, extractReviewedSnapshotTree, findAuthoritativeReviewCodeArtifact } from './review-fingerprint.js';
+const SHA_RE = /^[a-f0-9]{40,64}$/;
+function git(repoRoot, args) {
+    return execFileSync('git', args, {
+        cwd: repoRoot,
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'pipe']
+    }).trim();
+}
+function commitExists(repoRoot, value) {
+    return SHA_RE.test(value) && spawnSync('git', ['cat-file', '-e', `${value}^{commit}`], {
+        cwd: repoRoot,
+        stdio: 'ignore'
+    }).status === 0;
+}
+function isAncestor(repoRoot, ancestor, descendant) {
+    return spawnSync('git', ['merge-base', '--is-ancestor', ancestor, descendant], {
+        cwd: repoRoot,
+        stdio: 'ignore'
+    }).status === 0;
+}
+function outcome(disposition, overrides = {}) {
+    return {
+        disposition,
+        code: null,
+        message: disposition,
+        currentHead: '',
+        committedHead: null,
+        commitNote: null,
+        needsAnchor: false,
+        needsLog: false,
+        intent: null,
+        intentDigest: null,
+        ...overrides
+    };
+}
+function invalid(message, currentHead = '', code = 'COMMIT_FINALIZATION_EVIDENCE_INVALID', overrides = {}) {
+    return outcome('invalid', { code, message, currentHead, ...overrides });
+}
+function inspectCommitFinalization(taskDir, repoRoot, taskId) {
+    let currentHead;
+    let taskContent;
+    let metadata;
+    try {
+        currentHead = git(repoRoot, ['rev-parse', 'HEAD']);
+        taskContent = fs.readFileSync(path.join(taskDir, 'task.md'), 'utf8');
+        metadata = parseTypedTaskFrontmatter(taskContent);
+    }
+    catch (error) {
+        return invalid(error instanceof Error ? error.message : String(error));
+    }
+    const activity = locateActivityLog(taskContent);
+    if (!activity)
+        return invalid('task activity log is missing or ambiguous', currentHead);
+    const commitRows = pairEntries(activity.entries).filter((row) => row.step === 'Commit');
+    const openRows = commitRows.filter((row) => row.started !== '' && row.done === '');
+    const file = commitIntentPath(taskDir);
+    if (!fs.existsSync(file)) {
+        if (openRows.length > 0) {
+            return outcome('orphaned-start', {
+                code: 'COMMIT_FINALIZATION_EVIDENCE_MISSING',
+                message: 'an open Commit activity entry exists without a commit intent',
+                currentHead
+            });
+        }
+        return outcome('idle', { message: 'no active commit finalization exists', currentHead });
+    }
+    let raw;
+    let intent;
+    try {
+        raw = fs.readFileSync(file, 'utf8');
+        intent = readCommitIntent(taskDir, taskId);
+    }
+    catch (error) {
+        return invalid(error instanceof Error ? error.message : String(error), currentHead);
+    }
+    const intentDigest = digest(raw);
+    const shared = { currentHead, intent, intentDigest, committedHead: intent.committedHead };
+    if (!commitExists(repoRoot, intent.baselineHead)) {
+        return invalid('commit intent baseline is not a valid Git commit', currentHead, 'COMMIT_FINALIZATION_EVIDENCE_INVALID', shared);
+    }
+    if (intent.phase === 'prepared') {
+        if (intent.committedHead !== null || intent.pushEvidence !== null) {
+            return invalid('prepared commit intent contains commit or push evidence', currentHead, 'COMMIT_FINALIZATION_EVIDENCE_INVALID', shared);
+        }
+        if (currentHead !== intent.baselineHead || openRows.length !== 1) {
+            return outcome('conflict', {
+                ...shared,
+                code: 'COMMIT_FINALIZATION_CONFLICT',
+                message: 'prepared commit intent does not match HEAD and exactly one open Commit entry'
+            });
+        }
+        return outcome('prepared', { ...shared, message: 'prepared commit intent can be safely retried' });
+    }
+    if (!intent.committedHead || !commitExists(repoRoot, intent.committedHead)) {
+        return invalid('committed intent head is missing or invalid', currentHead, 'COMMIT_FINALIZATION_EVIDENCE_INVALID', shared);
+    }
+    if (intent.phase === 'committed' && intent.pushEvidence !== null) {
+        return invalid('committed intent contains premature push evidence', currentHead, 'COMMIT_FINALIZATION_EVIDENCE_INVALID', shared);
+    }
+    if (intent.phase === 'pushed'
+        && (intent.pushEvidence === null
+            || intent.pushEvidence.head !== intent.committedHead
+            || !intent.pushEvidence.remote
+            || !intent.pushEvidence.ref)) {
+        return invalid('pushed intent evidence is missing or inconsistent', currentHead, 'COMMIT_FINALIZATION_EVIDENCE_INVALID', shared);
+    }
+    if (currentHead !== intent.committedHead || !isAncestor(repoRoot, intent.baselineHead, intent.committedHead)) {
+        return outcome('conflict', {
+            ...shared,
+            code: 'COMMIT_FINALIZATION_CONFLICT',
+            message: 'repository HEAD or ancestry conflicts with the commit intent'
+        });
+    }
+    const review = findAuthoritativeReviewCodeArtifact(taskDir);
+    let needsAnchor = false;
+    if (review.ok && review.path) {
+        let reviewContent;
+        try {
+            reviewContent = fs.readFileSync(review.path, 'utf8');
+        }
+        catch (error) {
+            return invalid(error instanceof Error ? error.message : String(error), currentHead, 'COMMIT_FINALIZATION_EVIDENCE_MISSING', shared);
+        }
+        const summary = parseReviewSummary(reviewContent);
+        const reviewBaseline = extractReviewBaseline(reviewContent);
+        const reviewTree = extractReviewedSnapshotTree(reviewContent);
+        if (!summary.ok || summary.summary.verdict !== 'Approved' || !commitExists(repoRoot, reviewBaseline) || !SHA_RE.test(reviewTree)) {
+            return invalid('authoritative review-code evidence is not a valid approved snapshot', currentHead, 'COMMIT_FINALIZATION_EVIDENCE_INVALID', shared);
+        }
+        const committedTree = git(repoRoot, ['rev-parse', `${intent.committedHead}^{tree}`]);
+        if (reviewBaseline !== intent.baselineHead || reviewTree !== committedTree) {
+            return outcome('conflict', {
+                ...shared,
+                code: 'COMMIT_FINALIZATION_CONFLICT',
+                message: 'review baseline or snapshot tree conflicts with the committed intent'
+            });
+        }
+        const anchor = String(metadata.last_reviewed_commit ?? '').trim();
+        if (anchor && anchor !== intent.committedHead) {
+            return outcome('conflict', {
+                ...shared,
+                code: 'COMMIT_FINALIZATION_CONFLICT',
+                message: 'task review anchor conflicts with the committed intent'
+            });
+        }
+        needsAnchor = anchor === '';
+    }
+    const commitNote = git(repoRoot, ['show', '-s', '--format=%h%x20%s', intent.committedHead]);
+    const matchingDone = commitRows.filter((row) => row.done !== '' && row.note === commitNote);
+    const needsLog = matchingDone.length === 0 && openRows.length === 1;
+    if (!(needsLog || (matchingDone.length === 1 && openRows.length === 0))) {
+        return outcome('conflict', {
+            ...shared,
+            code: 'COMMIT_FINALIZATION_CONFLICT',
+            message: 'Commit activity identity is missing, duplicated, or ambiguous',
+            commitNote
+        });
+    }
+    return outcome('recoverable', {
+        ...shared,
+        message: 'commit finalization can be recovered',
+        commitNote,
+        needsAnchor,
+        needsLog
+    });
+}
+function planCommitTaskFinalization(taskDir, inspection, agent, timestamp) {
+    if (inspection.disposition !== 'recoverable' || !inspection.committedHead || !inspection.commitNote) {
+        throw new Error('commit finalization task mutations require a recoverable inspection');
+    }
+    const taskContent = fs.readFileSync(path.join(taskDir, 'task.md'), 'utf8');
+    const frontmatter = { assigned_to: agent };
+    if (inspection.needsAnchor)
+        frontmatter.last_reviewed_commit = inspection.committedHead;
+    const mutations = [{
+            kind: 'frontmatter',
+            set: frontmatter
+        }];
+    if (inspection.needsLog) {
+        const activity = locateActivityLog(taskContent);
+        if (!activity)
+            throw new Error('task activity log is missing or ambiguous');
+        mutations.push({
+            kind: 'section',
+            aliases: ['活动日志', 'Activity Log'],
+            heading: activity.heading,
+            body: appendActivityEntry(activity, {
+                time: timestamp,
+                step: 'Commit',
+                agent,
+                note: inspection.commitNote
+            })
+        });
+    }
+    return { mutations, commitNote: inspection.commitNote };
+}
+function inspectCreatePrCommitGate(taskDir, repoRoot, taskId) {
+    const lifecycle = inspectCommitFinalization(taskDir, repoRoot, taskId);
+    if (lifecycle.disposition !== 'idle') {
+        const pending = lifecycle.disposition === 'prepared' || lifecycle.disposition === 'recoverable';
+        return {
+            allowed: false,
+            code: pending ? 'COMMIT_FINALIZATION_PENDING' : lifecycle.code ?? 'COMMIT_FINALIZATION_CONFLICT',
+            message: pending ? 'commit finalization must complete before creating a pull request' : lifecycle.message,
+            disposition: lifecycle.disposition,
+            action: 'rerun-commit'
+        };
+    }
+    const review = findAuthoritativeReviewCodeArtifact(taskDir);
+    if (!review.ok || !review.path) {
+        return { allowed: true, code: null, message: 'no review-code history requires an anchor', disposition: 'idle', action: 'continue' };
+    }
+    try {
+        const content = fs.readFileSync(review.path, 'utf8');
+        const summary = parseReviewSummary(content);
+        if (!summary.ok || summary.summary.verdict !== 'Approved') {
+            return {
+                allowed: false,
+                code: 'COMMIT_FINALIZATION_EVIDENCE_INVALID',
+                message: 'latest authoritative review-code is not approved',
+                disposition: 'idle',
+                action: 'rerun-review-code'
+            };
+        }
+        const task = parseTypedTaskFrontmatter(fs.readFileSync(path.join(taskDir, 'task.md'), 'utf8'));
+        const currentHead = git(repoRoot, ['rev-parse', 'HEAD']);
+        const anchor = String(task.last_reviewed_commit ?? '').trim();
+        if (!anchor || !commitExists(repoRoot, anchor)) {
+            return {
+                allowed: false,
+                code: 'COMMIT_FINALIZATION_EVIDENCE_MISSING',
+                message: 'approved review snapshot is not anchored to a Git commit',
+                disposition: 'idle',
+                action: 'rerun-commit'
+            };
+        }
+        if (anchor !== currentHead || extractReviewedSnapshotTree(content) !== git(repoRoot, ['rev-parse', 'HEAD^{tree}'])) {
+            return {
+                allowed: false,
+                code: 'COMMIT_FINALIZATION_CONFLICT',
+                message: 'approved review anchor or tree does not match repository HEAD',
+                disposition: 'idle',
+                action: 'rerun-review-code'
+            };
+        }
+        return { allowed: true, code: null, message: 'commit finalization evidence is complete', disposition: 'idle', action: 'continue' };
+    }
+    catch (error) {
+        return {
+            allowed: false,
+            code: 'COMMIT_FINALIZATION_EVIDENCE_INVALID',
+            message: error instanceof Error ? error.message : String(error),
+            disposition: 'idle',
+            action: 'rerun-review-code'
+        };
+    }
+}
+export { inspectCommitFinalization, inspectCreatePrCommitGate, planCommitTaskFinalization };
+//# sourceMappingURL=commit-finalization.js.map