taskforce-loop-engineering 0.7.0 → 0.7.2

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # 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.
+- Distinguish installing the skill, installing the CLI, and integrating the CLI with OpenClaw.
+- Add plan, confirmed install, doctor, and disposable smoke commands for a verifiable OpenClaw deployment.
+- Require checking an exact workspace source path before using the source-only CLI fallback.
+
 ## 0.7.0 - 2026-08-05
 
 - Rename the project, npm package, GitHub repository, and bundled skill to Taskforce Loop Engineering.

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.0",
+  "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,

package/skills/taskforce-loop-engineering/SKILL.md

@@ -9,6 +9,85 @@ Use this skill only when the user explicitly invokes Loop Engineering, says `走
 
 Do not route ordinary chat, research, explanations, or simple direct tasks into a loop unless the user explicitly invokes it.
 
+## Distribution and CLI Installation
+
+A ClawHub installation may provide only this `SKILL.md`; it does **not** prove that the Loop Engineering CLI or OpenClaw integration is installed. Before running loop commands, check the deployment explicitly:
+
+```bash
+command -v loop-engineering
+loop-engineering --help
+```
+
+Official distribution:
+
+- npm package: `taskforce-loop-engineering`
+- GitHub repository: `https://github.com/ambitioncn/taskforce-loop-engineering`
+- ClawHub skill: `https://clawhub.ai/ambitioncn/skills/taskforce-loop-engineering`
+- license: Apache-2.0
+- runtime requirement: Node.js 22 or newer
+
+Install the CLI globally from npm:
+
+```bash
+node --version
+npm install -g taskforce-loop-engineering
+loop-engineering --help
+```
+
+For a temporary read-only invocation without a global install:
+
+```bash
+npx -p taskforce-loop-engineering loop-engineering --help
+```
+
+For source-based development, clone the official repository and install its dependencies:
+
+```bash
+git clone https://github.com/ambitioncn/taskforce-loop-engineering.git
+cd taskforce-loop-engineering
+npm install
+npm run check
+node bin/loop-engineering.mjs --help
+```
+
+Do not guess a workspace source path. Use `node packages/loop-engineering/bin/loop-engineering.mjs ...` only after confirming that exact path exists in the current workspace.
+
+### OpenClaw Integration
+
+Installing the npm package exposes the CLI, but it does not automatically route conversations, select a worker agent, or create queue wrappers. First generate a read-only installation plan:
+
+```bash
+loop-engineering-openclaw-install \
+  --root /path/to/openclaw/workspace \
+  --queue agent-tasks
+```
+
+Review the detected agents and planned files. Then install with an existing worker-agent id:
+
+```bash
+loop-engineering-openclaw-install \
+  --root /path/to/openclaw/workspace \
+  --queue agent-tasks \
+  --worker-agent main \
+  --confirm-install
+```
+
+The installer never creates the worker agent. After installation, verify wiring before using a real task:
+
+```bash
+loop-engineering-openclaw-doctor \
+  --root /path/to/openclaw/workspace \
+  --queue agent-tasks \
+  --worker-agent main
+
+loop-engineering-openclaw-smoke \
+  --root /path/to/openclaw/workspace \
+  --queue agent-tasks \
+  --worker-agent main
+```
+
+If the CLI or integration is missing and the user requested installation or repair, install it within the authorized host/workspace scope, then run doctor and the disposable smoke. If the user only asked what is missing, report the exact package, repository, commands, and current deployment state without mutating the system.
+
 ## Conversation Contract
 
 Interpret explicit loop language as follows: