taskforce-loop-engineering 0.14.0 → 0.15.0

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## Unreleased
 
+## 0.15.0 - 2026-08-20
+
+- Reconcile project-scoped human gates against the authoritative project contract and acceptance ledger, superseding stale or optional deferred gates without replay.
+- Strengthen doctor and project status checks for structured gate context, acceptance-ledger drift, execution-ledger reconciliation, and project completion.
+- Make active-task supersession project-aware across active and waiting tasks, and add end-to-end regression coverage for durable gate materialization.
+
 ## 0.14.0 - 2026-08-14
 
 - Add the platform-neutral runtime adapter SDK v1 with OpenClaw, Hermes, Codex CLI, and Claude Code factories, shared conformance tests, fail-closed effects, redacted telemetry, migration guidance, and a credential-free demo.

package/lib/core.mjs

@@ -651,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) {
@@ -749,6 +750,24 @@ 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));
@@ -1025,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.');
@@ -1133,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');
 }
@@ -1594,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;
@@ -1612,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,
@@ -1627,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.']
   };
 }
 
@@ -1659,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) } : {})
@@ -1757,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') {
@@ -1785,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);
@@ -1804,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);
@@ -1838,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');
@@ -1905,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 = [];
@@ -1913,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,
@@ -2024,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 任务正在等待你的输入',
@@ -2056,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.');
@@ -2067,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));
@@ -2097,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) {
@@ -2124,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,
@@ -2466,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,
@@ -2584,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,
@@ -2596,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 {
@@ -2776,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,
@@ -2843,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,
@@ -3123,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)
     });
@@ -3195,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') {
@@ -3245,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.');
@@ -3285,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
     },
@@ -3453,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);
@@ -3463,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),
@@ -8153,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,
@@ -8481,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();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "taskforce-loop-engineering",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "private": false,
   "description": "OpenClaw-native loop engineering CLI, templates, and skill for verifiable agent work loops.",
   "type": "module",
@@ -23,6 +23,7 @@
     "check:config-drift": "node --check scripts/config-drift-self-test.mjs && node scripts/config-drift-self-test.mjs",
     "check:openclaw-install": "node --check scripts/openclaw-install.mjs && node --check scripts/openclaw-doctor.mjs && node --check scripts/openclaw-smoke.mjs && node --check scripts/openclaw-manage.mjs && node scripts/openclaw-install-self-test.mjs",
     "check:hermes-install": "node --check scripts/hermes-install.mjs && node --check scripts/hermes-doctor.mjs && node --check scripts/hermes-smoke.mjs && node scripts/hermes-install-self-test.mjs",
+    "check:project-gates": "node --check lib/core.mjs && node scripts/project-gate-reconciliation-self-test.mjs",
     "check": "npm run check:config-drift && npm run check:openclaw-install && npm run check:hermes-install && node --check bin/loop-engineering.mjs && node --check lib/core.mjs && node --check lib/action-reservations.mjs && node --check lib/todo-control-plane.mjs && node --check lib/operator-dashboard.mjs && node scripts/action-reservation-self-test.mjs && node scripts/todo-control-plane-self-test.mjs && node scripts/operator-dashboard-self-test.mjs && node scripts/final-judgement-self-test.mjs && node scripts/route-notify-self-test.mjs && node scripts/scheduler-heartbeat-self-test.mjs && node scripts/human-gate-lifecycle-v2-self-test.mjs && node bin/loop-engineering.mjs verify --config templates/workspace-health.json --root . && node bin/loop-engineering.mjs queue-status --queue smoke --root . --json >/dev/null && node bin/loop-engineering.mjs project-intake --root /tmp/loop-engineering-check --name smoke-project --brief \"Build a small website project\" --type auto --check \"npm test\" --json >/dev/null && node bin/loop-engineering.mjs project-plan --root /tmp/loop-engineering-check --project smoke-project --force --json >/dev/null && node bin/loop-engineering.mjs project-status --root /tmp/loop-engineering-check --project smoke-project --json >/dev/null && node bin/loop-engineering.mjs queue-scheduler-tick --queue smoke --root /tmp/loop-engineering-check --plan-only --force-due --json >/dev/null && node bin/loop-engineering.mjs queue-scheduler-tick --queue smoke-progress --root /tmp/loop-engineering-check --plan-only --force-due --progress-report --progress-report-when-not-due --json >/dev/null && node bin/loop-engineering.mjs workflow-metrics --queue smoke --root . --json >/dev/null && node bin/loop-engineering.mjs workflow-tune-plan --queue smoke --root . --json >/dev/null && node bin/loop-engineering.mjs code-queue-init --queue smoke-code --root /tmp/loop-engineering-check --force >/dev/null && node bin/loop-engineering.mjs code-worktree-list --queue smoke-code --root /tmp/loop-engineering-check --json >/dev/null && node bin/loop-engineering.mjs code-task-status --queue smoke-code --root /tmp/loop-engineering-check --json >/dev/null && node bin/loop-engineering.mjs code-task-dashboard --queue smoke-code --root /tmp/loop-engineering-check --json >/dev/null && node bin/loop-engineering.mjs code-worktree-cleanup-plan --queue smoke-code --root /tmp/loop-engineering-check --json >/dev/null && node bin/loop-engineering.mjs code-worktree-cleanup --queue smoke-code --root /tmp/loop-engineering-check --confirm-cleanup --json >/dev/null && node bin/loop-engineering.mjs code-patch-verify --patch README.md --root . --json >/dev/null && node bin/loop-engineering.mjs code-patch-apply-plan --patch README.md --json >/dev/null && node bin/loop-engineering.mjs queue-revision-ci-self-test --queue smoke-ci --root /tmp/loop-engineering-check --json >/dev/null && node bin/loop-engineering.mjs summarize --root . --json >/dev/null && node bin/loop-engineering.mjs dashboard-health --root . --max-age-seconds 999999999 --json >/dev/null && node bin/loop-engineering.mjs doctor --root . --json >/dev/null",
     "pack:dry": "npm pack --dry-run"
   },

