taskforce-loop-engineering 0.15.5 → 0.15.7

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 ## Unreleased
 
+## 0.15.7 - 2026-08-24
+
+- Prevent accepted phase checkpoints from producing `ready_to_apply` when they explicitly mark project completion as `in_progress`, including both string and object completion forms.
+- Preserve unresolved checkpoint risks in the final judgement and treat a concrete continuation action as project work that must continue instead of terminal completion.
+- Use an accepted terminal contract as the authoritative project-completion source when no separate acceptance ledger is configured.
+- Reconcile stale optional post-completion authorization gates into `done` rather than `canceled`, while retaining fail-closed behavior for real blockers.
+- Add regression coverage for premature terminal judgement, terminal-contract status projection, and historical stale-gate reconciliation.
+
+## 0.15.6 - 2026-08-24
+
+- Allow project configurations to use an external authoritative `backlogSource` without duplicating an embedded backlog registry.
+- Keep project status fail-closed when neither an embedded backlog nor an external backlog source is configured.
+- Suppress false registry-drift findings when no embedded projection is intentionally present, while retaining drift detection when both representations exist.
+- Add regression coverage for external-only authoritative project backlogs.
+
 ## 0.15.5 - 2026-08-24
 
 - Treat embedded-runtime `incomplete_turn` / abandoned-liveness trailers as recoverable interruptions even when the dispatcher wrapper exits zero, preventing partial work from being accepted or stale human gates from being replayed.

package/lib/core.mjs

@@ -1173,20 +1173,34 @@ async function projectSpecs(root) {
   return specs;
 }
 
-async function projectTerminalAccepted(root, spec) {
+function acceptedTerminalRecord(record) {
+  if (!record || typeof record !== 'object') return false;
+  const accepted = record.status === 'accepted' || record.terminalState?.accepted === true || record.terminalAccepted === true;
+  const unmet = Array.isArray(record.unmet) ? record.unmet : [];
+  const blockers = Array.isArray(record.blockers) ? record.blockers : [];
+  return accepted && unmet.length === 0 && blockers.length === 0;
+}
+
+async function projectAcceptanceRecord(root, spec) {
   const configuredAcceptanceLedger = spec?.acceptanceLedger ?? spec?.ledger;
-  if (!configuredAcceptanceLedger) return false;
+  const configuredTerminalContract = spec?.terminalContract;
+  const configured = configuredAcceptanceLedger ?? configuredTerminalContract;
+  if (!configured) return null;
   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;
+    const kind = configuredAcceptanceLedger ? 'project acceptance ledger' : 'project terminal contract';
+    const file = path.resolve(root, safeRelativePath(configured, kind));
+    const record = await readJson(file);
+    return { file, record, source: configuredAcceptanceLedger ? 'acceptance_ledger' : 'terminal_contract' };
   } catch {
-    return false;
+    return null;
   }
 }
 
