taskforce-loop-engineering 0.7.1 → 0.7.2

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.7.2 - 2026-08-06
+
+- Keep `ready_for_human_review` tasks out of `done/` until an explicit human decision is recorded; emit a scoped acceptance notification, fail closed when delivery routing is missing, and transition approved tasks to `completed` only after approval.
+- Forward configured human-gate policy into generated task contracts so queue state and final judgement agree.
+- Add regression coverage for the complete `ready_for_human_review → approve → completed` lifecycle.
+
 ## 0.7.1 - 2026-08-05
 
 - Make the standalone ClawHub skill self-sufficient by documenting the official npm package, GitHub repository, Node.js requirement, license, and installation commands.

package/lib/core.mjs

@@ -1673,13 +1673,20 @@ export async function routeLoopMessage(root, options = {}) {
 }
 
 function terminalNotificationMessage(queue, task) {
-  const needsHuman = ['needs_human_input', 'blocked'].includes(task.status);
+  const needsReview = task.status === 'ready_for_human_review';
+  const needsHuman = ['needs_human_input', 'blocked', 'ready_for_human_review'].includes(task.status);
   return [
-    needsHuman ? 'Loop task needs human input' : 'Loop task reached a terminal state',
+    needsReview ? 'Loop task is ready for human acceptance'
+      : needsHuman ? 'Loop task needs human input'
+        : 'Loop task reached a terminal state',
     `task: ${task.title}`,
     `queue: ${queue}`,
     `status: ${task.status}`,
-    ...(needsHuman ? ['next: inspect the task final judgement and checkpoints, resolve the blocker, then explicitly continue or requeue.'] : [])
+    ...(needsReview
+      ? [`next: review the final judgement and record approve, request_changes, or reject for task ${task.id}.`]
+      : needsHuman
+        ? ['next: inspect the task final judgement and checkpoints, resolve the blocker, then explicitly continue or requeue.']
+        : [])
   ].join('\n');
 }
 
