bullswarm 0.18.0 → 0.18.1

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # bullswarm changelog
 
+## 0.18.1 — original-goal verification and denser timeline
+
+- Goal workflows now derive a durable requirement ledger from the original
+  user goal. Planner verify actions declare which requirements they cover, and
+  neither explicit nor program-level completion is accepted until every
+  requirement has a successful verifier with specific evidence. The verifier
+  receives the original goal from the runtime, so a reduced planner scope can
+  no longer silently omit requested APIs, events, tests, or documentation.
+- Successful verifier concerns are preserved in a verified
+  `completed_with_concerns` result instead of being discarded or triggering
+  unnecessary follow-up spending.
+- The human timeline calls its first accepted planner decision `plan created`,
+  later decisions `plan updated`, and the final one `completion confirmed`.
+  Execution milestones are rendered as one dense block without blank rows.
+  Finished workflows now say `No agents running · workflow finished` and
+  `Workflow finished · result ready` instead of control-plane terminology.
+
 ## 0.18.0 — exact routes, cheaper plans, clearer results
 
 - `workflow goal` can now guarantee an exact planner model and a separate exact

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bullswarm",
-  "version": "0.18.0",
+  "version": "0.18.1",
   "description": "Route work across coding-agent CLI subscriptions — paced by live quota meters, verified by content, never trusting exit codes.",
   "type": "module",
   "bin": {

package/src/workflow/dashboard.js

@@ -588,9 +588,9 @@ function workflowTimelineLines(model, width) {
   const { state, orchestrator } = model;
   const ledger = state.actionLedger ?? [];
   const events = [];
-  const add = (at, lines, sequence = Number.MAX_SAFE_INTEGER) => {
+  const add = (at, lines, sequence = Number.MAX_SAFE_INTEGER, group = null) => {
     if (!at) return;
-    events.push({ at, sequence, lines: Array.isArray(lines) ? lines : [lines] });
+    events.push({ at, sequence, group, lines: Array.isArray(lines) ? lines : [lines] });
   };
   const scout = ledger.find((action) => action.id === 'scout');
   add(state.startedAt, [
@@ -620,10 +620,17 @@ function workflowTimelineLines(model, width) {
     const decision = decisionForPlannerAttempt(state, attempt, index, orchestrator.attempts);
     const summary = decision?.reason ? sentencePreview(decision.reason, Math.max(30, width - 10))
       : decision ? decisionLabel(decision.decision) : 'No accepted decision; correction or retry turn';
+    const acceptedBefore = orchestrator.attempts.slice(0, index).filter((entry, priorIndex) =>
+      decisionForPlannerAttempt(state, entry, priorIndex, orchestrator.attempts)).length;
+    const plannerLabel = !decision
+      ? `planning retry #${index + 1}`
+      : decision.decision === 'complete'
+        ? 'completion confirmed'
+        : acceptedBefore === 0 ? 'plan created' : `plan updated #${acceptedBefore + 1}`;
     add(attempt.finishedAt, [
-      timelineRow(attempt.finishedAt, `◆ [Workflow Planner] checkpoint #${index + 1}`, durationText(attempt.startedAt, attempt.finishedAt), width),
+      timelineRow(attempt.finishedAt, `◆ [Workflow Planner] ${plannerLabel}`, durationText(attempt.startedAt, attempt.finishedAt), width),
       timelineDetail(summary, width),
-    ]);
+    ], Number.MAX_SAFE_INTEGER, 'execution');
   });
 
   const phases = new Map();
@@ -638,7 +645,7 @@ function workflowTimelineLines(model, width) {
     const startedAt = realStart ?? earliestTimestamp(actions.map((action) => actionFinishedAt(state, action)));
     if (!startedAt) continue;
     const label = phaseLabel(name, orchestrator);
-    add(startedAt, timelineRow(startedAt, `├─ [Phase: ${label}] ${realStart ? 'started' : 'blocked'}`, '', width));
+    add(startedAt, timelineRow(startedAt, `├─ [Phase: ${label}] ${realStart ? 'started' : 'blocked'}`, '', width), Number.MAX_SAFE_INTEGER, 'execution');
     const finished = actions
       .filter((action) => actionFinishedAt(state, action) && TERMINAL_ACTIONS.has(effectiveActionStatus(action, state)))
       .sort((a, b) => Date.parse(actionFinishedAt(state, a)) - Date.parse(actionFinishedAt(state, b)));
@@ -652,24 +659,24 @@ function workflowTimelineLines(model, width) {
         `${branch}${statusIcon(effectiveActionStatus(action, state))} [${label}] ${action.id}`,
         actionStarted ? durationText(actionStarted, actionFinished) : '',
         width,
-      ));
+      ), Number.MAX_SAFE_INTEGER, 'execution');
     });
     if (finished.length === actions.length && actions.length) {
       const finishedAt = latestTimestamp(actions.map((action) => actionFinishedAt(state, action)));
       const failed = actions.some((action) => String(effectiveActionStatus(action, state)).startsWith('failed'));
-      add(finishedAt, timelineRow(finishedAt, `└─${failed ? '✗' : '✓'} [Phase: ${label}] completed`, `${finished.length}/${actions.length}`, width));
+      add(finishedAt, timelineRow(finishedAt, `└─${failed ? '✗' : '✓'} [Phase: ${label}] completed`, `${finished.length}/${actions.length}`, width), Number.MAX_SAFE_INTEGER, 'execution');
     }
   }
 
   for (const event of model.events) {
     const detail = timelineControlEvent(event, width);
-    if (detail) add(event.committedAt, detail, Number(event.sequence));
+    if (detail) add(event.committedAt, detail, Number(event.sequence), event.type.startsWith('decision.') ? 'execution' : null);
   }
 
   events.sort((a, b) => Date.parse(a.at) - Date.parse(b.at) || a.sequence - b.sequence);
   const lines = [];
   events.forEach((event, index) => {
-    if (index) lines.push('');
+    if (index && (!event.group || event.group !== events[index - 1].group)) lines.push('');
     lines.push(...event.lines);
   });
   return { lines: lines.length ? lines : ['Waiting for the first durable workflow milestone'], milestoneCount: events.length };