+async function projectTerminalAccepted(root, spec) {
+  const acceptance = await projectAcceptanceRecord(root, spec);
+  return acceptedTerminalRecord(acceptance?.record);
+}
+
 function requirementIdsFromCheckpoint(checkpoint, specs) {
   const explicit = checkpoint?.requirement_ids ?? checkpoint?.requirementIds;
   if (Array.isArray(explicit)) return [...new Set(explicit.map(String))];
@@ -1284,12 +1298,19 @@ export async function reconcileProjectGates(root, options = {}) {
       await writeJson(full, reconciled);
       if (found?.subdir === 'waiting' && task?.waitingGateId === gate.gate_id) {
         const resumeSafeBacklog = invalid.code === 'safe_backlog_actionable';
-        const destinationFile = path.join(queueSubdirFor(root, queue, resumeSafeBacklog ? 'inbox' : 'canceled'), path.basename(found.file));
-        const restored = { ...task, status: resumeSafeBacklog ? 'queued' : invalid.status, gateReconciliation: reconciled.reconciliation };
+        const projectAccepted = invalid.code === 'project_accepted_optional_deferred';
+        const destination = resumeSafeBacklog ? 'inbox' : projectAccepted ? 'done' : 'canceled';
+        const destinationFile = path.join(queueSubdirFor(root, queue, destination), path.basename(found.file));
+        const restored = {
+          ...task,
+          status: resumeSafeBacklog ? 'queued' : projectAccepted ? 'completed' : invalid.status,
+          gateReconciliation: reconciled.reconciliation
+        };
         delete restored.waitingGateId;
         delete restored.waitKind;
         delete restored.waitingSince;
-        if (!resumeSafeBacklog) restored.canceledAt = now;
+        if (projectAccepted) restored.completedAt ??= now;
+        else if (!resumeSafeBacklog) restored.canceledAt = now;
         else restored.requeuedAt = now;
         await writeJson(destinationFile, restored);
         await rm(found.file, { force: true });
@@ -1669,7 +1690,12 @@ function validateProjectSpec(spec) {
     normalizeLoopId(queue.queue);
     if (!['code', 'standard'].includes(queue.kind)) throw new Error(`Unsupported project queue kind: ${queue.kind}`);
   }
-  if (!Array.isArray(spec.backlog) || spec.backlog.length === 0) throw new Error('Project spec backlog must be non-empty.');
+  const hasEmbeddedBacklog = Array.isArray(spec.backlog) && spec.backlog.length > 0;
+  const configuredBacklogSource = spec.backlogSource ?? spec.authoritativeBacklog;
+  const hasConfiguredBacklog = typeof configuredBacklogSource === 'string' && configuredBacklogSource.trim().length > 0;
+  if (!hasEmbeddedBacklog && !hasConfiguredBacklog) {
+    throw new Error('Project spec must provide a non-empty backlog or backlogSource.');
+  }
 }
 
 export async function projectPlan(root, options = {}) {
@@ -1801,20 +1827,43 @@ export async function projectStatus(root, options = {}) {
       acceptanceLedger = { file: path.relative(root, ledgerFile), readable: false, error: error.message };
     }
   }
-  const registryItems = Array.isArray(spec.backlog) ? spec.backlog : [];
+  let terminalContract = null;
+  if (!acceptanceLedger && spec.terminalContract) {
+    const terminalFile = path.resolve(root, safeRelativePath(spec.terminalContract, 'project terminal contract'));
+    try {
+      const contract = await readJson(terminalFile);
+      terminalContract = {
+        file: path.relative(root, terminalFile),
+        status: contract.status ?? null,
+        terminalAccepted: contract.terminalState?.accepted === true,
+        updatedAt: contract.updatedAt ?? contract.terminalState?.acceptedAt ?? null,
+        unmet: Array.isArray(contract.unmet) ? contract.unmet : [],
+        blockers: Array.isArray(contract.blockers) ? contract.blockers : []
+      };
+    } catch (error) {
+      terminalContract = { file: path.relative(root, terminalFile), readable: false, error: error.message };
+    }
+  }
+  const hasEmbeddedBacklog = Array.isArray(spec.backlog) && spec.backlog.length > 0;
+  const registryItems = hasEmbeddedBacklog ? 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 } });
+  if (hasEmbeddedBacklog) {
+    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
+  const completionRecord = acceptanceLedger?.readable !== false && acceptanceLedger
+    ? acceptanceLedger
+    : terminalContract?.readable !== false ? terminalContract : null;
+  const projectCompletion = acceptedTerminalRecord(completionRecord)
     ? 'accepted'
     : 'in_progress';
   const needsAttention = [];
@@ -1824,6 +1873,7 @@ export async function projectStatus(root, options = {}) {
   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');
+  if (!acceptanceLedger && terminalContract?.readable === false) needsAttention.push('terminal_contract_unreadable');
   return {
     version: 1,
     project,
@@ -1835,13 +1885,15 @@ export async function projectStatus(root, options = {}) {
     totals,
     backlog,
     acceptanceLedger,
+    terminalContract,
     authority: {
-      terminalContract: spec.terminalContract ?? null,
+      terminalContract: terminalContract?.file ?? 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'
+      completionSource: acceptanceLedger ? 'acceptance_ledger' : terminalContract ? 'terminal_contract' : null,
+      rule: 'acceptance ledger determines project completion when configured; otherwise the terminal contract is authoritative; backlog source determines remaining work; registry is a projection validated for drift'
     },
-    consistency: { ok: drift.length === 0 && acceptanceLedger?.readable !== false, drift },
+    consistency: { ok: drift.length === 0 && acceptanceLedger?.readable !== false && terminalContract?.readable !== false, drift },
     projectCompletion,
     latestIntake,
     needsAttention,
@@ -3579,6 +3631,26 @@ function aggregateCriticStatus(baseStatus, criticReviews) {
   return 'accepted';
 }
 
+function projectCompletionStatus(value) {
+  if (typeof value === 'string') return value;
+  if (value && typeof value === 'object') return value.status ?? null;
+  return null;
+}
+
+function continuationNextAction(value) {
+  const action = String(value ?? '').trim().toLowerCase();
+  if (!action) return false;
+  return ![
+    'acceptance_review',
+    'final_judge',
+    'ready_to_apply',
+    'apply',
+    'report',
+    'complete',
+    'completed'
+  ].includes(action);
+}
+
 function buildCheckpointReview(contract, acceptancePlan, checkpoint) {
   const baseStatus = checkpointReviewStatus(checkpoint);
   const failed = [];
@@ -3701,6 +3773,8 @@ 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,
+      checkpointRisks: Array.isArray(checkpoint.risks) ? checkpoint.risks : [],
+      checkpointNextAction: checkpoint.next_action ?? null,
       deferredGates: materializableDeferredGates(checkpoint),
       status: review.status,
       file: path.relative(root, reviewFile)
@@ -3773,8 +3847,11 @@ export function buildFinalJudgement(contract, acceptancePlan, devPlan, checkpoin
   const blockedCount = effectiveReviews.filter((item) => item.status === 'blocked').length;
   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 projectCompletionAccepted = effectiveReviews.some((review) => projectCompletionStatus(review.projectCompletion) === 'accepted');
+  const projectCompletionInProgress = effectiveReviews.some((review) => projectCompletionStatus(review.projectCompletion) === 'in_progress');
+  const explicitContinuationReviews = effectiveReviews.filter((review) =>
+    (review.checkpointRisks?.length ?? 0) > 0 && continuationNextAction(review.checkpointNextAction)
+  );
   const deferredGateCount = effectiveReviews.reduce((count, review) => count + (review.deferredGates?.length ?? 0), 0);
   let outcome = 'needs_revision';
 
@@ -3826,9 +3903,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' || projectCompletionInProgress || deferredGateCount > 0) && !projectCompletionAccepted) {
+  } else if ((contract.task_scope === 'project' || projectCompletionInProgress || explicitContinuationReviews.length > 0 || deferredGateCount > 0) && !projectCompletionAccepted) {
     outcome = 'project_in_progress';
     reasons.push('The latest milestone is accepted, but the project terminal contract is not accepted.');
+    if (projectCompletionInProgress) reasons.push('The latest effective checkpoint explicitly marks project completion as in_progress.');
+    if (explicitContinuationReviews.length > 0) reasons.push(`${explicitContinuationReviews.length} accepted checkpoint(s) record unresolved risks and an explicit continuation action.`);
     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) {
@@ -3868,12 +3947,14 @@ export function buildFinalJudgement(contract, acceptancePlan, devPlan, checkpoin
       revise: reviseCount,
       blocked: blockedCount,
       deferred_gates: deferredGateCount,
+      explicit_continuations: explicitContinuationReviews.length,
       rubric_items: Array.isArray(acceptancePlan?.rubric) ? acceptancePlan.rubric.length : 0,
       automation_suggestions: Array.isArray(acceptancePlan?.automation) ? acceptancePlan.automation.length : 0
     },
     residual_risks: [
       ...(contract.requires_human_gate ? ['Human gate still required before external or high-risk action.'] : []),
-      ...(context.verificationFailed ? ['Configured verification has failing commands.'] : [])
+      ...(context.verificationFailed ? ['Configured verification has failing commands.'] : []),
+      ...explicitContinuationReviews.flatMap((review) => review.checkpointRisks ?? [])
     ],
     created_at: new Date().toISOString()
   };

package/package.json

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

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

@@ -132,6 +132,34 @@ assert.equal(inferTaskScope({ body: 'Continue the overall project with a product
   assert.equal(judgement.outcome, 'project_in_progress');
 }
 
+{
+  const devPlan = { checkpoints: [{ id: 'cp1' }] };
+  const reviews = { reviews: [{
+    checkpointId: 'cp2', milestoneId: 'cp1', sequence: 2, status: 'accepted',
+    projectCompletion: 'in_progress',
+    checkpointRisks: ['Creative/perceptual director scoring is not wired into the production inspector.'],
+    checkpointNextAction: 'wire_director_perceptual_quality_and_quote_cost_without_paid_calls'
+  }] };
+  const judgement = buildFinalJudgement(baseContract, basePlan, devPlan, { count: 2 }, reviews, { dispatchStatus: 'completed' });
+  assert.equal(judgement.outcome, 'project_in_progress');
+  assert.equal(judgement.coverage.explicit_continuations, 1);
+  assert.deepEqual(judgement.residual_risks, ['Creative/perceptual director scoring is not wired into the production inspector.']);
+  assert.match(judgement.reasons.join(' '), /explicitly marks project completion as in_progress/);
+}
+
+{
+  const devPlan = { checkpoints: [{ id: 'cp1' }] };
+  const reviews = { reviews: [{
+    checkpointId: 'cp2', milestoneId: 'cp1', sequence: 2, status: 'accepted',
+    projectCompletion: null,
+    checkpointRisks: ['A required production integration remains incomplete.'],
+    checkpointNextAction: 'implement_remaining_production_integration'
+  }] };
+  const judgement = buildFinalJudgement(baseContract, basePlan, devPlan, { count: 2 }, reviews, { dispatchStatus: 'completed' });
+  assert.equal(judgement.outcome, 'project_in_progress');
+  assert.equal(judgement.coverage.explicit_continuations, 1);
+}
+
 {
   const devPlan = { checkpoints: [{ id: 'cp1' }] };
   const reviews = { reviews: [{

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

@@ -91,6 +91,45 @@ assert.equal(drifted.authority.acceptanceLedger, 'project/acceptance-ledger.json
 assert.equal(drifted.consistency.ok, false);
 assert(drifted.needsAttention.includes('authoritative_source_drift'));
 
+// A project may keep its authoritative backlog exclusively in backlogSource.
+// Requiring a duplicate embedded backlog makes the two copies drift and used
+// to prevent project-status from reading an otherwise valid project ledger.
+await writeFile(projectFile, `${JSON.stringify({
+  ...spec,
+  backlog: undefined,
+  backlogSource: 'project/backlog.json',
+  acceptanceLedger: 'project/acceptance-ledger.json',
+  terminalContract: 'project/terminal.md'
+}, null, 2)}\n`);
+const externalOnly = await projectStatus(root, { project: 'openreel' });
+assert.equal(externalOnly.backlog.file, 'project/backlog.json');
+assert.equal(externalOnly.backlog.count, 1);
+assert.equal(externalOnly.consistency.ok, true);
+
+// When a project deliberately uses its terminal contract as the completion
+// ledger, accepted terminal bytes must project accepted status and suppress
+// optional post-completion authorization gates.
+const terminalContractFile = path.join(root, 'project', 'terminal-contract.json');
+await writeFile(terminalContractFile, `${JSON.stringify({
+  status: 'accepted', terminalState: { accepted: true }, unmet: [], blockers: []
+}, null, 2)}\n`);
+await writeFile(projectFile, `${JSON.stringify({
+  ...spec,
+  backlog: undefined,
+  backlogSource: 'project/backlog.json',
+  acceptanceLedger: undefined,
+  terminalContract: 'project/terminal-contract.json'
+}, null, 2)}\n`);
+const terminalOnly = await projectStatus(root, { project: 'openreel' });
+assert.equal(terminalOnly.projectCompletion, 'accepted');
+assert.equal(terminalOnly.authority.completionSource, 'terminal_contract');
+await writeFile(projectFile, `${JSON.stringify({
+  ...spec,
+  backlogSource: 'project/backlog.json',
+  acceptanceLedger: 'project/acceptance-ledger.json',
+  terminalContract: 'project/terminal.md'
+}, null, 2)}\n`);
+
 // 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' });
@@ -155,6 +194,23 @@ await writeFile(authoritativeLedger, `${JSON.stringify({ status: 'accepted', unm
 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 legacyTerminal = await enqueueTask(root, { queue, title: 'Legacy accepted-project gate', task: 'Project openreel terminal bookkeeping', projectId: 'openreel' });
+const legacyCheckpointDir = path.join(taskRuntimeDirFor(root, queue, legacyTerminal.task.id), 'checkpoints');
+await mkdir(legacyCheckpointDir, { recursive: true });
+await writeFile(path.join(legacyCheckpointDir, 'cp-terminal.json'), `${JSON.stringify({ checkpoint_id: 'cp-terminal', status: 'ready_for_acceptance', blockers: [] }, null, 2)}\n`);
+const legacyGateId = `${legacyTerminal.task.id}:cp-terminal`;
+const legacyGateFile = path.join(root, 'runtime', 'loops', queue, 'human-input', 'gates', `${legacyTerminal.task.id}.cp-terminal.json`);
+await writeFile(legacyGateFile, `${JSON.stringify({
+  gate_id: legacyGateId, task_id: legacyTerminal.task.id, checkpoint_id: 'cp-terminal', project_id: 'openreel',
+  requirement_ids: [], contract_hash: 'legacy', gate_kind: 'deferred_authorization', status: 'waiting_for_human'
+}, null, 2)}\n`);
+const legacyInbox = path.join(root, legacyTerminal.file);
+const legacyWaiting = path.join(root, 'runtime', 'loops', queue, 'waiting', path.basename(legacyTerminal.file));
+await writeFile(legacyWaiting, `${JSON.stringify({ ...legacyTerminal.task, status: 'waiting_for_human', waitingGateId: legacyGateId }, null, 2)}\n`);
+await rename(legacyInbox, `${legacyInbox}.moved`);
+await reconcileProjectGates(root, { queue });
+assert.equal((await queueStatus(root, queue)).done >= 1, true, 'accepted project task must close in done, not canceled');
+assert.equal(JSON.parse(await readFile(legacyGateFile, '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 });