package/scripts/final-judgement-self-test.mjs

@@ -1,9 +1,15 @@
 import assert from 'node:assert/strict';
-import { buildFinalJudgement, dispatchFailureClassification, selectEffectiveAcceptanceReviews } from '../lib/core.mjs';
+import { buildFinalJudgement, dispatchFailureClassification, inferTaskScope, selectEffectiveAcceptanceReviews } from '../lib/core.mjs';
 
 const basePlan = { rubric: [], automation: [] };
 const baseContract = { task_id: 't1', risk_level: 'L1', requires_human_gate: false, task_scope: 'scoped_task' };
 
+assert.equal(inferTaskScope({ body: '开发完整项目并完成整体目标' }), 'project');
+assert.equal(inferTaskScope({ body: '继续同一整体项目，仅推进 T-01 第 2 项；阶段完成后不能称整体项目完成' }), 'scoped_task');
+assert.equal(inferTaskScope({ body: 'Continue the project, only complete boundary item 2' }), 'scoped_task');
+assert.equal(inferTaskScope({ body: '继续同一整体项目，取消团队功能并从项目完成门槛中移除，其他 backlog 不变' }), 'scoped_task');
+assert.equal(inferTaskScope({ body: 'Continue the overall project with a product-scope amendment: remove the team feature from the completion gate.' }), 'scoped_task');
+
 {
   const devPlan = { checkpoints: [{ id: 'cp1' }] };
   const reviews = {
@@ -96,6 +102,19 @@ const baseContract = { task_id: 't1', risk_level: 'L1', requires_human_gate: fal
   assert.equal(judgement.outcome, 'project_in_progress');
 }
 
+{
+  const devPlan = { checkpoints: [{ id: 'cp1' }] };
+  const reviews = { reviews: [{
+    checkpointId: 'cp1', sequence: 1, status: 'accepted',
+    projectCompletion: { status: 'in_progress' },
+    deferredGates: [{ id: 'deploy', required_authority: 'owner deployment approval' }]
+  }] };
+  const judgement = buildFinalJudgement(baseContract, basePlan, devPlan, { count: 1 }, reviews, { dispatchStatus: 'completed' });
+  assert.equal(judgement.outcome, 'project_in_progress');
+  assert.equal(judgement.coverage.deferred_gates, 1);
+  assert.match(judgement.reasons.join(' '), /structured|waiting gates/);
+}
+
 {
   const devPlan = { checkpoints: [{ id: 'cp1' }] };
   const reviews = { reviews: [{ checkpointId: 'cp6', sequence: 6, status: 'accepted', projectCompletion: { status: 'accepted' } }] };

package/scripts/project-gate-reconciliation-self-test.mjs

@@ -0,0 +1,107 @@
+import assert from 'node:assert/strict';
+import { mkdtemp, mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { doctorReport, enqueueTask, notifyHumanInputRequests, projectStatus, queueStatus, reconcileProjectGates, routeLoopMessage, taskRuntimeDirFor } from '../lib/core.mjs';
+
+const root = await mkdtemp(path.join(os.tmpdir(), 'loop-project-gates-'));
+const queue = 'shared';
+const projectFile = path.join(root, 'configs', 'loops', 'projects', 'openreel.json');
+const spec = { schemaVersion: 1, project: 'openreel', type: 'code_project', queues: [{ queue, kind: 'standard' }], backlog: [
+  { id: 'B-01', required: true, status: 'human_gated', dependsOn: [] },
+  { id: 'S-01', required: true, status: 'human_gated', dependsOn: [] }
+] };
+await mkdir(path.dirname(projectFile), { recursive: true });
+await writeFile(projectFile, `${JSON.stringify(spec, null, 2)}\n`);
+
+const b = await enqueueTask(root, { queue, title: 'OpenReel B-01', task: 'Project openreel requirement B-01', projectId: 'openreel', sourceChannel: 'test', sourceTarget: 'owner' });
+const checkpointDir = path.join(taskRuntimeDirFor(root, queue, b.task.id), 'checkpoints');
+await mkdir(checkpointDir, { recursive: true });
+await writeFile(path.join(checkpointDir, 'cp1.json'), `${JSON.stringify({ version: 1, task_id: b.task.id, checkpoint_id: 'cp1', milestone_id: 'B-01', requirement_ids: ['B-01'], status: 'needs_human_input', blockers: ['Authorize B-01'] }, null, 2)}\n`);
+const notified = await notifyHumanInputRequests(root, { queue, notifyCommand: '/bin/true' });
+assert.equal(notified.sent, 1);
+assert.equal((await queueStatus(root, queue)).waiting, 1);
+const gateFile = path.join(root, notified.results[0].ledger);
+const gate = JSON.parse(await readFile(gateFile, 'utf8'));
+assert.equal(gate.project_id, 'openreel');
+assert.equal(gate.milestone_id, 'B-01');
+assert.deepEqual(gate.requirement_ids, ['B-01']);
+assert.equal(typeof gate.contract_hash, 'string');
+
+spec.backlog[0] = { ...spec.backlog[0], required: false, status: 'out_of_scope', disposition: 'canceled_by_owner' };
+await writeFile(projectFile, `${JSON.stringify(spec, null, 2)}\n`);
+const status = await queueStatus(root, queue);
+assert.equal(status.waiting, 0, 'B-01 waiting gate must disappear after B-01 leaves project scope');
+assert.equal(status.canceled, 1);
+assert.equal(JSON.parse(await readFile(gateFile, 'utf8')).status, 'canceled');
+
+const other = await enqueueTask(root, { queue, title: 'Other project task', task: 'Project other', projectId: 'other' });
+const openreel = await enqueueTask(root, { queue, title: 'OpenReel target', task: 'Project openreel', projectId: 'openreel' });
+await rename(path.join(root, other.file), path.join(root, 'runtime', 'loops', queue, 'active', path.basename(other.file)));
+await rename(path.join(root, openreel.file), path.join(root, 'runtime', 'loops', queue, 'active', path.basename(openreel.file)));
+const replacement = await routeLoopMessage(root, { route: true, confirmExecute: true, supersedeActive: true, queue, message: '走 loop：继续 openreel 项目' });
+assert.equal(replacement.supersededTaskId, openreel.task.id);
+assert.equal(await readFile(path.join(taskRuntimeDirFor(root, queue, other.task.id), 'supersede_request.json'), 'utf8').then(() => true, () => false), false);
+
+const invalidGate = { ...gate, gate_id: `${openreel.task.id}:bad`, task_id: openreel.task.id, checkpoint_id: 'bad', status: 'waiting_for_human', requirement_ids: ['MISSING'] };
+const invalidFile = path.join(root, 'runtime', 'loops', queue, 'human-input', 'gates', `${openreel.task.id}.bad.json`);
+await writeFile(invalidFile, `${JSON.stringify(invalidGate, null, 2)}\n`);
+const doctor = await doctorReport(root);
+assert.equal(doctor.ok, false);
+assert(doctor.checks.some((check) => check.id === `human-gate:${invalidGate.gate_id}` && !check.ok));
+await reconcileProjectGates(root, { queue });
+
+// project-status treats the configured ledger/backlog as authoritative and
+// exposes registry drift instead of silently reporting stale completion data.
+const authoritativeBacklog = path.join(root, 'project', 'backlog.json');
+const authoritativeLedger = path.join(root, 'project', 'acceptance-ledger.json');
+await mkdir(path.dirname(authoritativeBacklog), { recursive: true });
+await writeFile(authoritativeBacklog, `${JSON.stringify({ status: 'ongoing', items: [{ id: 'S-01', required: true, status: 'accepted' }] }, null, 2)}\n`);
+await writeFile(authoritativeLedger, `${JSON.stringify({ status: 'ongoing', unmet: ['S-01'], blockers: [{ id: 'S-01' }] }, null, 2)}\n`);
+await writeFile(projectFile, `${JSON.stringify({ ...spec, backlogSource: 'project/backlog.json', acceptanceLedger: 'project/acceptance-ledger.json', terminalContract: 'project/terminal.md' }, null, 2)}\n`);
+const drifted = await projectStatus(root, { project: 'openreel' });
+assert.equal(drifted.projectCompletion, 'in_progress');
+assert.equal(drifted.authority.acceptanceLedger, 'project/acceptance-ledger.json');
+assert.equal(drifted.consistency.ok, false);
+assert(drifted.needsAttention.includes('authoritative_source_drift'));
+
+// A ready milestone with project in progress and a deferred authorization is
+// converted into a structured waiting gate, not left as prose on a done task.
+const deferred = await enqueueTask(root, { queue, title: 'OpenReel deferred S-01', task: 'Project openreel S-01', projectId: 'openreel', sourceChannel: 'test', sourceTarget: 'owner' });
+const deferredDir = path.join(taskRuntimeDirFor(root, queue, deferred.task.id), 'checkpoints');
+await mkdir(deferredDir, { recursive: true });
+await writeFile(path.join(deferredDir, 'cp-ready.json'), `${JSON.stringify({
+  version: 1, task_id: deferred.task.id, checkpoint_id: 'cp-ready', milestone_id: 'S-01', requirement_ids: ['S-01'],
+  status: 'ready_for_acceptance', blockers: [], verification: ['local phase passed'], risks: [],
+  project_completion: { status: 'in_progress' },
+  deferred_gates: [{ id: 'S-01-production', action: 'production_rollback_drill', required_authority: 'Owner authorization for the exact production rollback drill scope.' }]
+}, null, 2)}\n`);
+const deferredNotice = await notifyHumanInputRequests(root, { queue, notifyCommand: '/bin/true' });
+const deferredResult = deferredNotice.results.find((item) => item.taskId === deferred.task.id);
+assert.equal(deferredResult.outcome, 'sent');
+const deferredGate = JSON.parse(await readFile(path.join(root, deferredResult.ledger), 'utf8'));
+assert.equal(deferredGate.gate_kind, 'deferred_authorization');
+assert.equal(deferredGate.authorization_requirements[0].action, 'production_rollback_drill');
+assert.match(deferredGate.authorization_requirements[0].required_authority, /Owner authorization/);
+assert.equal((await queueStatus(root, queue)).waiting >= 1, true);
+
+// Once the authoritative project ledger accepts the terminal contract, an
+// optional post-completion deferred action stays in operations backlog and
+// neither creates nor retains a project-queue waiting gate.
+await writeFile(authoritativeLedger, `${JSON.stringify({ status: 'accepted', unmet: [], blockers: [] }, null, 2)}\n`);
+await reconcileProjectGates(root, { queue });
+assert.equal((await queueStatus(root, queue)).waiting, 0);
+assert.equal(JSON.parse(await readFile(path.join(root, deferredResult.ledger), 'utf8')).status, 'superseded');
+const acceptedOptional = await enqueueTask(root, { queue, title: 'OpenReel optional operations transfer', task: 'Project openreel optional post-completion transfer', projectId: 'openreel', sourceChannel: 'test', sourceTarget: 'owner' });
+const acceptedOptionalDir = path.join(taskRuntimeDirFor(root, queue, acceptedOptional.task.id), 'checkpoints');
+await mkdir(acceptedOptionalDir, { recursive: true });
+await writeFile(path.join(acceptedOptionalDir, 'cp1.json'), `${JSON.stringify({
+  version: 1, task_id: acceptedOptional.task.id, checkpoint_id: 'cp1', milestone_id: 'cp1',
+  status: 'ready_for_acceptance', blockers: [], project_completion: { status: 'accepted' },
+  deferred_gates: [{ id: 'optional-transfer', required_authority: 'Separate authorization for optional production transfer.' }]
+}, null, 2)}\n`);
+const acceptedNotice = await notifyHumanInputRequests(root, { queue, notifyCommand: '/bin/true' });
+assert.equal(acceptedNotice.results.some((item) => item.taskId === acceptedOptional.task.id), false);
+assert.equal((await queueStatus(root, queue)).waiting, 0);
+
+console.log(JSON.stringify({ status: 'ok', assertions: ['structured gate context', 'B-01 waiting to zero', 'project-isolated supersede', 'doctor strong validation', 'authoritative ledger drift', 'ready milestone deferred gate', 'accepted project optional deferred gate stays out of queue'] }));

package/scripts/route-notify-self-test.mjs

@@ -89,6 +89,27 @@ const contract = await readJson(path.join(taskRuntimeDirFor(root, queue, routed.
 assert.equal(contract.risk_level, 'model_assessed');
 assert.equal(contract.requires_human_gate, false);
 
+const largeBodyQueue = 'large-body-smoke';
+const largeBody = `走 loop 验证超长任务正文\n${'checkpoint evidence '.repeat(10_000)}`;
+const largeBodyRouted = await routeLoopMessage(root, {
+  route: true,
+  confirmExecute: true,
+  queue: largeBodyQueue,
+  message: largeBody,
+  sourceChannel: 'feishu',
+  sourceTarget: 'user-1'
+});
+const largeBodyRun = await runQueueOnce(root, {
+  queue: largeBodyQueue,
+  dispatcher: `node -e "const fs=require('fs');const t=JSON.parse(fs.readFileSync(process.env.LOOP_TASK_FILE,'utf8'));if(process.env.LOOP_TASK_BODY!==undefined||process.env.LOOP_TASK_BODY_MODE!=='task_file'||t.body.length<100000)process.exit(7)"`,
+  progressNotifyCommand: '/bin/true',
+  timeoutMs: 10_000,
+  leaseMs: 20_000,
+  staleActiveMs: 60_000
+});
+assert.equal(largeBodyRun.processed, true);
+assert.equal(largeBodyRun.run.dispatch.exitCode, 0);
+
 const orphanQueue = 'orphan-recovery-smoke';
 const orphanRouted = await routeLoopMessage(root, {
   route: true,
@@ -483,5 +504,35 @@ assert.equal(sent.sent, 1);
 const repeated = await notifyTerminalTasks(root, { queue, notifyCommand: '/bin/true' });
 assert.equal(repeated.results[0].outcome, 'already_notified');
 
+// Real directory-level regression: terminal history plus the newest project
+// carrier yields exactly one durable gate, one waiting task, and zero replay.
+const regressionRoot = await mkdtemp(path.join(tmpdir(), 'loop-gate-regression-'));
+const regressionQueue = 'project-regression';
+await writeJson(path.join(regressionRoot, 'configs', 'loops', 'projects', 'demo.json'), {
+  schemaVersion: 1, project: 'demo', queues: [{ queue: regressionQueue }],
+  backlog: [{ id: 'R-1', status: 'human_gated', required: true }]
+});
+for (const [id, enqueuedAt] of [['history-done', '2026-01-01T00:00:00Z'], ['latest-done', '2026-01-02T00:00:00Z']]) {
+  await writeJson(path.join(queueSubdirFor(regressionRoot, regressionQueue, 'done'), `${id}.json`), {
+    id, title: `demo ${id}`, body: 'demo R-1', projectId: 'demo', status: 'completed', enqueuedAt,
+    source: { channel: 'test', target: 'owner' }
+  });
+  await writeJson(path.join(taskRuntimeDirFor(regressionRoot, regressionQueue, id), 'checkpoints', 'cp1.json'), {
+    version: 1, task_id: id, checkpoint_id: 'cp1', milestone_id: 'R-1', sequence: 1,
+    status: 'ready_for_acceptance', blockers: [], deferred_gates: [{ id: 'R-1', required_authority: 'Approve R-1.' }],
+    verification: [], risks: [], project_completion: 'in_progress', next_action: 'wait'
+  });
+  await writeJson(path.join(taskRuntimeDirFor(regressionRoot, regressionQueue, id), 'final_judgement.json'), {
+    version: 1, task_id: id, outcome: 'project_in_progress', coverage: { effective_review_ids: ['cp1'] }
+  });
+}
+const regressionFirst = await notifyHumanInputRequests(regressionRoot, { queue: regressionQueue, notifyCommand: '/bin/true' });
+assert.equal(regressionFirst.sent, 1);
+assert.equal((await queueStatus(regressionRoot, regressionQueue)).waiting, 1);
+assert.equal((await readdir(path.join(queueDirFor(regressionRoot, regressionQueue), 'human-input', 'gates'))).length, 1);
+assert.equal((await readdir(queueSubdirFor(regressionRoot, regressionQueue, 'done'))).length, 1);
+const regressionRepeated = await notifyHumanInputRequests(regressionRoot, { queue: regressionQueue, notifyCommand: '/bin/true' });
+assert.equal(regressionRepeated.sent, 0);
+
 console.log('route/notify self-test passed');
 await import('./config-drift-self-test.mjs');