taskforce-loop-engineering 0.13.0 → 0.15.0

package/lib/core.mjs

@@ -4,6 +4,8 @@ import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { tmpdir } from 'node:os';
 import { createHash } from 'node:crypto';
+import { listSteps } from './execution-ledger.mjs';
+import { readAndVerifyEvidence } from './production-evidence.mjs';
 
 export const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 
@@ -649,6 +651,7 @@ export async function recentRuns(root, id, options = {}) {
 }
 
 export async function summarizeLoopRuns(root, options = {}) {
+  await reconcileProjectGates(root, options.queue ? { queue: options.queue } : {});
   const ids = await targetRuntimeIds(root, options);
   const summaries = [];
   for (const id of ids) {
@@ -747,6 +750,38 @@ export async function doctorReport(root, options = {}) {
   add('configs-dir', 'warn', await exists(configsDir), path.relative(root, configsDir));
   const runtimeDir = path.join(root, 'runtime', 'loops');
   add('runtime-dir', 'warn', await exists(runtimeDir), path.relative(root, runtimeDir));
+  const gateSpecs = new Map((await projectSpecs(root)).map((spec) => [spec.project, spec]));
+  const gateQueues = [...new Set([...gateSpecs.values()].flatMap((spec) => (spec.queues ?? []).map((item) => item.queue)))];
+  for (const queue of gateQueues) {
+    const gatesDir = path.join(queueDirFor(root, queue), 'human-input', 'gates');
+    for (const file of await listJson(gatesDir)) {
+      const gate = await readJson(path.join(gatesDir, file));
+      if (gate.status !== 'waiting_for_human') continue;
+      const invalid = !gate.project_id || !gate.contract_hash || !Array.isArray(gate.requirement_ids)
+        ? { code: 'missing_structured_project_context' }
+        : gateInvalidity(gate, gateSpecs.get(gate.project_id));
+      add(`human-gate:${gate.gate_id}`, 'fail', !invalid, invalid ?? {
+        project_id: gate.project_id,
+        contract_version: gate.contract_version,
+        milestone_id: gate.milestone_id,
+        requirement_ids: gate.requirement_ids
+      });
+    }
+  }
+  try {
+    const steps = await listSteps(root);
+    const invalid = steps.filter((step) => step.version !== 2 || !step.step_id || !step.input_fingerprint || !['llm', 'tool', 'effect'].includes(step.kind));
+    const reconciliation = steps.filter((step) => step.status === 'unknown' || step.reconciliation?.required);
+    add('execution-ledger', 'fail', invalid.length === 0, { schema_version: 2, steps: steps.length, invalid: invalid.map((step) => step.step_id), reconciliation_required: reconciliation.map((step) => step.step_id) });
+    if (reconciliation.length) add('execution-ledger:reconciliation', 'warn', false, `${reconciliation.length} step(s) require evidence-backed reconciliation`);
+  } catch (error) {
+    add('execution-ledger', 'fail', false, error instanceof Error ? error.message : String(error));
+  }
+  const evidenceFile = path.join(root, '.production-evidence', 'evidence.json');
+  if (await exists(evidenceFile)) {
+    try { const evidence = await readAndVerifyEvidence(evidenceFile); add('production-evidence', 'fail', evidence.verification.valid && evidence.report.passed, { schema_version: evidence.report.schema_version, integrity: evidence.verification.valid, passed: evidence.report.passed, digest: evidence.report.integrity?.digest }); }
+    catch (error) { add('production-evidence', 'fail', false, error instanceof Error ? error.message : String(error)); }
+  } else add('production-evidence', 'warn', false, '.production-evidence/evidence.json not generated');
 
   const loopConfigs = await configFilesFromArgs(root, []);
   add('loop-configs-found', 'warn', loopConfigs.length > 0, `${loopConfigs.length} loop config(s)`);
@@ -1009,6 +1044,7 @@ function parkedDisplayState(parked, now = Date.now()) {
 
 export async function tickParkedTasks(root, options = {}) {
   const queue = normalizeLoopId(options.queue);
+  await reconcileProjectGates(root, { queue });
   const now = options.now ? new Date(options.now) : new Date();
   if (!Number.isFinite(now.getTime())) throw new Error(`Invalid tick time: ${options.now}`);
   if (!options.notifyCommand && !options.dryRun) throw new Error('queue-wait-tick requires --notify-command unless --dry-run is used.');
@@ -1117,6 +1153,138 @@ function projectConfigPathFor(root, project) {
   return path.join(root, 'configs', 'loops', 'projects', `${normalizeProjectId(project)}.json`);
 }
 
+function projectContractVersion(spec) {
+  return spec.contractVersion ?? spec.contract_version ?? spec.schemaVersion ?? null;
+}
+
+function projectContractHash(spec) {
+  return createHash('sha256').update(JSON.stringify(spec)).digest('hex');
+}
+
+async function projectSpecs(root) {
+  const dir = path.join(root, 'configs', 'loops', 'projects');
+  const specs = [];
+  for (const file of await listJson(dir)) {
+    try {
+      const spec = await readJson(path.join(dir, file));
+      if (spec?.project) specs.push(spec);
+    } catch { /* doctor reports malformed project files through its normal config checks */ }
+  }
+  return specs;
+}
+
+async function projectTerminalAccepted(root, spec) {
+  const configuredAcceptanceLedger = spec?.acceptanceLedger ?? spec?.ledger;
+  if (!configuredAcceptanceLedger) return false;
+  try {
+    const ledgerFile = path.resolve(root, safeRelativePath(configuredAcceptanceLedger, 'project acceptance ledger'));
+    const ledger = await readJson(ledgerFile);
+    return ledger.status === 'accepted'
+      && Array.isArray(ledger.unmet) && ledger.unmet.length === 0
+      && Array.isArray(ledger.blockers) && ledger.blockers.length === 0;
+  } catch {
+    return false;
+  }
+}
+
+function requirementIdsFromCheckpoint(checkpoint, specs) {
+  const explicit = checkpoint?.requirement_ids ?? checkpoint?.requirementIds;
+  if (Array.isArray(explicit)) return [...new Set(explicit.map(String))];
+  const text = JSON.stringify({
+    milestone_id: checkpoint?.milestone_id,
+    blockers: checkpoint?.blockers,
+    next_action: checkpoint?.next_action
+  });
+  const known = new Set(specs.flatMap((spec) => (spec.backlog ?? []).map((item) => String(item.id))));
+  return [...known].filter((id) => new RegExp(`(^|[^A-Za-z0-9_-])${id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}([^A-Za-z0-9_-]|$)`).test(text));
+}
+
+function inferProjectSpec(task, checkpoint, specs, requirementIds = []) {
+  const explicit = checkpoint?.project_id ?? checkpoint?.projectId ?? task?.project_id ?? task?.projectId;
+  if (explicit) return specs.find((spec) => spec.project === explicit) ?? null;
+  const text = `${task?.title ?? ''}\n${task?.body ?? ''}`.toLowerCase();
+  const candidates = specs.map((spec) => ({
+    spec,
+    requirementMatches: requirementIds.filter((id) => (spec.backlog ?? []).some((item) => item.id === id)).length,
+    nameMatch: text.includes(String(spec.project).toLowerCase()) ? 1 : 0
+  })).filter((item) => item.requirementMatches > 0 || item.nameMatch > 0)
+    .sort((a, b) => b.requirementMatches - a.requirementMatches || b.nameMatch - a.nameMatch || b.spec.project.length - a.spec.project.length);
+  return candidates[0]?.spec ?? null;
+}
+
+async function gateProjectMetadata(root, task, checkpoint) {
+  const specs = await projectSpecs(root);
+  const requirementIds = requirementIdsFromCheckpoint(checkpoint, specs);
+  const spec = inferProjectSpec(task, checkpoint, specs, requirementIds);
+  return {
+    project_id: spec?.project ?? null,
+    contract_version: spec ? projectContractVersion(spec) : null,
+    contract_hash: spec ? projectContractHash(spec) : null,
+    milestone_id: checkpoint?.milestone_id ?? checkpoint?.checkpoint_id ?? null,
+    requirement_ids: requirementIds
+  };
+}
+
+function gateInvalidity(gate, spec) {
+  if (!spec) return { code: 'project_not_found', status: 'superseded' };
+  const backlog = new Map((spec.backlog ?? []).map((item) => [String(item.id), item]));
+  for (const id of gate.requirement_ids ?? []) {
+    const requirement = backlog.get(String(id));
+    if (!requirement) return { code: 'requirement_not_found', requirement_id: id, status: 'superseded' };
+    if (requirement.required === false || ['out_of_scope', 'canceled_by_owner'].includes(requirement.status) || requirement.disposition === 'canceled_by_owner') {
+      return {
+        code: requirement.disposition === 'canceled_by_owner' ? 'canceled_by_owner' : 'requirement_not_required',
+        requirement_id: id,
+        status: requirement.disposition === 'canceled_by_owner' ? 'canceled' : 'superseded'
+      };
+    }
+  }
+  if (gate.contract_version !== projectContractVersion(spec)) {
+    return { code: 'stale_contract', status: 'superseded' };
+  }
+  return null;
+}
+
+export async function reconcileProjectGates(root, options = {}) {
+  const queues = options.queue
+    ? [normalizeLoopId(options.queue)]
+    : [...new Set((await projectSpecs(root)).flatMap((spec) => (spec.queues ?? []).map((item) => item.queue)))];
+  const specs = new Map((await projectSpecs(root)).map((spec) => [spec.project, spec]));
+  const results = [];
+  for (const queue of queues) {
+    await ensureQueueDirs(root, queue);
+    const gatesDir = path.join(queueDirFor(root, queue), 'human-input', 'gates');
+    for (const file of await listJson(gatesDir)) {
+      const full = path.join(gatesDir, file);
+      let gate = await readJson(full);
+      if (gate.status !== 'waiting_for_human') continue;
+      const found = await findTaskFile(root, queue, gate.task_id);
+      const task = found ? await readJson(found.file) : null;
+      const checkpointFile = path.join(taskRuntimeDirFor(root, queue, gate.task_id), 'checkpoints', `${gate.checkpoint_id}.json`);
+      const checkpoint = await exists(checkpointFile) ? await readJson(checkpointFile) : null;
+      if (!gate.project_id || !Array.isArray(gate.requirement_ids) || !gate.contract_hash) {
+        gate = { ...gate, ...await gateProjectMetadata(root, task, checkpoint) };
+        await writeJson(full, gate);
+      }
+      const spec = specs.get(gate.project_id);
+      const invalid = gate.gate_kind === 'deferred_authorization' && await projectTerminalAccepted(root, spec)
+        ? { code: 'project_accepted_optional_deferred', status: 'superseded' }
+        : gateInvalidity(gate, spec);
+      if (!invalid) continue;
+      const now = new Date().toISOString();
+      const reconciled = { ...gate, status: invalid.status, reconciliation: { ...invalid, reconciled_at: now } };
+      await writeJson(full, reconciled);
+      if (found?.subdir === 'waiting' && task?.waitingGateId === gate.gate_id) {
+        const canceledFile = path.join(queueSubdirFor(root, queue, 'canceled'), path.basename(found.file));
+        await writeJson(canceledFile, { ...task, status: invalid.status, canceledAt: now, gateReconciliation: reconciled.reconciliation });
+        await rm(found.file, { force: true });
+      }
+      results.push({ queue, gateId: gate.gate_id, projectId: gate.project_id, outcome: invalid.status, reason: invalid.code });
+    }
+  }
+  return { inspectedQueues: queues.length, reconciled: results.length, results };
+}
+
 function projectLatestIntakePath(root, project) {
   return path.join(projectRuntimeDirFor(root, project), 'intake', 'latest.json');
 }
@@ -1578,13 +1746,19 @@ export async function projectStatus(root, options = {}) {
   } catch {
     latestIntake = null;
   }
-  const backlogFile = projectInitialBacklogPath(root, project);
+  const configuredBacklogSource = spec.backlogSource ?? spec.authoritativeBacklog;
+  const configuredAcceptanceLedger = spec.acceptanceLedger ?? spec.ledger;
+  const backlogFile = configuredBacklogSource
+    ? path.resolve(root, safeRelativePath(configuredBacklogSource, 'project backlog source'))
+    : projectInitialBacklogPath(root, project);
   let backlog = null;
   try {
     const loaded = await readJson(backlogFile);
     backlog = {
       file: path.relative(root, backlogFile),
-      count: Array.isArray(loaded.tasks) ? loaded.tasks.length : 0
+      count: Array.isArray(loaded.tasks) ? loaded.tasks.length : Array.isArray(loaded.items) ? loaded.items.length : 0,
+      status: loaded.status ?? null,
+      updatedAt: loaded.updatedAt ?? loaded.generatedAt ?? null
     };
   } catch {
     backlog = null;
@@ -1596,11 +1770,45 @@ export async function projectStatus(root, options = {}) {
     if (queue.status.locked) acc.locked += 1;
     return acc;
   }, { queued: 0, active: 0, waiting: 0, done: 0, failed: 0, canceled: 0, runs: 0, locked: 0 });
+  let acceptanceLedger = null;
+  if (configuredAcceptanceLedger) {
+    const ledgerFile = path.resolve(root, safeRelativePath(configuredAcceptanceLedger, 'project acceptance ledger'));
+    try {
+      const ledger = await readJson(ledgerFile);
+      acceptanceLedger = {
+        file: path.relative(root, ledgerFile),
+        status: ledger.status ?? null,
+        updatedAt: ledger.updatedAt ?? null,
+        unmet: Array.isArray(ledger.unmet) ? ledger.unmet : [],
+        blockers: Array.isArray(ledger.blockers) ? ledger.blockers : []
+      };
+    } catch (error) {
+      acceptanceLedger = { file: path.relative(root, ledgerFile), readable: false, error: error.message };
+    }
+  }
+  const registryItems = Array.isArray(spec.backlog) ? spec.backlog : [];
+  const sourceItems = backlog ? await readJson(backlogFile).then((loaded) => loaded.items ?? loaded.tasks ?? []) : [];
+  const registryById = new Map(registryItems.map((item) => [item.id, item]));
+  const sourceById = new Map(sourceItems.map((item) => [item.id, item]));
+  const drift = [];
+  for (const id of new Set([...registryById.keys(), ...sourceById.keys()])) {
+    const registry = registryById.get(id);
+    const authoritative = sourceById.get(id);
+    if (!registry || !authoritative) drift.push({ id, kind: registry ? 'missing_from_authoritative_backlog' : 'missing_from_registry' });
+    else if (registry.status !== authoritative.status || Boolean(registry.required) !== Boolean(authoritative.required)) {
+      drift.push({ id, kind: 'status_or_scope_mismatch', registry: { status: registry.status, required: registry.required }, authoritative: { status: authoritative.status, required: authoritative.required } });
+    }
+  }
+  const projectCompletion = acceptanceLedger?.status === 'accepted' && acceptanceLedger.unmet.length === 0 && acceptanceLedger.blockers.length === 0
+    ? 'accepted'
+    : 'in_progress';
   const needsAttention = [];
   if (totals.failed > 0) needsAttention.push('failed_tasks_present');
   if (totals.waiting > 0) needsAttention.push('human_input_waiting');
   if (totals.active > 0) needsAttention.push('active_tasks_present');
   if (queues.some((queue) => queue.status.locked)) needsAttention.push('queue_locked');
+  if (drift.length > 0) needsAttention.push('authoritative_source_drift');
+  if (acceptanceLedger?.readable === false) needsAttention.push('acceptance_ledger_unreadable');
   return {
     version: 1,
     project,
@@ -1611,11 +1819,22 @@ export async function projectStatus(root, options = {}) {
     queues,
     totals,
     backlog,
+    acceptanceLedger,
+    authority: {
+      terminalContract: spec.terminalContract ?? null,
+      backlog: backlog?.file ?? null,
+      acceptanceLedger: acceptanceLedger?.file ?? null,
+      rule: 'acceptance ledger determines project completion; backlog source determines remaining work; registry is a projection validated for drift'
+    },
+    consistency: { ok: drift.length === 0 && acceptanceLedger?.readable !== false, drift },
+    projectCompletion,
     latestIntake,
     needsAttention,
     nextActions: needsAttention.length
       ? ['Inspect queue-status or code-task-status for the queue needing attention.']
-      : ['Enqueue or run the next planned backlog task when ready.']
+      : projectCompletion === 'accepted'
+        ? ['Project terminal contract is accepted.']
+        : ['Enqueue or run the next safe authorized item from the authoritative backlog.']
   };
 }
 
@@ -1643,6 +1862,7 @@ export async function enqueueTask(root, options) {
     status: 'queued',
     enqueuedAt: new Date().toISOString(),
     ...(options.riskAssessment ? { riskAssessment: options.riskAssessment } : {}),
+    ...(options.projectId ? { projectId: normalizeProjectId(options.projectId) } : {}),
     ...(options.supersedesTaskId ? { supersedesTaskId: options.supersedesTaskId } : {}),
     ...(options.supersedeReason ? { supersedeReason: options.supersedeReason } : {}),
     ...(taskSourceFromOptions(options) ? { source: taskSourceFromOptions(options) } : {})
@@ -1741,6 +1961,7 @@ async function appendActiveTaskAmendment(root, queue, activeTask, options = {})
 }
 
 export async function routeLoopMessage(root, options = {}) {
+  if (options.queue) await reconcileProjectGates(root, { queue: options.queue });
   const classification = classifyLoopMessage(options.message);
   if (!options.route) return classification;
   if (classification.intent === 'status') {
@@ -1769,10 +1990,20 @@ export async function routeLoopMessage(root, options = {}) {
   if (options.supersedeActive && options.amendActive) {
     throw new Error('--supersede-active and --amend-active are mutually exclusive.');
   }
-  const activeFiles = (options.supersedeActive || options.amendActive) ? await listJson(queueSubdirFor(root, queue, 'active')) : [];
-  const activeTask = activeFiles.length > 0
-    ? await readJson(path.join(queueSubdirFor(root, queue, 'active'), activeFiles[0]))
-    : null;
+  const specs = await projectSpecs(root);
+  const routedProject = inferProjectSpec({ title: options.title, body: options.message }, null, specs)?.project ?? null;
+  const activeEntries = [];
+  if (options.supersedeActive || options.amendActive) {
+    for (const subdir of options.supersedeActive ? ['active', 'waiting'] : ['active']) {
+      for (const file of await listJson(queueSubdirFor(root, queue, subdir))) {
+        const task = await readJson(path.join(queueSubdirFor(root, queue, subdir), file));
+        const metadata = await gateProjectMetadata(root, task, null);
+        if (routedProject && metadata.project_id !== routedProject) continue;
+        activeEntries.push({ task, subdir, file });
+      }
+    }
+  }
+  const activeTask = activeEntries[0]?.task ?? null;
   if (options.amendActive) {
     if (!activeTask) throw new Error('No active loop task exists to amend.');
     const amended = await appendActiveTaskAmendment(root, queue, activeTask, options);
@@ -1788,14 +2019,33 @@ export async function routeLoopMessage(root, options = {}) {
     };
   }
   if (activeTask) {
+    const now = new Date().toISOString();
+    for (const entry of activeEntries) {
+      const requestFile = path.join(taskRuntimeDirFor(root, queue, entry.task.id), 'supersede_request.json');
+      await writeJson(requestFile, {
+        version: 1,
+        requestedAt: now,
+        activeTaskId: entry.task.id,
+        projectId: routedProject,
+        reason: String(options.message).trim(),
+        status: 'requested'
+      });
+      if (entry.subdir === 'waiting') {
+        const sourceFile = path.join(queueSubdirFor(root, queue, 'waiting'), entry.file);
+        const canceledFile = path.join(queueSubdirFor(root, queue, 'canceled'), entry.file);
+        await writeJson(canceledFile, { ...entry.task, status: 'superseded', canceledAt: now, supersededByNewerRequest: true });
+        await rm(sourceFile, { force: true });
+        const separator = entry.task.waitingGateId?.lastIndexOf(':') ?? -1;
+        if (separator > 0) {
+          const gateFile = path.join(queueDirFor(root, queue), 'human-input', 'gates', `${safeTaskId(entry.task.id)}.${normalizeLoopId(entry.task.waitingGateId.slice(separator + 1))}.json`);
+          if (await exists(gateFile)) {
+            const gate = await readJson(gateFile);
+            await writeJson(gateFile, { ...gate, status: 'superseded', reconciliation: { code: 'superseded_by_owner', reconciled_at: now } });
+          }
+        }
+      }
+    }
     const requestFile = path.join(taskRuntimeDirFor(root, queue, activeTask.id), 'supersede_request.json');
-    await writeJson(requestFile, {
-      version: 1,
-      requestedAt: new Date().toISOString(),
-      activeTaskId: activeTask.id,
-      reason: String(options.message).trim(),
-      status: 'requested'
-    });
     for (const file of await listJson(queueSubdirFor(root, queue, 'inbox'))) {
       const full = path.join(queueSubdirFor(root, queue, 'inbox'), file);
       const queued = await readJson(full);
@@ -1822,7 +2072,8 @@ export async function routeLoopMessage(root, options = {}) {
     task,
     riskAssessment: 'model_assessed',
     supersedesTaskId: activeTask?.id,
-    supersedeReason: activeTask ? String(options.message).trim() : null
+    supersedeReason: activeTask ? String(options.message).trim() : null,
+    projectId: routedProject
   });
   if (activeTask) {
     const requestFile = path.join(taskRuntimeDirFor(root, queue, activeTask.id), 'supersede_request.json');
@@ -1889,6 +2140,16 @@ export async function notifyTerminalTasks(root, options = {}) {
     throw new Error('queue-terminal-notify requires --notify-command unless --dry-run is used.');
   }
   await ensureQueueDirs(root, queue);
+  await reconcileProjectGates(root, { queue });
+  const queueConfigFile = path.join(root, 'configs', 'loops', 'queues', `${queue}.json`);
+  let terminalNotificationArchive = { tasks: {} };
+  if (await exists(queueConfigFile)) {
+    const queueConfig = await readJson(queueConfigFile);
+    if (queueConfig.terminalNotificationArchive) {
+      const archiveFile = path.resolve(root, queueConfig.terminalNotificationArchive);
+      if (await exists(archiveFile)) terminalNotificationArchive = await readJson(archiveFile);
+    }
+  }
   const notificationDir = path.join(queueDirFor(root, queue), 'notifications');
   await mkdir(notificationDir, { recursive: true });
   const results = [];
@@ -1897,6 +2158,17 @@ export async function notifyTerminalTasks(root, options = {}) {
     for (const file of await listJson(dir)) {
       const task = await readJson(path.join(dir, file));
       if (!task?.id || !task?.status) continue;
+      const archived = terminalNotificationArchive?.tasks?.[task.id];
+      if (archived) {
+        results.push({
+          taskId: task.id,
+          status: task.status,
+          outcome: 'archived_unroutable',
+          reason: archived.reason,
+          archive: path.relative(root, path.resolve(root, terminalNotificationArchive.archiveFile ?? queueConfigFile))
+        });
+        continue;
+      }
       if (!task?.source?.channel || !task?.source?.target) {
         results.push({
           taskId: task.id,
@@ -2008,8 +2280,10 @@ export async function refreshTaskAcceptance(root, options = {}) {
 
 function humanInputMessage(queue, task, checkpoint, gateId, language = 'en') {
   const blockers = Array.isArray(checkpoint.blockers) ? checkpoint.blockers : [];
-  const blockerText = blockers.length
-    ? blockers.map((item) => typeof item === 'string' ? item : item?.human_action_required ?? item?.user_action ?? item?.description ?? item?.message ?? JSON.stringify(item))
+  const deferredGates = Array.isArray(checkpoint.deferred_gates) ? checkpoint.deferred_gates : [];
+  const requirements = blockers.length > 0 ? blockers : deferredGates;
+  const blockerText = requirements.length
+    ? requirements.map((item) => typeof item === 'string' ? item : item?.required_authority ?? item?.human_action_required ?? item?.user_action ?? item?.reason ?? item?.description ?? item?.message ?? JSON.stringify(item))
     : [checkpoint.next_action ?? 'Human input is required before the task can continue.'];
   if (language === 'zh') return [
     'Loop 任务正在等待你的输入',
@@ -2040,8 +2314,70 @@ async function tasksById(root, queue) {
   return tasks;
 }
 
+function taskRecency(task) {
+  // Queue-carrier authority follows creation/enqueue order. Later bookkeeping
+  // updates on an old task must never make it newer than its successor.
+  const value = task?.enqueuedAt ?? task?.createdAt ?? task?.updatedAt ?? task?.completedAt ?? '';
+  const parsed = Date.parse(value);
+  return Number.isFinite(parsed) ? parsed : 0;
+}
+
+async function authoritativeHumanGateCandidates(root, queue, tasks) {
+  const specs = await projectSpecs(root);
+  const candidates = [];
+  for (const [taskId, entry] of tasks) {
+    if (!entry.task.source || entry.subdir === 'canceled') continue;
+    const runtimeDir = taskRuntimeDirFor(root, queue, taskId);
+    let files = await listJson(path.join(runtimeDir, 'checkpoints'));
+    const judgementFile = path.join(runtimeDir, 'final_judgement.json');
+    if (await exists(judgementFile)) {
+      const judgement = await readJson(judgementFile);
+      const effectiveIds = new Set(Array.isArray(judgement?.coverage?.effective_review_ids)
+        ? judgement.coverage.effective_review_ids
+        : []);
+      if (effectiveIds.size > 0) files = files.filter((file) => effectiveIds.has(path.basename(file, '.json')));
+    }
+    const checkpoints = [];
+    for (const file of files) {
+      const checkpointFile = path.join(runtimeDir, 'checkpoints', file);
+      const checkpoint = await readJson(checkpointFile);
+      const deferred = Array.isArray(checkpoint?.deferred_gates) ? checkpoint.deferred_gates : [];
+      if (['needs_human_input', 'blocked'].includes(checkpoint?.status) || deferred.length > 0) {
+        checkpoints.push({ file, checkpoint, mtimeMs: (await stat(checkpointFile)).mtimeMs });
+      }
+    }
+    if (checkpoints.length === 0) continue;
+    checkpoints.sort((a, b) => Number(b.checkpoint.sequence ?? 0) - Number(a.checkpoint.sequence ?? 0)
+      || b.mtimeMs - a.mtimeMs
+      || String(b.checkpoint.checkpoint_id ?? b.file).localeCompare(String(a.checkpoint.checkpoint_id ?? a.file)));
+    const metadata = await gateProjectMetadata(root, entry.task, checkpoints[0].checkpoint);
+    const latestCheckpoint = checkpoints[0].checkpoint;
+    const deferredOnly = Array.isArray(latestCheckpoint.deferred_gates)
+      && latestCheckpoint.deferred_gates.length > 0
+      && (!Array.isArray(latestCheckpoint.blockers) || latestCheckpoint.blockers.length === 0)
+      && !['needs_human_input', 'blocked'].includes(latestCheckpoint.status);
+    const spec = specs.find((item) => item.project === metadata.project_id);
+    if (deferredOnly && await projectTerminalAccepted(root, spec)) continue;
+    candidates.push({ taskId, entry, projectId: metadata.project_id, ...checkpoints[0] });
+  }
+
+  // A project deferred gate is materialized only from its newest authoritative
+  // carrier. Historical terminal tasks are audit evidence, not a replay queue.
+  const newestByProject = new Map();
+  for (const candidate of candidates.filter((item) => item.projectId)) {
+    const current = newestByProject.get(candidate.projectId);
+    if (!current || taskRecency(candidate.entry.task) > taskRecency(current.entry.task)) newestByProject.set(candidate.projectId, candidate);
+  }
+  return candidates.filter((candidate) => {
+    if (candidate.projectId) return newestByProject.get(candidate.projectId) === candidate && candidate.entry.subdir !== 'failed';
+    return ['inbox', 'active', 'waiting'].includes(candidate.entry.subdir)
+      || (candidate.entry.subdir === 'failed' && ['needs_human_input', 'blocked'].includes(candidate.checkpoint.status));
+  });
+}
+
 export async function notifyHumanInputRequests(root, options = {}) {
   const queue = normalizeLoopId(options.queue);
+  await reconcileProjectGates(root, { queue });
   const language = await installedQueueLanguage(root, queue, options.language);
   if (!options.notifyCommand && !options.dryRun) {
     throw new Error('queue-human-input-notify requires --notify-command unless --dry-run is used.');
@@ -2051,29 +2387,15 @@ export async function notifyHumanInputRequests(root, options = {}) {
   const gatesDir = path.join(queueDirFor(root, queue), 'human-input', 'gates');
   await mkdir(gatesDir, { recursive: true });
   const results = [];
-  for (const [taskId, entry] of tasks) {
-    if (!entry.task.source) continue;
-    const checkpointsDir = path.join(taskRuntimeDirFor(root, queue, taskId), 'checkpoints');
-    let checkpointFiles = await listJson(checkpointsDir);
-    const judgementFile = path.join(taskRuntimeDirFor(root, queue, taskId), 'final_judgement.json');
-    if (await exists(judgementFile)) {
-      const judgement = await readJson(judgementFile);
-      const effectiveIds = Array.isArray(judgement?.coverage?.effective_review_ids)
-        ? new Set(judgement.coverage.effective_review_ids)
-        : null;
-      if (effectiveIds?.size > 0) {
-        checkpointFiles = checkpointFiles.filter((file) => effectiveIds.has(path.basename(file, '.json')));
-      }
-    }
-    for (const file of checkpointFiles) {
-      const checkpoint = await readJson(path.join(checkpointsDir, file));
-      if (!['needs_human_input', 'blocked'].includes(checkpoint?.status)) continue;
+  const candidates = await authoritativeHumanGateCandidates(root, queue, tasks);
+  for (const { taskId, entry, file, checkpoint } of candidates) {
+      const deferredGates = Array.isArray(checkpoint?.deferred_gates) ? checkpoint.deferred_gates : [];
       const checkpointId = checkpoint.checkpoint_id ?? path.basename(file, '.json');
       const gateId = `${taskId}:${checkpointId}`;
       const ledgerFile = path.join(gatesDir, `${safeTaskId(taskId)}.${normalizeLoopId(checkpointId)}.json`);
       if (await exists(ledgerFile)) {
         const gate = await readJson(ledgerFile);
-        if (gate.status === 'waiting_for_human' && ['inbox', 'failed'].includes(entry.subdir)) {
+        if (gate.status === 'waiting_for_human' && ['inbox', 'done', 'failed'].includes(entry.subdir)) {
           const sourceFile = path.join(queueSubdirFor(root, queue, entry.subdir), `${safeTaskId(taskId)}.json`);
           if (await exists(sourceFile)) {
             const waitingFile = path.join(queueSubdirFor(root, queue, 'waiting'), path.basename(sourceFile));
@@ -2081,13 +2403,46 @@ export async function notifyHumanInputRequests(root, options = {}) {
               ...entry.task,
               status: 'waiting_for_human',
               waitingGateId: gateId,
+              waitKind: gate.gate_kind ?? 'human_input',
               waitingSince: gate.requested_at ?? new Date().toISOString()
             });
             await rm(sourceFile, { force: true });
           }
         }
-        results.push({ taskId, checkpointId, gateId, outcome: gate.status === 'resolved' ? 'resolved' : 'already_notified', ledger: path.relative(root, ledgerFile) });
-        continue;
+        const notified = gate.notification_record?.status === 'sent' || gate.notification?.exitCode === 0;
+        if (gate.status !== 'waiting_for_human' || notified || options.dryRun) {
+          results.push({ taskId, checkpointId, gateId, outcome: gate.status === 'resolved' ? 'resolved' : 'already_notified', ledger: path.relative(root, ledgerFile) });
+          continue;
+        }
+        // A prior notification failure is safely retryable because the durable
+        // gate/task transition already exists and notification_record is the cursor.
+      } else if (!options.dryRun) {
+        const now = new Date().toISOString();
+        await writeJson(ledgerFile, {
+          version: 1, gate_id: gateId, queue, task_id: taskId, checkpoint_id: checkpointId,
+          ...await gateProjectMetadata(root, entry.task, checkpoint), status: 'waiting_for_human',
+          gate_kind: deferredGates.length > 0 ? 'deferred_authorization' : 'human_input',
+          authorization_requirements: deferredGates.map((gate, index) => ({
+            id: gate?.id ?? `deferred-${index + 1}`, action: gate?.action ?? gate?.kind ?? null,
+            required_authority: gate?.required_authority ?? gate?.human_action_required ?? gate?.reason ?? gate?.description ?? String(gate),
+            scope: gate?.scope ?? null
+          })), source: entry.task.source, requested_at: now,
+          notification_record: { status: 'pending', attempts: 0, idempotency_key: gateId }
+        });
+        if (['inbox', 'done', 'failed'].includes(entry.subdir)) {
+          const sourceFile = path.join(queueSubdirFor(root, queue, entry.subdir), `${safeTaskId(taskId)}.json`);
+          if (await exists(sourceFile)) {
+            const waitingFile = path.join(queueSubdirFor(root, queue, 'waiting'), path.basename(sourceFile));
+            await writeJson(waitingFile, {
+              ...entry.task,
+              status: 'waiting_for_human',
+              waitingGateId: gateId,
+              waitKind: deferredGates.length > 0 ? 'deferred_authorization' : 'human_input',
+              waitingSince: now
+            });
+            await rm(sourceFile, { force: true });
+          }
+        }
       }
       const message = humanInputMessage(queue, entry.task, checkpoint, gateId, language);
       if (options.dryRun) {
@@ -2108,36 +2463,20 @@ export async function notifyHumanInputRequests(root, options = {}) {
         }
       });
       if (result.exitCode !== 0) {
+        const gate = await readJson(ledgerFile);
+        await writeJson(ledgerFile, { ...gate, request: message, notification_record: {
+          status: 'failed', attempts: Number(gate.notification_record?.attempts ?? 0) + 1,
+          idempotency_key: gateId, last_attempt_at: new Date().toISOString(), result: compactCommandResult(result)
+        } });
         results.push({ taskId, checkpointId, gateId, outcome: 'failed', result: compactCommandResult(result) });
         continue;
       }
-      await writeJson(ledgerFile, {
-        version: 1,
-        gate_id: gateId,
-        queue,
-        task_id: taskId,
-        checkpoint_id: checkpointId,
-        status: 'waiting_for_human',
-        source: entry.task.source,
-        request: message,
-        requested_at: new Date().toISOString(),
-        notification: compactCommandResult(result)
-      });
-      if (['inbox', 'failed'].includes(entry.subdir)) {
-        const sourceFile = path.join(queueSubdirFor(root, queue, entry.subdir), `${safeTaskId(taskId)}.json`);
-        if (await exists(sourceFile)) {
-          const waitingFile = path.join(queueSubdirFor(root, queue, 'waiting'), path.basename(sourceFile));
-          await writeJson(waitingFile, {
-            ...entry.task,
-            status: 'waiting_for_human',
-            waitingGateId: gateId,
-            waitingSince: new Date().toISOString()
-          });
-          await rm(sourceFile, { force: true });
-        }
-      }
+      const gate = await readJson(ledgerFile);
+      await writeJson(ledgerFile, { ...gate, request: message, notification: compactCommandResult(result), notification_record: {
+        status: 'sent', attempts: Number(gate.notification_record?.attempts ?? 0) + 1,
+        idempotency_key: gateId, sent_at: new Date().toISOString()
+      } });
       results.push({ taskId, checkpointId, gateId, outcome: 'sent', ledger: path.relative(root, ledgerFile) });
-    }
   }
   return {
     queue,
@@ -2450,14 +2789,25 @@ function defaultBlockedActions(riskLevel) {
   return blocked;
 }
 
+export function inferTaskScope(task) {
+  const requestText = `${task?.title ?? ''}\n${task?.body ?? ''}`.toLowerCase();
+  // A project can be referenced as context while the routed task is explicitly
+  // bounded to one milestone or backlog item. Those bounded instructions must
+  // win; otherwise phrases such as "do not call the overall project complete"
+  // incorrectly turn an accepted milestone into an endlessly requeued project
+  // task.
+  const boundedMilestone = /(?:only|仅|只)(?:推进|处理|执行|完成|验证)|阶段完成|任务完成|第\s*\d+\s*(?:项|步)|选项\s*\d+|boundary item|backlog item|(?:取消|撤销|移除).{0,40}(?:功能|范围|计划|必做|门槛)|(?:cancel|remove|drop|withdraw).{0,40}(?:feature|scope|requirement|backlog item|completion gate)|(?:product[-_ ]scope|产品范围).{0,20}(?:decision|amendment|决策|修订)/.test(requestText);
+  if (boundedMilestone) return 'scoped_task';
+  return /project[-_ ]level|项目级|完整项目|整体项目|single milestone|单(?:一)?里程碑/.test(requestText)
+    ? 'project'
+    : 'scoped_task';
+}
+
 function buildTaskContract(queue, task, options = {}) {
   const inferredRisk = inferTaskRisk(task);
   const modelAssessed = task.riskAssessment === 'model_assessed';
   const riskLevel = options.riskLevel ?? (modelAssessed ? 'model_assessed' : inferredRisk.level);
-  const requestText = `${task.title ?? ''}\n${task.body ?? ''}`.toLowerCase();
-  const taskScope = /project[-_ ]level|项目级|完整项目|整体项目|single milestone|单(?:一)?里程碑/.test(requestText)
-    ? 'project'
-    : 'scoped_task';
+  const taskScope = inferTaskScope(task);
   return {
     version: 1,
     task_id: task.id,
@@ -2568,11 +2918,12 @@ export async function writeTaskContract(root, queue, task, options = {}) {
   const dir = taskRuntimeDirFor(root, queue, task.id);
   const file = path.join(dir, 'task_contract.json');
   const historicalPatterns = await retrieveHistoricalPatterns(root, queue, task, options.history ?? {});
-  const contract = buildTaskContract(queue, task, {
+  let contract = buildTaskContract(queue, task, {
     ...options,
     workspace: options.workspace ?? root,
     historicalPatterns
   });
+  contract = await mergeLiveAmendments(root, queue, task.id, contract, 'supplemental_requirements');
   await writeJson(file, contract);
   return {
     contract,
@@ -2580,6 +2931,36 @@ export async function writeTaskContract(root, queue, task, options = {}) {
   };
 }
 
+async function mergeLiveAmendments(root, queue, taskId, artifact, supplementalField) {
+  const amendmentsDir = path.join(taskRuntimeDirFor(root, queue, taskId), 'amendments');
+  if (!(await exists(amendmentsDir))) return artifact;
+  const files = (await listJson(amendmentsDir)).filter((file) => /^\d{4}\.json$/.test(file)).sort();
+  if (files.length === 0) return artifact;
+  const refs = [];
+  const instructions = [];
+  for (const name of files) {
+    const amendment = await readJson(path.join(amendmentsDir, name));
+    const instruction = String(amendment.instruction ?? amendment.requirement ?? '').trim();
+    if (!instruction) continue;
+    const sequence = Number(amendment.sequence ?? refs.length + 1);
+    refs.push({
+      sequence,
+      instruction,
+      requested_at: amendment.requestedAt ?? amendment.created_at ?? null,
+      artifact: path.relative(root, path.join(amendmentsDir, name))
+    });
+    instructions.push(instruction);
+  }
+  if (refs.length === 0) return artifact;
+  return {
+    ...artifact,
+    amendment_version: Math.max(...refs.map((item) => item.sequence)),
+    amendments: refs,
+    [supplementalField]: instructions,
+    updated_at: new Date().toISOString()
+  };
+}
+
 function inferAcceptanceSignals(contract) {
   const text = `${contract.title ?? ''}\n${contract.original_request ?? ''}`.toLowerCase();
   return {
@@ -2760,7 +3141,8 @@ function buildAcceptancePlan(contract, options = {}) {
 export async function writeAcceptancePlan(root, queue, task, taskContract, options = {}) {
   const dir = taskRuntimeDirFor(root, queue, task.id);
   const file = path.join(dir, 'acceptance_plan.json');
-  const plan = buildAcceptancePlan(taskContract.contract, options);
+  let plan = buildAcceptancePlan(taskContract.contract, options);
+  plan = await mergeLiveAmendments(root, queue, task.id, plan, 'supplemental_checks');
   await writeJson(file, plan);
   return {
     plan,
@@ -2827,7 +3209,8 @@ export async function writeDevPlan(root, queue, task, taskContract, acceptancePl
   await mkdir(checkpointsDir, { recursive: true });
   await mkdir(reviewsDir, { recursive: true });
   const file = path.join(dir, 'dev_plan.json');
-  const plan = buildDevPlan(taskContract.contract, acceptancePlan.plan);
+  let plan = buildDevPlan(taskContract.contract, acceptancePlan.plan);
+  plan = await mergeLiveAmendments(root, queue, task.id, plan, 'supplemental_instructions');
   await writeJson(file, plan);
   return {
     plan,
@@ -3107,6 +3490,7 @@ export async function writeAcceptanceReviews(root, queue, task, taskContract, ac
       checkpointCreatedAt: checkpoint.created_at ?? null,
       createdAt: checkpoint.created_at ?? review.created_at,
       projectCompletion: checkpoint.project_completion ?? null,
+      deferredGates: Array.isArray(checkpoint.deferred_gates) ? checkpoint.deferred_gates : [],
       status: review.status,
       file: path.relative(root, reviewFile)
     });
@@ -3179,6 +3563,8 @@ export function buildFinalJudgement(contract, acceptancePlan, devPlan, checkpoin
   const dispatchStatus = context.dispatchStatus ?? 'unknown';
   const dispatchFailure = context.dispatchFailureClassification ?? null;
   const projectCompletionAccepted = effectiveReviews.some((review) => review.projectCompletion?.status === 'accepted');
+  const projectCompletionInProgress = effectiveReviews.some((review) => review.projectCompletion?.status === 'in_progress');
+  const deferredGateCount = effectiveReviews.reduce((count, review) => count + (review.deferredGates?.length ?? 0), 0);
   let outcome = 'needs_revision';
 
   if (dispatchStatus === 'runtime_interrupted') {
@@ -3229,10 +3615,11 @@ export function buildFinalJudgement(contract, acceptancePlan, devPlan, checkpoin
     outcome = 'needs_revision';
     reasons.push(`Accepted checkpoints (${acceptedCount}) do not cover required checkpoints (${Math.max(requiredCheckpoints, 1)}).`);
     nextActions.push('Complete and review the remaining planned checkpoints.');
-  } else if (contract.task_scope === 'project' && !projectCompletionAccepted) {
+  } else if ((contract.task_scope === 'project' || projectCompletionInProgress || deferredGateCount > 0) && !projectCompletionAccepted) {
     outcome = 'project_in_progress';
     reasons.push('The latest milestone is accepted, but the project terminal contract is not accepted.');
-    nextActions.push('Continue with the next safe actionable project backlog item.');
+    if (deferredGateCount > 0) reasons.push(`${deferredGateCount} deferred authorization gate(s) remain and must be materialized as waiting gates when no unrelated safe work is actionable.`);
+    nextActions.push('Reread the authoritative project ledger and continue with the next safe actionable backlog item, or wait on a structured authorization gate.');
   } else if (contract.requires_human_gate) {
     outcome = 'ready_for_human_review';
     reasons.push('All reviewed checkpoints are accepted, and the task contract requires a human gate.');
@@ -3269,6 +3656,7 @@ export function buildFinalJudgement(contract, acceptancePlan, devPlan, checkpoin
       accepted: acceptedCount,
       revise: reviseCount,
       blocked: blockedCount,
+      deferred_gates: deferredGateCount,
       rubric_items: Array.isArray(acceptancePlan?.rubric) ? acceptancePlan.rubric.length : 0,
       automation_suggestions: Array.isArray(acceptancePlan?.automation) ? acceptancePlan.automation.length : 0
     },
@@ -3437,6 +3825,7 @@ async function listJson(dir) {
 export async function queueStatus(root, queue) {
   normalizeLoopId(queue);
   await ensureQueueDirs(root, queue);
+  await reconcileProjectGates(root, { queue });
   const activeFiles = await listJson(queueSubdirFor(root, queue, 'active'));
   const lock = await readQueueLock(root, queue);
   const lockOwnerAlive = queueLockOwnerAlive(lock);
@@ -3447,7 +3836,7 @@ export async function queueStatus(root, queue) {
       taskId: task.id,
       status: task.status,
       waitId: task.parked?.wait_id ?? task.waitingGateId ?? null,
-      waitKind: task.parked?.kind ?? (task.status === 'waiting_for_human' ? 'human_input' : null),
+      waitKind: task.parked?.kind ?? task.waitKind ?? (task.status === 'waiting_for_human' ? 'human_input' : null),
       displayState: task.parked ? parkedDisplayState(task.parked) : task.status,
       parkedAt: task.parked?.parked_at ?? task.waitingSince ?? null,
       reminderCount: Number(task.parked?.reminder_count ?? 0),
@@ -8137,13 +8526,22 @@ function shellQuote(value) {
   return `'${String(value).replace(/'/g, `'\\''`)}'`;
 }
 
+// Linux limits the size of a single argv/env string (commonly 128 KiB). Revision
+// tasks can legitimately exceed that after many checkpoints, so keep the
+// legacy inline body only for bounded tasks. The authoritative task body is
+// always available through LOOP_TASK_FILE.
+const MAX_INLINE_TASK_BODY_BYTES = 32 * 1024;
+
 function buildQueueEnv(root, queue, task, taskFile, runId, extra = {}) {
+  const taskBody = String(task.body ?? '');
+  const inlineTaskBody = Buffer.byteLength(taskBody, 'utf8') <= MAX_INLINE_TASK_BODY_BYTES;
   return {
     ...process.env,
     LOOP_QUEUE_ID: queue,
     LOOP_TASK_ID: task.id,
     LOOP_TASK_TITLE: task.title,
-    LOOP_TASK_BODY: task.body,
+    ...(inlineTaskBody ? { LOOP_TASK_BODY: taskBody } : {}),
+    LOOP_TASK_BODY_MODE: inlineTaskBody ? 'inline' : 'task_file',
     LOOP_TASK_FILE: taskFile,
     LOOP_TASK_FILE_REL: path.relative(root, taskFile),
     LOOP_RUN_ID: runId,
@@ -8465,6 +8863,7 @@ async function runPreflight(root, config, timeoutMs) {
 export async function runQueueOnce(root, options) {
   const queue = normalizeLoopId(options.queue);
   await ensureQueueDirs(root, queue);
+  await reconcileProjectGates(root, { queue });
   let progressTask = null;
   const liveProgressNotifications = [];
   let liveProgressChain = Promise.resolve();