@@ -1696,7 +1703,16 @@ export async function notifyTerminalTasks(root, options = {}) {
     const dir = queueSubdirFor(root, queue, subdir);
     for (const file of await listJson(dir)) {
       const task = await readJson(path.join(dir, file));
-      if (!task?.source || !task?.id || !task?.status) continue;
+      if (!task?.id || !task?.status) continue;
+      if (!task?.source?.channel || !task?.source?.target) {
+        results.push({
+          taskId: task.id,
+          status: task.status,
+          outcome: 'failed',
+          error: 'missing source.channel/source.target; refusing unscoped terminal delivery'
+        });
+        continue;
+      }
       const key = `${safeTaskId(task.id)}.${normalizeLoopId(task.status)}.json`;
       const ledgerFile = path.join(notificationDir, key);
       if (await exists(ledgerFile)) {
@@ -2792,7 +2808,8 @@ function queueStatusFromFinalJudgement(currentStatus, finalJudgement) {
   if (!finalJudgement?.judgement) return currentStatus;
   if (currentStatus !== 'completed') return currentStatus;
   const outcome = finalJudgement.judgement.outcome;
-  if (outcome === 'ready_for_human_review' || outcome === 'ready_to_apply') return currentStatus;
+  if (outcome === 'ready_to_apply') return currentStatus;
+  if (outcome === 'ready_for_human_review') return outcome;
   return outcome;
 }
 
@@ -4069,6 +4086,27 @@ export async function queueHumanDecision(root, queue, taskId, options = {}) {
   };
   await writeJson(file, artifact);
 
+  let transitionedTask = null;
+  if (decision === 'approve' && found.subdir !== 'done') {
+    const completedAt = artifact.created_at;
+    transitionedTask = {
+      ...task,
+      status: 'completed',
+      humanApprovedAt: completedAt,
+      humanReviewDecision: path.relative(root, file)
+    };
+    const completedFile = path.join(queueSubdirFor(root, normalized, 'done'), path.basename(found.file));
+    await writeJson(completedFile, transitionedTask);
+    await rm(found.file, { force: true });
+    artifact.effects.queueTransition = {
+      from: found.subdir,
+      to: 'done',
+      status: 'completed',
+      file: path.relative(root, completedFile)
+    };
+    await writeJson(file, artifact);
+  }
+
   let revisionRequest = null;
   if (decision === 'request_changes') {
     const revisionFile = path.join(dir, 'human_revision_request.json');
@@ -4098,6 +4136,7 @@ export async function queueHumanDecision(root, queue, taskId, options = {}) {
     decisionFile: path.relative(root, file),
     revisionRequestFile: revisionRequest?.path ?? null,
     revisionNext,
+    transitionedTask,
     artifact
   };
 }
@@ -7901,7 +7940,11 @@ export async function runQueueOnce(root, options) {
     let revisionRequest = null;
 
     try {
-      taskContract = await writeTaskContract(root, queue, task);
+      taskContract = await writeTaskContract(root, queue, task, {
+        riskLevel: options.riskLevel,
+        riskReasons: options.riskReasons,
+        requiresHumanGate: options.requiresHumanGate
+      });
       progress.emit('planning', 'task_contract', `Wrote task contract (${taskContract.contract.risk_level})`, {
         taskId: task.id,
         artifact: taskContract.file,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "taskforce-loop-engineering",
-  "version": "0.7.1",
+  "version": "0.7.2",
   "private": false,
   "description": "OpenClaw-native loop engineering CLI, templates, and skill for verifiable agent work loops.",
   "type": "module",

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

@@ -10,6 +10,8 @@ import {
   normalizeGoalDecision,
   notifyHumanInputRequests,
   notifyTerminalTasks,
+  queueHumanDecision,
+  queueStatus,
   queueSubdirFor,
   readJson,
   routeLoopMessage,
@@ -76,6 +78,55 @@ 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 reviewQueue = 'human-review-smoke';
+const reviewTask = await routeLoopMessage(root, {
+  route: true,
+  confirmExecute: true,
+  queue: reviewQueue,
+  message: '走 loop 生成需要人工验收的交付物',
+  sourceChannel: 'feishu',
+  sourceTarget: 'user-1'
+});
+let reviewCheckpointWrite = null;
+const reviewRun = await runQueueOnce(root, {
+  queue: reviewQueue,
+  dispatcher: '/bin/sleep 0.1',
+  requiresHumanGate: true,
+  timeoutMs: 10_000,
+  leaseMs: 20_000,
+  staleActiveMs: 60_000,
+  onProgress: (event) => {
+    if (event.phase !== 'dispatch' || event.status !== 'running' || reviewCheckpointWrite) return;
+    reviewCheckpointWrite = writeJson(path.join(taskRuntimeDirFor(root, reviewQueue, reviewTask.task.id), 'checkpoints', 'cp-review.json'), {
+      version: 1,
+      task_id: reviewTask.task.id,
+      checkpoint_id: 'cp-review',
+      status: 'ready_for_acceptance',
+      summary: 'The deliverable is complete and explicitly awaits human acceptance.',
+      files_changed: [],
+      verification: [{ command: '/bin/true', outcome: 'passed' }],
+      blockers: [],
+      risks: [],
+      next_action: 'human_acceptance'
+    });
+  }
+});
+await reviewCheckpointWrite;
+assert.equal(reviewRun.status, 'ready_for_human_review');
+assert.match(reviewRun.taskPath, /failed/);
+const reviewStatus = await queueStatus(root, reviewQueue);
+assert.equal(reviewStatus.done, 0);
+assert.equal(reviewStatus.failed, 1);
+const reviewNotice = await notifyTerminalTasks(root, { queue: reviewQueue, dryRun: true });
+assert.equal(reviewNotice.results[0].outcome, 'dry_run');
+assert.match(reviewNotice.results[0].message, /ready for human acceptance/);
+assert.match(reviewNotice.results[0].message, /approve, request_changes, or reject/);
+const reviewDecision = await queueHumanDecision(root, reviewQueue, reviewTask.task.id, { decision: 'approve' });
+assert.equal(reviewDecision.transitionedTask.status, 'completed');
+const approvedStatus = await queueStatus(root, reviewQueue);
+assert.equal(approvedStatus.done, 1);
+assert.equal(approvedStatus.failed, 0);
+
 for (const suffix of ['second', 'third']) {
   await routeLoopMessage(root, {
     route: true,