@@ -757,13 +764,35 @@ function workflowLiveLines(model, width, spinnerFrame) {
     if (stream) lines.push(`   ${stream}`);
     lines.push('');
   }
-  if (!lines.length) lines.push(state.finishedAt ? '✓ No live agents · workflow is terminal' : '⧖ Waiting for the next dispatch');
+  if (!lines.length) lines.push(state.finishedAt
+    ? `${statusIcon(state.status)} No agents running · ${terminalWorkflowLabel(state.status)}`
+    : '⧖ Waiting for the next dispatch');
   return { lines, running, waiting };
 }
 
+function terminalWorkflowLabel(status) {
+  if (status === 'completed') return 'workflow finished';
+  if (status === 'completed_with_concerns') return 'workflow finished with concerns';
+  if (status === 'blocked') return 'workflow stopped with blockers';
+  if (status === 'failed') return 'workflow failed';
+  if (status === 'cancelled') return 'workflow cancelled';
+  if (status === 'interrupted') return 'workflow interrupted';
+  return 'workflow stopped';
+}
+
 function workflowNextLines(model, width) {
   const { state, orchestrator } = model;
-  if (state.finishedAt) return [truncate(`${statusIcon(state.status)} Workflow terminal · obtain the stable result envelope`, width)];
+  if (state.finishedAt) {
+    const next = state.status === 'completed' || state.status === 'completed_with_concerns'
+      ? 'result ready'
+      : state.status === 'blocked' ? 'review blockers and partial work'
+        : state.status === 'failed' ? 'inspect the failure before using partial work'
+          : state.status === 'cancelled' ? 'review any partial work'
+            : state.status === 'interrupted' ? 'resume the workflow or inspect partial work'
+              : 'inspect the workflow result';
+    const label = terminalWorkflowLabel(state.status);
+    return [truncate(`${statusIcon(state.status)} ${label[0].toUpperCase()}${label.slice(1)} · ${next}`, width)];
+  }
   const ledger = state.actionLedger ?? [];
   const pending = ledger.find((action) => action.id !== 'scout'
     && action.id !== orchestrator.actionId

package/src/workflow/decision.js

@@ -111,6 +111,8 @@ export function normalizeDecisionProposal(proposal) {
 
 export function validateDecisionProposal(proposal, {
   knownActionIds = [],
+  requiredRequirementIds = [],
+  completedRequirementIds = [],
   closedPhases = [],
   currentActionCount = 0,
   maxActions = 100,
@@ -161,6 +163,8 @@ export function validateDecisionProposal(proposal, {
   }
 
   const known = new Set(knownActionIds);
+  const requiredRequirements = new Set(requiredRequirementIds);
+  const completedRequirements = new Set(completedRequirementIds);
   const proposedIds = new Set(safeActions.map((action) => action?.id).filter((id) => typeof id === 'string'));
   const closed = new Set(closedPhases);
   const proposed = new Set();
@@ -261,6 +265,21 @@ export function validateDecisionProposal(proposal, {
       }
     }
     if (action.type === 'verify') {
+      if (requiredRequirements.size) {
+        if (!Array.isArray(action.covers) || action.covers.length === 0) {
+          issues.push(`${at}.covers must name one or more intent requirement IDs`);
+        } else {
+          const seen = new Set();
+          for (const requirementId of action.covers) {
+            if (typeof requirementId !== 'string' || !requiredRequirements.has(requirementId)) {
+              issues.push(`${at}.covers references unknown requirement "${requirementId}"`);
+            } else if (seen.has(requirementId)) {
+              issues.push(`${at}.covers repeats requirement "${requirementId}"`);
+            }
+            seen.add(requirementId);
+          }
+        }
+      }
       if (action.review == null && action.reviewScope === 'repository') {
         // Normalized zero-dependency audit: no artifact to review.
       } else if (typeof action.review !== 'string') {
@@ -274,6 +293,9 @@ export function validateDecisionProposal(proposal, {
         }
       }
     }
+    if (action.type !== 'verify' && action.covers != null) {
+      issues.push(`${at}.covers is only valid on verify actions`);
+    }
   }
   if (proposedItems > maxItemsPerExpansion) {
     issues.push(`proposal has ${proposedItems} fanout items, exceeding maxItemsPerExpansion=${maxItemsPerExpansion}`);
@@ -300,6 +322,15 @@ export function validateDecisionProposal(proposal, {
   };
   for (const id of proposed) visit(id);
 
+  if (requiredRequirements.size && (proposal.completion || proposal.decision === 'complete')) {
+    const covered = new Set(completedRequirements);
+    for (const action of safeActions.filter((entry) => entry?.type === 'verify')) {
+      for (const requirementId of action.covers ?? []) covered.add(requirementId);
+    }
+    const missing = [...requiredRequirements].filter((id) => !covered.has(id));
+    if (missing.length) issues.push(`completion lacks verifier coverage for ${missing.join(', ')}`);
+  }
+
   if (issues.length) throw new DecisionValidationError(issues);
   return {
     schemaVersion: DECISION_SCHEMA_VERSION,

package/src/workflow/goal.js

@@ -16,7 +16,7 @@ export const PLANNER_RULES_SECTION = [
   '5. For unknown items, create discovery ending with RETURN ONLY a JSON object containing an items array, then data-driven fan-out via itemsFrom outputs.<id>.outFile or outputs.<id>.data.<field>; the runtime extracts the list, retrying once read-only if needed.',
   '6. Put outputSchema only on a worker whose object a LATER action reads via itemsFrom or outputs.<id>.data.<field>, and tell it to RETURN ONLY the object; a prose report or any answer with fenced JSON gets no schema: the runtime parses the last {...} of the text, so a schema on prose costs a retry and a planner turn.',
   '7. Put verify.repair on every verify. ok:false means unusable: the goal\'s acceptance command fails, a deliverable is missing, or the answer is nonsense; everything else is a concern under ok:true (style, cosmetic mismatches, later-scheduled work, files other actions changed, and any process rule the goal does not state such as append-only or tests untouched). ok:false is repaired and re-checked inside the program; the repair edits only its unit\'s files and cannot rewrite the answer under review, so report a wrong claim as a concern with the true value.',
-  '8. Add completion with all-actions-ok whenever a clean program finishes the goal; when acceptance checks pass, return complete rather than adding polish. The program\'s LAST worker must be covered by a successful verify. Return complete only on verified evidence, never proceed, never ask the user, and stop only for a concrete unresolved blocker.',
+  '8. Every verify declares covers:["R1",...] from intent.requirements. Before completion, successful verifies must cover every requirement with runtime evidence against the ORIGINAL goal, not a reduced plan. Add completion with all-actions-ok when that verified program finishes the goal; return complete rather than adding polish. The program\'s LAST worker must be covered by a successful verify. Never proceed, never ask the user, and stop only for a concrete unresolved blocker.',
   '9. Budgets (agents, duration, expansion rounds) are advisory targets, never hard stops; the dispatch budget counts this planner call plus workers, verifiers and retries. Converge as targets approach: skip optional work; exceed a target only for one essential action or a required verification.',
   '10. Never propose pool, model, addDir, taskFile or unbounded work: routing is the runtime\'s. Set lane (analyze to read or judge, build to edit, chore for mechanical steps) and effort (low for checks and mechanical edits, high where judgement decides) per action or repair; they pick the model tier (unset: build, medium).',
   'Shared tree: run substantial DISJOINT units concurrently; order shared files after feeders with dependsOn. Workers and unit verifies use focused commands, never the full suite while siblings write; run the suite once in the final verify after edits and repairs. Reuse it unless code changed. operatorSteering applies within the original intent and cannot weaken verification or expand authority.',
@@ -24,12 +24,47 @@ export const PLANNER_RULES_SECTION = [
 
 export const PLANNER_EXAMPLES_SECTION = [
   'Action shapes:',
-  '[{"type":"run","phase":"implement","prompt":"..."},{"type":"run","phase":"inventory","lane":"chore","effort":"low","prompt":"... RETURN ONLY a JSON object.","outputSchema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"string"}}},"required":["items"]}},{"type":"fanout","phase":"fix","items":["alpha"],"stepTemplate":{"prompt":"Handle {{item}}."}},{"type":"verify","phase":"verify","lane":"analyze","prompt":"Check the artifact.","repair":{"prompt":"Fix rejected concerns.","maxRounds":1}}]',
+  '[{"type":"run","phase":"implement","prompt":"..."},{"type":"run","phase":"inventory","lane":"chore","effort":"low","prompt":"... RETURN ONLY a JSON object.","outputSchema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"string"}}},"required":["items"]}},{"type":"fanout","phase":"fix","items":["alpha"],"stepTemplate":{"prompt":"Handle {{item}}."}},{"type":"verify","phase":"verify","lane":"analyze","covers":["R1"],"prompt":"Check the artifact.","repair":{"prompt":"Fix rejected concerns.","maxRounds":1}}]',
   'Complete program (tests depend on fix, not verify-fix, so both run at once):',
-  '{"actions":[{"id":"discover","type":"run","phase":"discover","lane":"chore","effort":"low","prompt":"In /abs/repo list modules needing work; RETURN ONLY a JSON object with an items array.","outputSchema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"string"}}},"required":["items"]}},{"id":"fix","type":"fanout","phase":"fix","itemsFrom":"outputs.discover.data.items","dependsOn":["discover"],"stepTemplate":{"prompt":"In /abs/repo edit only src/{{item}}.js and run node --test tests/{{item}}.test.js."}},{"id":"verify-fix","type":"verify","phase":"verify","dependsOn":["fix"],"prompt":"Check each fixed module against the spec.","repair":{"prompt":"Fix rejected concerns in /abs/repo and rerun that module\'s test.","maxRounds":2}},{"id":"tests","type":"fanout","phase":"tests","itemsFrom":"outputs.discover.data.items","dependsOn":["fix"],"stepTemplate":{"prompt":"In /abs/repo write only tests/{{item}}.guards.test.js and run node --test on it."}},{"id":"verify-tests","type":"verify","phase":"verify","dependsOn":["tests"],"prompt":"Check the new tests are non-vacuous.","repair":{"prompt":"Fix rejected tests in /abs/repo.","maxRounds":1}},{"id":"verify-suite","type":"verify","phase":"verify","dependsOn":["verify-fix","verify-tests"],"effort":"low","prompt":"Run npm test in /abs/repo.","repair":{"prompt":"Fix the suite failure in /abs/repo and rerun it.","maxRounds":1}},{"id":"report","type":"run","phase":"report","lane":"chore","effort":"low","dependsOn":["verify-suite"],"prompt":"In /abs/repo list each changed file with a reason and quote the suite tail; plain markdown."},{"id":"verify-report","type":"verify","phase":"report","dependsOn":["report"],"prompt":"Check each claim against git status and a fresh suite run; a wrong number is a concern with the true value.","repair":{"prompt":"Fix any real repository defect in /abs/repo.","maxRounds":1}}],"completion":{"when":"all-actions-ok","reason":"Fix, tests, suite and report are each verified."}}',
+  '{"actions":[{"id":"discover","type":"run","phase":"discover","prompt":"In /abs/repo list modules needing work; RETURN ONLY a JSON object with an items array.","outputSchema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"string"}}},"required":["items"]}},{"id":"fix","type":"fanout","phase":"fix","itemsFrom":"outputs.discover.data.items","dependsOn":["discover"],"stepTemplate":{"prompt":"In /abs/repo edit only src/{{item}}.js and run node --test tests/{{item}}.test.js."}},{"id":"verify-fix","type":"verify","phase":"verify","covers":["R1"],"dependsOn":["fix"],"prompt":"Check each fixed module against the spec.","repair":{"prompt":"Fix rejected concerns in /abs/repo and rerun that module\'s test.","maxRounds":2}},{"id":"tests","type":"fanout","phase":"tests","itemsFrom":"outputs.discover.data.items","dependsOn":["fix"],"stepTemplate":{"prompt":"In /abs/repo write only tests/{{item}}.guards.test.js and run node --test on it."}},{"id":"verify-tests","type":"verify","phase":"verify","covers":["R1"],"dependsOn":["tests"],"prompt":"Check the new tests are non-vacuous.","repair":{"prompt":"Fix rejected tests in /abs/repo.","maxRounds":1}},{"id":"verify-suite","type":"verify","phase":"verify","covers":["R1"],"dependsOn":["verify-fix","verify-tests"],"prompt":"Run npm test in /abs/repo.","repair":{"prompt":"Fix the suite failure in /abs/repo and rerun it.","maxRounds":1}},{"id":"report","type":"run","phase":"report","dependsOn":["verify-suite"],"prompt":"In /abs/repo list each changed file with a reason and quote the suite tail; plain markdown."},{"id":"verify-report","type":"verify","phase":"report","covers":["R1"],"dependsOn":["report"],"prompt":"Check each claim against git status and a fresh suite run; a wrong number is a concern with the true value.","repair":{"prompt":"Fix any real repository defect in /abs/repo.","maxRounds":1}}],"completion":{"when":"all-actions-ok","reason":"Fix, tests, suite and report are each verified."}}',
   'Rules the validator enforces: action type is run, fanout, or verify; fanout has stepTemplate and either items or itemsFrom; verify.review, when given, is outputs.<id>.outFile; ids are unique across the whole run, finished and failed actions included; dependsOn names existing or proposed actions; lane is analyze|build|chore and effort is low|medium|high; runtime-owned fields are rejected.',
 ].join('\n');
 
+function compactRequirement(text, max = 600) {
+  const compact = String(text ?? '').replace(/\s+/g, ' ').trim();
+  return compact.length > max ? `${compact.slice(0, max - 1)}…` : compact;
+}
+
+export function extractGoalRequirements(goal) {
+  const text = String(goal ?? '').trim();
+  if (!text) return [];
+  const lines = text.split(/\r?\n/);
+  const numbered = [];
+  let current = null;
+  for (const raw of lines) {
+    const line = raw.trim();
+    const match = /^(\d+)[.)]\s+(.+)$/.exec(line);
+    if (match) {
+      if (current) numbered.push(current);
+      current = { number: match[1], text: match[2] };
+    } else if (current && line && !/^(?:finish with|before completion|acceptance(?: criteria)?|finally)\b/i.test(line)) {
+      current.text += ` ${line}`;
+    }
+  }
+  if (current) numbered.push(current);
+  const requirements = numbered.map((entry, index) => ({
+    id: `R${index + 1}`,
+    text: compactRequirement(entry.text),
+  }));
+  const finalLines = lines
+    .map((line) => line.trim())
+    .filter((line) => /^(?:finish with|before completion|acceptance(?: criteria)?|finally)\b/i.test(line));
+  if (finalLines.length) {
+    requirements.push({ id: `R${requirements.length + 1}`, text: compactRequirement(finalLines.join(' ')) });
+  }
+  return requirements.length ? requirements : [{ id: 'R1', text: compactRequirement(text) }];
+}
+
 export const AUTONOMOUS_ORCHESTRATOR_PROMPT = [
   'You are the autonomous orchestrator for the user goal in the durable workflow context.',
   'This is a control-plane decision thread. Compile the goal into a complete workflow program, own decomposition through independent verification, and use only the supplied context. Do not invoke Bullswarm, run shell commands, call tools, modify files, or ask the user to steer routine execution.',
@@ -133,6 +168,7 @@ export function buildGoalWorkflow({
     description: 'Autonomous goal-driven workflow generated by Bullswarm.',
     intent: {
       goal: goal.trim(),
+      requirements: extractGoalRequirements(goal),
       cwd: targetDir,
       autonomous: true,
       requestedOrchestrator: orchestrator ?? 'auto',

package/src/workflow/runner.js

@@ -505,7 +505,19 @@ export function verifiesWorker(verify, worker) {
     && new RegExp(`^${verify.id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}-repair-\\d+$`).test(worker.id);
 }
 
-export function completionEvidenceGaps(dynamicActions, policy, outputs = {}) {
+export function completedRequirementIds(dynamicActions, outputs = {}) {
+  const completed = new Set();
+  for (const action of dynamicActions) {
+    if (action.kind !== 'verify' || action.status !== 'succeeded' || !actionOutputOk(action, outputs)) continue;
+    for (const id of action.covers ?? []) {
+      const evidence = outputs?.[action.id]?.verify?.requirements?.[id];
+      if (evidence?.ok === true && typeof evidence.evidence === 'string' && evidence.evidence.trim()) completed.add(id);
+    }
+  }
+  return [...completed];
+}
+
+export function completionEvidenceGaps(dynamicActions, policy, outputs = {}, requirements = []) {
   const missing = [];
   const successfulWorkers = dynamicActions.filter(
     (action) => action.kind !== 'verify' && action.status === 'succeeded'
@@ -526,9 +538,20 @@ export function completionEvidenceGaps(dynamicActions, policy, outputs = {}) {
       ? `a successful verification of latest worker ${latestSuccessfulWorker.id}`
       : 'a successful verification action');
   }
+  const covered = new Set(completedRequirementIds(dynamicActions, outputs));
+  const missingRequirements = requirements.filter((entry) => !covered.has(entry.id)).map((entry) => entry.id);
+  if (missingRequirements.length) missing.push(`verified original-goal coverage for ${missingRequirements.join(', ')}`);
   return missing;
 }
 
+function successfulVerifyConcerns(dynamicActions, outputs = {}) {
+  return [...new Set(dynamicActions
+    .filter((action) => action.kind === 'verify' && action.status === 'succeeded' && actionOutputOk(action, outputs))
+    .flatMap((action) => Array.isArray(outputs?.[action.id]?.verify?.concerns)
+      ? outputs[action.id].verify.concerns.map(String) : [])
+    .filter(Boolean))];
+}
+
 function plannerCorrectionAllowance(settings) {
   const value = Number(settings?.maxPlannerCorrections);
   if (!Number.isFinite(value)) return 2;
@@ -553,6 +576,7 @@ function terminalPlannerOutcome(state, gate, reason) {
     dynamicActions,
     state.orchestration?.completionPolicy,
     state.outputs,
+    state.intent?.requirements ?? [],
   );
   for (const action of observedActions.filter((entry) => entry.kind === 'verify')) {
     const output = state.outputs?.[action.id];
@@ -964,6 +988,11 @@ async function runDecisionLoop({ runtime, gate, phase, state, retryAttempts }) {
           }
           proposal = validateDecisionProposal(normalizedProposal, {
             knownActionIds: (state.plan?.actions ?? []).map((action) => action.id),
+            requiredRequirementIds: (state.intent?.requirements ?? []).map((entry) => entry.id),
+            completedRequirementIds: completedRequirementIds(
+              (state.actionLedger ?? []).filter((action) => action.parentId === gate.id),
+              state.outputs,
+            ),
             closedPhases: (state.plan?.actions ?? [])
               .filter((action) => action.source === 'planner')
               .map((action) => action.definition?.phase)
@@ -1071,7 +1100,7 @@ async function runDecisionLoop({ runtime, gate, phase, state, retryAttempts }) {
     if (proposal.decision === 'complete') {
       const policy = state.orchestration?.completionPolicy;
       const dynamicActions = (state.actionLedger ?? []).filter((action) => action.parentId === gate.id);
-      const missing = completionEvidenceGaps(dynamicActions, policy, state.outputs);
+      const missing = completionEvidenceGaps(dynamicActions, policy, state.outputs, state.intent?.requirements ?? []);
       if (missing.length) {
         const why = `autonomous completion rejected: missing ${missing.join(' and ')}`;
         decision.accepted = false;
@@ -1081,16 +1110,18 @@ async function runDecisionLoop({ runtime, gate, phase, state, retryAttempts }) {
         runtime.persist();
         continue;
       }
+      const concerns = successfulVerifyConcerns(dynamicActions, state.outputs);
+      const terminalStatus = concerns.length ? 'completed_with_concerns' : 'completed';
       state.outcome = {
-        status: 'completed',
+        status: terminalStatus,
         verified: true,
         bestEffort: false,
         reason: proposal.reason,
-        concerns: [],
+        concerns,
         deliveryActionId: dynamicActions.filter((action) =>
           action.kind !== 'verify' && actionOutputOk(action, state.outputs)).at(-1)?.id ?? null,
       };
-      return { ok: true, why: proposal.reason, complete: true, decision: proposal };
+      return { ok: true, why: proposal.reason, complete: true, terminalStatus, decision: proposal };
     }
     if (proposal.decision === 'proceed') return { ok: true, why: proposal.reason, decision: proposal };
     if (proposal.decision === 'stop') {
@@ -1152,7 +1183,12 @@ async function runDecisionLoop({ runtime, gate, phase, state, retryAttempts }) {
         .filter((entry) => !ledgerById.has(entry.id) || !actionOutputOk(ledgerById.get(entry.id), state.outputs))
         .map((entry) => entry.id);
       const dynamicActions = (state.actionLedger ?? []).filter((action) => action.parentId === gate.id);
-      const gaps = failing.length ? [] : completionEvidenceGaps(dynamicActions, state.orchestration?.completionPolicy, state.outputs);
+      const gaps = failing.length ? [] : completionEvidenceGaps(
+        dynamicActions,
+        state.orchestration?.completionPolicy,
+        state.outputs,
+        state.intent?.requirements ?? [],
+      );
       // Pending operator steering blocks self-completion: the documented
       // contract is delivery at the next planner gate, so a clean program
       // returns to the planner (which delivers the steer) instead of
@@ -1182,19 +1218,21 @@ async function runDecisionLoop({ runtime, gate, phase, state, retryAttempts }) {
           gateId: gate.id, sequence: auto.sequence, programSequence: decision.sequence,
           actions: programActions.map((entry) => entry.id), reason,
         });
+        const concerns = successfulVerifyConcerns(dynamicActions, state.outputs);
+        const terminalStatus = concerns.length ? 'completed_with_concerns' : 'completed';
         state.outcome = {
-          status: 'completed',
+          status: terminalStatus,
           verified: true,
           bestEffort: false,
           reason,
-          concerns: [],
+          concerns,
           deliveryActionId: dynamicActions.filter((action) =>
             action.kind !== 'verify' && actionOutputOk(action, state.outputs)).at(-1)?.id ?? null,
           source: 'program-completion',
         };
         state.outputs[gate.id] = { ...state.outputs[gate.id], ok: true, why: reason, autoCompleted: true };
         runtime.persist();
-        return { ok: true, why: reason, complete: true, decision: { decision: 'complete', reason, actions: [], completion: proposal.completion } };
+        return { ok: true, why: reason, complete: true, terminalStatus, decision: { decision: 'complete', reason, actions: [], completion: proposal.completion } };
       }
       if (pendingSteering.length) {
         runtime.emit('decision.completion_deferred', {

package/src/workflow/runtime.js

@@ -56,6 +56,25 @@ export const BURST_WAIT_GRACE_MS = 10 * 60_000;
 export const BURST_WAIT_UNKNOWN_RESET_MS = 5 * 3600_000;
 export const QUOTA_POLL_MS = 60_000;
 
+export function enforceVerifyRequirementCoverage(parsed, requiredCoverage = []) {
+  if (!parsed || !requiredCoverage.length) return { parsed, concerns: [] };
+  const normalized = { ...parsed };
+  normalized.requirements = parsed.requirements && typeof parsed.requirements === 'object'
+    ? parsed.requirements : {};
+  const concerns = [];
+  for (const requirement of requiredCoverage) {
+    const evidence = normalized.requirements[requirement.id];
+    if (!evidence || evidence.ok !== true || typeof evidence.evidence !== 'string' || !evidence.evidence.trim()) {
+      concerns.push(`${requirement.id} lacks passing, specific verification evidence: ${requirement.text}`);
+    }
+  }
+  if (concerns.length) {
+    normalized.ok = false;
+    normalized.concerns = [...new Set([...(Array.isArray(parsed.concerns) ? parsed.concerns : []), ...concerns])];
+  }
+  return { parsed: normalized, concerns };
+}
+
 export function plannerBudgetContext(budget = {}) {
   const dispatchesUsedBeforePlanner = Number(budget.dispatchesUsed ?? 0);
   const rawTarget = budget.dispatchTarget ?? budget.dispatchLimit;
@@ -239,6 +258,7 @@ export class WorkflowRuntime {
         parentId: opts.itemIndex == null ? (step.parentId ?? null) : step.id,
         kind: opts.itemIndex == null ? step.type : 'run',
         dependsOn: [...(step.dependsOn ?? [])],
+        ...(step.type === 'verify' && Array.isArray(step.covers) ? { covers: [...step.covers] } : {}),
         status: 'queued',
         phase: opts.phase ?? null,
         item: opts.item,
@@ -1127,6 +1147,22 @@ export class WorkflowRuntime {
     })();
 
     const reverify = step._reverify && typeof step._reverify === 'object' ? step._reverify : null;
+    const requiredCoverage = Array.isArray(step.covers)
+      ? step.covers.map((id) => this.state.intent?.requirements?.find((entry) => entry.id === id)).filter(Boolean)
+      : [];
+    const coverageVerdictShape = requiredCoverage.length
+      ? JSON.stringify(Object.fromEntries(requiredCoverage.map((entry) => [entry.id, { ok: true, evidence: 'specific evidence' }])))
+      : null;
+    const coverageContract = requiredCoverage.length ? [
+      '',
+      'ORIGINAL USER GOAL (runtime-owned; it overrides any narrower planner or worker scope):',
+      this.state.intent?.goal ?? '(goal unavailable)',
+      '',
+      'REQUIRED COVERAGE FOR THIS VERIFIER:',
+      ...requiredCoverage.map((entry) => `- ${entry.id}: ${entry.text}`),
+      'A missing explicitly required deliverable is unusable and MUST produce ok:false.',
+      'For every ID above, include requirements.<ID> = {"ok":true|false,"evidence":"specific file, symbol, command, or observed result"}. Empty or generic evidence is invalid.',
+    ] : [];
     const reviewInstructions = [
       step.prompt ?? 'You are a skeptical reviewer. Independently inspect the work and its current repository state.',
       ...(reverify ? [
@@ -1139,9 +1175,12 @@ export class WorkflowRuntime {
       ] : []),
       '',
       'Acceptance standard (runtime-owned; it overrides any stricter rule in the instructions above): ok:false means the work is unusable: its acceptance command fails, a required deliverable is missing, or the answer is nonsense or contradicts its own evidence. Everything else goes in concerns under ok:true: style, wording, scope, cosmetic mismatches, process rules the goal never stated (append-only, diff size), and files changed by other actions that share this working tree, which are never this unit\'s defect. Never reject for something the goal does not require.',
+      ...coverageContract,
       '',
       'RETURN ONLY a single JSON object of the form',
-      '{"ok": <true|false>, "concerns": [<string>...], "summary": <string>}.',
+      requiredCoverage.length
+        ? `{"ok": <true|false>, "concerns": [<string>...], "summary": <string>, "requirements": ${coverageVerdictShape}}.`
+        : '{"ok": <true|false>, "concerns": [<string>...], "summary": <string>}.',
       'No prose and no markdown fences. Set ok by the acceptance standard above: true unless the work is unusable.',
     ].join('\n');
     // Only the reviewer INSTRUCTIONS are a template. The review target is a
@@ -1208,7 +1247,7 @@ export class WorkflowRuntime {
         taskText,
         '',
         `Your previous reply could not be used: ${parseError ?? 'it did not contain a parseable JSON object'}.`,
-        'Do the review again if needed, then RETURN ONLY the single JSON object {"ok": <true|false>, "concerns": [...], "summary": "..."} — no prose, no markdown fences, nothing before "{" or after "}".',
+        `Do the review again if needed, then RETURN ONLY the single JSON object ${requiredCoverage.length ? `{"ok":true,"concerns":[],"summary":"...","requirements":${coverageVerdictShape}}` : '{"ok": <true|false>, "concerns": [...], "summary": "..."}'} — no prose, no markdown fences, nothing before "{" or after "}".`,
       ].join('\n'), targetDir, paths, {
         escalate: this.state.settings.escalateOnFail !== false,
         retryAttempts: 0,
@@ -1222,6 +1261,7 @@ export class WorkflowRuntime {
       }
     }
 
+    ({ parsed } = enforceVerifyRequirementCoverage(parsed, requiredCoverage));
     const ok = verdict.ok && !!parsed && parsed.ok === true;
     const verifyVerdict = {
       ok,