@fitlab-ai/agent-infra 0.9.2 → 0.9.4

package/lib/task/commit-finalization.ts

@@ -0,0 +1,356 @@
+import { execFileSync, spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { locateActivityLog, appendActivityEntry, pairEntries } from './activity-log.ts';
+import { commitIntentPath, digest, readCommitIntent } from './commit-intent.ts';
+import type { CommitIntent } from './commit-intent.ts';
+import { parseTypedTaskFrontmatter } from './frontmatter.ts';
+import { parseReviewSummary } from './review-artifacts.ts';
+import {
+  extractReviewBaseline,
+  extractReviewedSnapshotTree,
+  findAuthoritativeReviewCodeArtifact
+} from './review-fingerprint.ts';
+import type { TaskMutation } from './write.ts';
+
+type CommitFinalizationDisposition =
+  | 'idle'
+  | 'prepared'
+  | 'recoverable'
+  | 'invalid'
+  | 'conflict'
+  | 'orphaned-start';
+
+type CommitFinalizationCode =
+  | 'COMMIT_FINALIZATION_PENDING'
+  | 'COMMIT_FINALIZATION_EVIDENCE_MISSING'
+  | 'COMMIT_FINALIZATION_EVIDENCE_INVALID'
+  | 'COMMIT_FINALIZATION_CONFLICT';
+
+type CommitFinalizationInspection = Readonly<{
+  disposition: CommitFinalizationDisposition;
+  code: CommitFinalizationCode | null;
+  message: string;
+  currentHead: string;
+  committedHead: string | null;
+  commitNote: string | null;
+  needsAnchor: boolean;
+  needsLog: boolean;
+  intent: CommitIntent | null;
+  intentDigest: string | null;
+}>;
+
+type CreatePrCommitGate = Readonly<{
+  allowed: boolean;
+  code: CommitFinalizationCode | null;
+  message: string;
+  disposition: CommitFinalizationDisposition;
+  action: 'continue' | 'rerun-commit' | 'rerun-review-code';
+}>;
+
+type CommitTaskFinalizationPlan = Readonly<{
+  mutations: readonly TaskMutation[];
+  commitNote: string;
+}>;
+
+const SHA_RE = /^[a-f0-9]{40,64}$/;
+
+function git(repoRoot: string, args: string[]): string {
+  return execFileSync('git', args, {
+    cwd: repoRoot,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe']
+  }).trim();
+}
+
+function commitExists(repoRoot: string, value: string): boolean {
+  return SHA_RE.test(value) && spawnSync('git', ['cat-file', '-e', `${value}^{commit}`], {
+    cwd: repoRoot,
+    stdio: 'ignore'
+  }).status === 0;
+}
+
+function isAncestor(repoRoot: string, ancestor: string, descendant: string): boolean {
+  return spawnSync('git', ['merge-base', '--is-ancestor', ancestor, descendant], {
+    cwd: repoRoot,
+    stdio: 'ignore'
+  }).status === 0;
+}
+
+function outcome(
+  disposition: CommitFinalizationDisposition,
+  overrides: Partial<CommitFinalizationInspection> = {}
+): CommitFinalizationInspection {
+  return {
+    disposition,
+    code: null,
+    message: disposition,
+    currentHead: '',
+    committedHead: null,
+    commitNote: null,
+    needsAnchor: false,
+    needsLog: false,
+    intent: null,
+    intentDigest: null,
+    ...overrides
+  };
+}
+
+function invalid(
+  message: string,
+  currentHead = '',
+  code: CommitFinalizationCode = 'COMMIT_FINALIZATION_EVIDENCE_INVALID',
+  overrides: Partial<CommitFinalizationInspection> = {}
+): CommitFinalizationInspection {
+  return outcome('invalid', { code, message, currentHead, ...overrides });
+}
+
+function inspectCommitFinalization(
+  taskDir: string,
+  repoRoot: string,
+  taskId: string
+): CommitFinalizationInspection {
+  let currentHead: string;
+  let taskContent: string;
+  let metadata: ReturnType<typeof parseTypedTaskFrontmatter>;
+  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: string;
+  let intent: CommitIntent;
+  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: string;
+    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: string,
+  inspection: CommitFinalizationInspection,
+  agent: string,
+  timestamp: string
+): CommitTaskFinalizationPlan {
+  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: Record<string, string> = { assigned_to: agent };
+  if (inspection.needsAnchor) frontmatter.last_reviewed_commit = inspection.committedHead;
+  const mutations: TaskMutation[] = [{
+    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: string, repoRoot: string, taskId: string): CreatePrCommitGate {
+  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
+};
+export type {
+  CommitFinalizationCode,
+  CommitFinalizationDisposition,
+  CommitFinalizationInspection,
+  CommitTaskFinalizationPlan,
+  CreatePrCommitGate
+};

package/lib/task/commit-intent.ts

@@ -0,0 +1,230 @@
+import { createHash, randomBytes, randomUUID, timingSafeEqual } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+import type { DelegationReceipt } from './delegation-receipts.ts';
+
+type CommitIntentPhase = 'prepared' | 'committed' | 'pushed';
+type PushEvidence = Readonly<{ remote: string; ref: string; head: string }>;
+type CommitIntentOrchestration = Readonly<{
+  runId: string;
+  receiptId: string;
+  authorizationIssuedAt: string;
+  sourceRunDigest: string;
+  plannedRunDigest: string;
+  completionUpdatedAt: string;
+  plannedReceipt: DelegationReceipt;
+}>;
+type CommitIntent = Readonly<{
+  schemaVersion: 1;
+  taskId: string;
+  mode: 'standalone' | 'orchestrated';
+  phase: CommitIntentPhase;
+  tokenDigest: string;
+  baselineHead: string;
+  committedHead: string | null;
+  pushEvidence: PushEvidence | null;
+  orchestration: CommitIntentOrchestration | null;
+  createdAt: string;
+  updatedAt: string;
+}>;
+type CommitIntentInput = Omit<CommitIntent, 'schemaVersion' | 'tokenDigest'>;
+
+class CommitIntentError extends Error {
+  readonly code: string;
+
+  constructor(code: string, message: string) {
+    super(message);
+    this.name = 'CommitIntentError';
+    this.code = code;
+  }
+}
+
+function commitIntentPath(taskDir: string): string {
+  return path.join(taskDir, 'commit-intent.json');
+}
+
+function digest(value: string | Buffer): string {
+  return createHash('sha256').update(value).digest('hex');
+}
+
+function serialize(value: unknown): string {
+  return `${JSON.stringify(value, null, 2)}\n`;
+}
+
+function atomicWrite(file: string, value: CommitIntent): void {
+  const temp = `${file}.${process.pid}.${randomUUID()}.tmp`;
+  try {
+    fs.writeFileSync(temp, serialize(value), { encoding: 'utf8', flag: 'wx', mode: 0o600 });
+    const handle = fs.openSync(temp, 'r+');
+    try {
+      fs.fsyncSync(handle);
+    } finally {
+      fs.closeSync(handle);
+    }
+    fs.renameSync(temp, file);
+    fs.chmodSync(file, 0o600);
+    try {
+      const directory = fs.openSync(path.dirname(file), 'r');
+      try {
+        fs.fsyncSync(directory);
+      } finally {
+        fs.closeSync(directory);
+      }
+    } catch (error) {
+      const code = (error as NodeJS.ErrnoException).code;
+      if (!['EACCES', 'EISDIR', 'EINVAL', 'EPERM'].includes(code ?? '')) throw error;
+    }
+  } finally {
+    if (fs.existsSync(temp)) fs.unlinkSync(temp);
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function keysEqual(value: Record<string, unknown>, expected: readonly string[]): boolean {
+  return Object.keys(value).sort().join('\0') === [...expected].sort().join('\0');
+}
+
+function validPushEvidence(value: unknown): value is PushEvidence | null {
+  return value === null || (
+    isRecord(value)
+    && keysEqual(value, ['remote', 'ref', 'head'])
+    && ['remote', 'ref', 'head'].every((key) => typeof value[key] === 'string' && value[key] !== '')
+  );
+}
+
+function validOrchestration(value: unknown): value is CommitIntentOrchestration | null {
+  if (value === null) return true;
+  if (!isRecord(value) || !keysEqual(value, [
+    'runId', 'receiptId', 'authorizationIssuedAt', 'sourceRunDigest', 'plannedRunDigest',
+    'completionUpdatedAt', 'plannedReceipt'
+  ])) return false;
+  return [
+    'runId', 'receiptId', 'authorizationIssuedAt', 'sourceRunDigest', 'plannedRunDigest', 'completionUpdatedAt'
+  ].every((key) => typeof value[key] === 'string' && value[key] !== '') && isRecord(value.plannedReceipt);
+}
+
+function parseIntent(raw: string, taskId: string): CommitIntent {
+  let value: unknown;
+  try {
+    value = JSON.parse(raw);
+  } catch {
+    throw new CommitIntentError('ORCHESTRATION_COMMIT_INTENT_INVALID', 'commit intent is not valid JSON');
+  }
+  if (!isRecord(value) || !keysEqual(value, [
+    'schemaVersion', 'taskId', 'mode', 'phase', 'tokenDigest', 'baselineHead', 'committedHead',
+    'pushEvidence', 'orchestration', 'createdAt', 'updatedAt'
+  ])) {
+    throw new CommitIntentError('ORCHESTRATION_COMMIT_INTENT_INVALID', 'commit intent has an invalid schema');
+  }
+  if (
+    value.schemaVersion !== 1
+    || value.taskId !== taskId
+    || !['standalone', 'orchestrated'].includes(String(value.mode))
+    || !['prepared', 'committed', 'pushed'].includes(String(value.phase))
+    || typeof value.tokenDigest !== 'string'
+    || !/^[a-f0-9]{64}$/.test(value.tokenDigest)
+    || typeof value.baselineHead !== 'string'
+    || (value.committedHead !== null && typeof value.committedHead !== 'string')
+    || !validPushEvidence(value.pushEvidence)
+    || !validOrchestration(value.orchestration)
+    || typeof value.createdAt !== 'string'
+    || typeof value.updatedAt !== 'string'
+    || (value.mode === 'standalone') !== (value.orchestration === null)
+  ) {
+    throw new CommitIntentError('ORCHESTRATION_COMMIT_INTENT_INVALID', 'commit intent has invalid field values');
+  }
+  return value as CommitIntent;
+}
+
+function tokenMatches(actualDigest: string, token: string): boolean {
+  const actual = Buffer.from(actualDigest, 'hex');
+  const supplied = Buffer.from(digest(token), 'hex');
+  return actual.length === supplied.length && timingSafeEqual(actual, supplied);
+}
+
+function readCommitIntent(taskDir: string, taskId: string, token?: string): CommitIntent {
+  const file = commitIntentPath(taskDir);
+  const intent = parseIntent(fs.readFileSync(file, 'utf8'), taskId);
+  if (token !== undefined && !tokenMatches(intent.tokenDigest, token)) {
+    throw new CommitIntentError('ORCHESTRATION_COMMIT_INTENT_TOKEN_MISMATCH', 'commit intent token does not match');
+  }
+  return intent;
+}
+
+function createCommitIntent(
+  taskDir: string,
+  input: CommitIntentInput,
+  options: Readonly<{ token?: () => string }> = {}
+): Readonly<{ intent: CommitIntent; token: string }> {
+  const file = commitIntentPath(taskDir);
+  if (fs.existsSync(file)) {
+    throw new CommitIntentError('ORCHESTRATION_COMMIT_INTENT_BUSY', 'an active commit intent already exists');
+  }
+  const token = (options.token ?? (() => randomBytes(32).toString('base64url')))();
+  const intent: CommitIntent = Object.freeze({ schemaVersion: 1, ...input, tokenDigest: digest(token) });
+  atomicWrite(file, intent);
+  return { intent, token };
+}
+
+function updateCommitIntent(
+  taskDir: string,
+  taskId: string,
+  token: string,
+  updates: Partial<Pick<CommitIntent, 'phase' | 'committedHead' | 'pushEvidence' | 'updatedAt'>>
+): CommitIntent {
+  const current = readCommitIntent(taskDir, taskId, token);
+  const nextPhase = updates.phase ?? current.phase;
+  const transitions: Record<CommitIntentPhase, readonly CommitIntentPhase[]> = {
+    prepared: ['prepared', 'committed', 'pushed'],
+    committed: ['committed', 'pushed'],
+    pushed: ['pushed']
+  };
+  if (!transitions[current.phase].includes(nextPhase)) {
+    throw new CommitIntentError('ORCHESTRATION_COMMIT_INTENT_STATE_INVALID', `cannot move commit intent from ${current.phase} to ${nextPhase}`);
+  }
+  const updated = Object.freeze({ ...current, ...updates, phase: nextPhase });
+  atomicWrite(commitIntentPath(taskDir), updated);
+  return updated;
+}
+
+function removeCommitIntent(taskDir: string, taskId: string, token: string): void {
+  readCommitIntent(taskDir, taskId, token);
+  fs.unlinkSync(commitIntentPath(taskDir));
+}
+
+function removeCommitIntentByDigest(taskDir: string, taskId: string, expectedDigest: string): void {
+  const file = commitIntentPath(taskDir);
+  const raw = fs.readFileSync(file);
+  parseIntent(raw.toString('utf8'), taskId);
+  const actual = digest(raw);
+  const expected = Buffer.from(expectedDigest, 'hex');
+  const observed = Buffer.from(actual, 'hex');
+  if (
+    !/^[a-f0-9]{64}$/.test(expectedDigest)
+    || expected.length !== observed.length
+    || !timingSafeEqual(expected, observed)
+  ) {
+    throw new CommitIntentError(
+      'ORCHESTRATION_COMMIT_RECOVERY_REQUIRED',
+      'commit intent changed after recovery inspection'
+    );
+  }
+  fs.unlinkSync(file);
+}
+
+export {
+  CommitIntentError,
+  commitIntentPath,
+  createCommitIntent,
+  digest,
+  readCommitIntent,
+  removeCommitIntent,
+  removeCommitIntentByDigest,
+  serialize,
+  updateCommitIntent
+};
+export type { CommitIntent, CommitIntentInput, CommitIntentOrchestration, CommitIntentPhase, PushEvidence };

package/lib/task/decision-intents.ts

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