@kontourai/flow-agents 3.11.0 → 3.12.1

package/src/cli/kit-metadata-security.test.mjs

@@ -8,6 +8,7 @@ import { createRequire, syncBuiltinESMExports } from "node:module";
 import { readKitInventory } from "../../build/src/runtime-adapters.js";
 import { main as validateHookInfluence } from "../../build/src/cli/validate-hook-influence.js";
 import { parseKitFlowStepActions, parseKitSkillRoles, validateKitRepository } from "../../build/src/flow-kit/validate.js";
+import { observeBuilderArtifactsForProgress } from "../../build/src/builder-gate-action-envelope.js";
 
 const require = createRequire(import.meta.url);
 const { workflowTriggersFor } = require("../../scripts/hooks/lib/kit-catalog.js");
@@ -70,35 +71,75 @@ test("Builder flow step actions are structured, complete, and operation-aware",
   assert.deepEqual(result.errors, []);
   assert.equal(result.entries.length, 14);
   assert.deepEqual(result.entries.find((entry) => entry.step_id === "plan")?.skills, ["plan-work"]);
+  assert.deepEqual(result.entries.filter((entry) => entry.implementation_allowed).map((entry) => `${entry.flow_id}/${entry.step_id}`), ["builder.build/execute"]);
+  assert.equal(result.entries.find((entry) => entry.step_id === "verify")?.expectation_bindings.find((binding) => binding.expectation_id === "clean-critique")?.interface, "workflow.critique");
   assert.deepEqual(result.entries.find((entry) => entry.step_id === "pr-open"), {
     flow_id: "builder.build",
     step_id: "pr-open",
     skills: [],
     operations: ["publish-change"],
-    artifacts: ["release.json"],
+    artifacts: ["publish-change.result.json"],
     expectation_ids: ["pull-request-opened"],
+    implementation_allowed: false,
+    expectation_bindings: [{ expectation_id: "pull-request-opened", interface: "operation", operation: "publish-change" }],
+    artifact_bindings: [{ artifact: "publish-change.result.json", expectation_ids: ["pull-request-opened"] }],
   });
 });
 
 test("flow step action metadata rejects malformed and duplicate entries", () => {
   const result = parseKitFlowStepActions({
     flow_step_actions: [
-      { flow_id: "builder.build", step_id: "plan", skills: ["plan-work"] },
-      { flow_id: "builder.build", step_id: "plan", skills: [] },
-      { flow_id: "builder.build", step_id: "verify", skills: "verify-work" },
-      { flow_id: "builder.build", step_id: "publish", skills: [], operations: ["publish-change"], expectation_ids: ["pull-request-opened", "pull-request-opened"] },
+      { flow_id: "builder.build", step_id: "plan", skills: ["plan-work"], implementation_allowed: false, artifacts: [], expectation_ids: [], expectation_bindings: [] },
+      { flow_id: "builder.build", step_id: "plan", skills: [], implementation_allowed: false, artifacts: [], expectation_ids: [], expectation_bindings: [] },
+      { flow_id: "builder.build", step_id: "verify", skills: "verify-work", implementation_allowed: false, artifacts: [], expectation_ids: [], expectation_bindings: [] },
+      { flow_id: "builder.build", step_id: "publish", skills: [], operations: ["publish-change"], implementation_allowed: false, artifacts: [], expectation_ids: ["pull-request-opened", "pull-request-opened"], expectation_bindings: [] },
+      { flow_id: "builder.build", step_id: "execute", skills: ["execute-plan"], implementation_allowed: true, artifacts: ["x".repeat(1025)], expectation_ids: [], expectation_bindings: [], unexpected: "ignored before #577" },
     ],
   }, "fixture/kit.json");
 
   assert.match(result.errors.join("\n"), /duplicates 'builder\.build\/plan'/);
   assert.match(result.errors.join("\n"), /skills must be an identifier list/);
-  assert.match(result.errors.join("\n"), /expectation_ids must be a unique identifier list when present/);
+  assert.match(result.errors.join("\n"), /expectation_ids must be a unique identifier list/);
+  assert.match(result.errors.join("\n"), /unsupported field\(s\): unexpected/);
+});
+
+test("flow step action metadata requires progress and policy fields", () => {
+  const base = {
+    flow_id: "builder.build",
+    step_id: "plan",
+    skills: ["plan-work"],
+    implementation_allowed: false,
+    artifacts: [],
+    expectation_ids: [],
+    expectation_bindings: [],
+  };
+  for (const field of ["expectation_ids", "artifacts", "implementation_allowed", "expectation_bindings"]) {
+    const action = { ...base };
+    delete action[field];
+    const result = parseKitFlowStepActions({ flow_step_actions: [action] }, "fixture/kit.json");
+    assert.match(result.errors.join("\n"), new RegExp(`flow_step_actions\\[0\\]\\.${field} must be explicitly declared`), field);
+  }
+});
+
+test("flow step action metadata rejects oversized action lists", () => {
+  const result = parseKitFlowStepActions({
+    flow_step_actions: [{
+      flow_id: "builder.build",
+      step_id: "plan",
+      skills: Array.from({ length: 33 }, (_, index) => `skill-${index}`),
+      implementation_allowed: false,
+      artifacts: [],
+      expectation_ids: [],
+      expectation_bindings: [],
+    }],
+  }, "fixture/kit.json");
+  assert.match(result.errors.join("\n"), /list exceeds 32 entries/);
 });
 
 test("flow step action metadata preserves explicit operation expectation ownership", () => {
   const result = parseKitFlowStepActions({
     flow_step_actions: [
-      { flow_id: "builder.build", step_id: "pr-open", skills: [], operations: ["publish-change"], expectation_ids: ["pull-request-opened"] },
+      { flow_id: "builder.build", step_id: "pr-open", skills: [], operations: ["publish-change"], implementation_allowed: false, artifacts: [], expectation_ids: ["pull-request-opened"], expectation_bindings: [{ expectation_id: "pull-request-opened", interface: "operation", operation: "publish-change" }], artifact_bindings: [] },
     ],
   }, "fixture/kit.json");
 
@@ -107,6 +148,94 @@ test("flow step action metadata preserves explicit operation expectation ownersh
   assert.deepEqual(result.entries[0]?.artifacts, []);
 });
 
+test("Builder action validation rejects expectation omissions, unsafe artifacts, and unknown operations", async () => {
+  async function errorsFor(name, mutate) {
+    const root = tempRoot(`flow-agents-action-contract-${name}-`);
+    const kit = path.join(root, "builder");
+    fs.cpSync("kits/builder", kit, { recursive: true });
+    const manifestFile = path.join(kit, "kit.json");
+    const manifest = JSON.parse(fs.readFileSync(manifestFile, "utf8"));
+    mutate(manifest);
+    writeJson(manifestFile, manifest);
+    return (await validateKitRepository(kit)).join("\n");
+  }
+
+  const omitted = await errorsFor("omitted-expectation", (manifest) => {
+    const action = manifest.flow_step_actions.find((entry) => entry.step_id === "verify");
+    action.expectation_ids = action.expectation_ids.filter((id) => id !== "policy-compliance");
+    action.expectation_bindings = action.expectation_bindings.filter((binding) => binding.expectation_id !== "policy-compliance");
+    action.artifacts = action.artifacts.filter((artifact) => artifact !== "trust.bundle#policy-compliance");
+    action.artifact_bindings = action.artifact_bindings.filter((binding) => binding.artifact !== "trust.bundle#policy-compliance");
+  });
+  assert.match(omitted, /expectation_ids must exactly equal its resolved Flow expectation set/);
+
+  const traversal = await errorsFor("artifact-traversal", (manifest) => {
+    const action = manifest.flow_step_actions.find((entry) => entry.step_id === "plan");
+    action.artifacts.push("../outside.md");
+    action.artifact_bindings.push({ artifact: "../outside.md", expectation_ids: ["implementation-plan"] });
+  });
+  assert.match(traversal, /safe session-relative paths/);
+
+  for (const [name, artifact] of [["absolute", "/tmp/outside.md"], ["fragment", "release.json#arbitrary"]]) {
+    const unsafe = await errorsFor(name, (manifest) => {
+      const action = manifest.flow_step_actions.find((entry) => entry.step_id === "pr-open");
+      action.artifacts = [artifact];
+      action.artifact_bindings = [{ artifact, expectation_ids: ["pull-request-opened"] }];
+    });
+    assert.match(unsafe, /safe session-relative paths/, name);
+  }
+
+  const typo = await errorsFor("operation-typo", (manifest) => {
+    const action = manifest.flow_step_actions.find((entry) => entry.step_id === "pr-open");
+    action.operations = ["publish-chagne"];
+    action.expectation_bindings[0].operation = "publish-chagne";
+  });
+  assert.match(typo, /canonical public operation catalog/);
+});
+
+test("artifact progress enforces deduplicated count and aggregate read budgets", (t) => {
+  const root = tempRoot("flow-agents-artifact-budget-");
+  t.after(() => fs.rmSync(root, { recursive: true, force: true }));
+  assert.throws(
+    () => observeBuilderArtifactsForProgress(root, Array.from({ length: 129 }, (_, index) => `artifact-${index}.json`)),
+    /exceeds 128 unique files/,
+  );
+  const refs = [];
+  for (let index = 0; index < 9; index += 1) {
+    const ref = `artifact-${index}.bin`;
+    fs.writeFileSync(path.join(root, ref), Buffer.alloc(1024 * 1024));
+    refs.push(ref);
+  }
+  assert.throws(() => observeBuilderArtifactsForProgress(root, refs), /exceeds 8388608 aggregate bytes/);
+});
+
+test("metadata validation matches runtime skill and run-wide observable artifact bounds", () => {
+  const tooManySkills = parseKitFlowStepActions({
+    flow_step_actions: [{
+      flow_id: "builder.build", step_id: "execute", skills: Array.from({ length: 17 }, (_, index) => `skill${index}`),
+      operations: [], implementation_allowed: true, artifacts: [], expectation_ids: [], expectation_bindings: [], artifact_bindings: [],
+    }],
+  }, "fixture/kit.json");
+  assert.match(tooManySkills.errors.join("\n"), /skills exceeds 16 entries/);
+
+  const artifacts = Array.from({ length: 129 }, (_, index) => `artifact-${index}.json`);
+  const actions = Array.from({ length: 5 }, (_, actionIndex) => {
+    const slice = artifacts.slice(actionIndex * 32, (actionIndex + 1) * 32);
+    return {
+      flow_id: "builder.build", step_id: `step${actionIndex}`, skills: [], operations: [], implementation_allowed: false,
+      artifacts: slice, expectation_ids: [], expectation_bindings: [],
+      artifact_bindings: slice.map((artifact) => ({ artifact, expectation_ids: [] })),
+    };
+  });
+  const tooManyArtifacts = parseKitFlowStepActions({ flow_step_actions: actions }, "fixture/kit.json");
+  assert.match(tooManyArtifacts.errors.join("\n"), /exceed 128 distinct observable file artifacts/);
+
+  actions[4].artifacts = ["state.json", "trust.bundle#virtual"];
+  actions[4].artifact_bindings = actions[4].artifacts.map((artifact) => ({ artifact, expectation_ids: [] }));
+  const excluded = parseKitFlowStepActions({ flow_step_actions: actions }, "fixture/kit.json");
+  assert.doesNotMatch(excluded.errors.join("\n"), /distinct observable file artifacts/);
+});
+
 test("Builder skill roles form one complete role and producer matrix", async () => {
   const manifest = JSON.parse(fs.readFileSync("kits/builder/kit.json", "utf8"));
   const result = parseKitSkillRoles(manifest, "kits/builder/kit.json");
@@ -225,7 +354,7 @@ test("operation-only composed actions must explicitly and exclusively own expect
     action.operations = ["publish-change"];
     delete action.expectation_ids;
   });
-  assert.match(missing, /operation-only action must explicitly declare expectation_ids/);
+  assert.match(missing, /expectation_ids must be explicitly declared/);
   assert.match(missing, /flow expectation 'builder\.publish-learn\/pr-open\/pull-request-opened' must have exactly one producer owner; found 0/);
 
   const duplicate = await errorsFor("duplicate", (manifest) => {
@@ -240,6 +369,30 @@ test("operation-only composed actions must explicitly and exclusively own expect
   assert.match(duplicate, /flow expectation 'builder\.publish-learn\/pr-open\/pull-request-opened' must have exactly one producer owner; found 2/);
 });
 
+test("mixed skill and operation ownership follows each expectation binding interface", async () => {
+  const root = tempRoot("flow-agents-mixed-operation-owner-");
+  const kit = path.join(root, "builder");
+  fs.cpSync("kits/builder", kit, { recursive: true });
+  const manifestFile = path.join(kit, "kit.json");
+  const manifest = JSON.parse(fs.readFileSync(manifestFile, "utf8"));
+  const action = manifest.flow_step_actions.find((entry) => entry.flow_id === "builder.build" && entry.step_id === "verify");
+  action.operations = ["publish-change"];
+  const policyBinding = action.expectation_bindings.find((entry) => entry.expectation_id === "policy-compliance");
+  policyBinding.interface = "operation";
+  policyBinding.operation = "publish-change";
+  const verifier = manifest.skill_roles.find((entry) => entry.skill_id === "builder.verify-work");
+  verifier.expectation_ids = verifier.expectation_ids.filter((id) => id !== "policy-compliance");
+  writeJson(manifestFile, manifest);
+  const valid = (await validateKitRepository(kit)).join("\n");
+  assert.doesNotMatch(valid, /verify\/policy-compliance.*producer owner/);
+
+  policyBinding.interface = "workflow.evidence";
+  delete policyBinding.operation;
+  writeJson(manifestFile, manifest);
+  const missing = (await validateKitRepository(kit)).join("\n");
+  assert.match(missing, /flow expectation 'builder\.build\/verify\/policy-compliance' must have exactly one producer owner; found 0/);
+});
+
 test("skill role cross-reference never reads Flow definitions through traversal, symlinks, or oversized files", async () => {
   async function errorsFor(name, mutate) {
     const root = tempRoot(`flow-agents-skill-role-safe-flow-${name}-`);

package/src/cli/public-contracts.ts

@@ -0,0 +1,41 @@
+export const WORKFLOW_CRITIQUE_STATUSES = ["pass", "fail", "not_verified"] as const;
+
+export const PUBLISH_CHANGE_OPERATION = "publish-change" as const;
+
+export const PUBLISH_CHANGE_OPERATION_PROTOCOL = {
+  schema_version: "1.0",
+  operation: PUBLISH_CHANGE_OPERATION,
+  kind: "provider_capability",
+  capability: "pull_request.create",
+  parameters: [
+    { name: "title", required: true, type: "string", max_length: 512 },
+    { name: "body", required: true, type: "string", max_length: 65_536 },
+    { name: "head_ref", required: true, type: "string", max_length: 255 },
+    { name: "base_ref", required: true, type: "string", max_length: 255 },
+    { name: "draft", required: false, type: "boolean" },
+  ],
+  result: {
+    required: ["provider", "repository", "number", "url", "head_ref", "base_ref"],
+    properties: {
+      provider: { type: "string", max_length: 128 },
+      repository: { type: "string", max_length: 1_024 },
+      number: { type: "integer", minimum: 1 },
+      url: { type: "string", max_length: 8_192 },
+      head_ref: { type: "string", max_length: 255 },
+      base_ref: { type: "string", max_length: 255 },
+    },
+    url_protocols: ["https:"],
+    persist_as: "publish-change.result.json",
+  },
+  availability: {
+    status: "external_capability_required",
+    executable_by_flow_agents: false,
+    completion_verification: "authenticated_change_provider_required",
+  },
+} as const;
+
+export const PUBLIC_OPERATION_CONTRACTS = {
+  [PUBLISH_CHANGE_OPERATION]: PUBLISH_CHANGE_OPERATION_PROTOCOL,
+} as const;
+
+export const PUBLIC_OPERATION_IDS = new Set<string>(Object.keys(PUBLIC_OPERATION_CONTRACTS));

package/src/cli/workflow-sidecar.ts

@@ -14,6 +14,7 @@ import { flowAgentsPackageRoot, flowAgentsPackageVersion } from "../lib/package-
 import { pinnedFlowAgentsCommand } from "../lib/pinned-cli-command.js";
 import { runObservedCommand } from "../lib/observed-command.js";
 import { captureReviewWorkspaceSnapshot, startBuilderFlowSession, syncBuilderFlowSession } from "../builder-flow-runtime.js";
+import { WORKFLOW_CRITIQUE_STATUSES } from "./public-contracts.js";
 // #291 Wave 1 Task 1.1 exports: ensure-session's ownership guard reuses the EXACT same
 // assignment ⋈ liveness join / claim / supersede logic #290 already ships for the
 // `assignment-provider` CLI, rather than reimplementing a second, parallel join (static ESM
@@ -2504,24 +2505,19 @@ function expectedGateProducer(flowId: string, stepId: string, expectationId: str
   const actions = Array.isArray(manifest.flow_step_actions) ? manifest.flow_step_actions as AnyObj[] : [];
   const action = actions.find((candidate) => candidate.flow_id === flowId && candidate.step_id === stepId);
   if (!action) die(`record-gate-claim cannot derive a producer for unknown Flow step ${flowId}/${stepId}`);
+  const binding = Array.isArray(action.expectation_bindings)
+    ? action.expectation_bindings.find((candidate): candidate is AnyObj => candidate && typeof candidate === "object" && !Array.isArray(candidate) && candidate.expectation_id === expectationId)
+    : undefined;
+  if (binding?.interface === "operation") {
+    const operation = typeof binding.operation === "string" ? binding.operation : "the declared external operation";
+    die(`record-gate-claim cannot satisfy operation-bound expectation ${expectationId}; ${operation} requires authenticated external ChangeProvider completion`);
+  }
   const skills = Array.isArray(action.skills) ? action.skills.filter((value: unknown): value is string => typeof value === "string") : [];
   const roles = Array.isArray(manifest.skill_roles) ? manifest.skill_roles as AnyObj[] : [];
   const owners = roles.filter((role) => typeof role.skill_id === "string"
     && Array.isArray(role.step_ids) && role.step_ids.includes(stepId)
     && Array.isArray(role.expectation_ids) && role.expectation_ids.includes(expectationId)
     && skills.includes(role.skill_id.replace(/^builder\./, "")));
-  if (owners.length === 0) {
-    const operations = Array.isArray(action.operations) ? action.operations.filter((value: unknown): value is string => typeof value === "string") : [];
-    const operationExpectations = Array.isArray(action.expectation_ids) ? action.expectation_ids : [];
-    if (operations.length === 1 && operationExpectations.includes(expectationId)) {
-      const artifacts = Array.isArray(action.artifacts) ? action.artifacts.filter((value: unknown): value is string => typeof value === "string") : [];
-      return {
-        id: `operation:${operations[0]}`,
-        artifactPatterns: artifacts.filter((value) => !value.includes("#")),
-        selfProducedTrustSlices: artifacts.filter((value) => value.startsWith("trust.bundle#")).map((value) => value.slice("trust.bundle#".length)),
-      };
-    }
-  }
   if (owners.length !== 1) die(`record-gate-claim cannot derive exactly one producer for ${flowId}/${stepId}/${expectationId}`);
   const owner = owners[0]!;
   const artifacts = (Array.isArray(owner.artifacts) ? owner.artifacts : []).filter((value): value is string => typeof value === "string" && value !== "ephemeral decision record");
@@ -2778,7 +2774,7 @@ function completePassingCriteria(existing: AnyObj[], raw: string[], observedComm
   });
 }
 
-const critiqueStatuses = new Set(["pass", "fail", "not_verified"]);
+const critiqueStatuses = new Set<string>(WORKFLOW_CRITIQUE_STATUSES);
 const safeCritiqueId = /^[a-z][a-z0-9_-]*$/;
 
 function normalizeCritiqueLanes(raw: string[]): AnyObj[] {

package/src/cli/workflow.ts

@@ -6,7 +6,8 @@ import { isDeepStrictEqual } from "node:util";
 import { fileURLToPath } from "node:url";
 import { validateDefinition } from "@kontourai/flow";
 import { loadBuilderFlowRun } from "../builder-flow-run-adapter.js";
-import { driveBuilderFlowSession, withContinuationDriverLock } from "../continuation-driver.js";
+import { parseKitFlowStepActions } from "../flow-kit/validate.js";
+import { MAX_CONTINUATION_TURN_RESULT_BYTES, createFileContinuationStore, driveBuilderFlowSession, withContinuationDriverLock } from "../continuation-driver.js";
 import { inspectBuilderFlowSession, recoverBuilderFlowSession, syncBuilderFlowSession } from "../builder-flow-runtime.js";
 import { flowAgentsPackageRoot, flowAgentsPackageVersion } from "../lib/package-version.js";
 import { pinnedFlowAgentsCommand } from "../lib/pinned-cli-command.js";
@@ -86,12 +87,14 @@ async function drive(sessionDir: string, argv: string[], json: boolean): Promise
   assertOrdinaryMatchingAssignmentActor(sessionDir, slug);
   const adapterCommand = loadContinuationAdapterCommand(adapterCommandFile);
   let evidenceSigner: EvidenceSigner | null = null;
-  const observedAdapterTurns: Array<Record<string, unknown>> = [];
+  let observedAdapterTurns: Array<Record<string, unknown>> = [];
   const result = await withContinuationDriverLock(sessionDir, async (lock) => {
     assertOrdinaryMatchingAssignmentActor(sessionDir, slug);
     evidenceSigner = evidenceSigningKeyFile ? consumeEvidenceSigningKey(evidenceSigningKeyFile) : null;
-    return driveBuilderFlowSession({
+    const continuationStore = createFileContinuationStore(sessionDir);
+    const outcome = await driveBuilderFlowSession({
       sessionDir,
+      store: continuationStore,
       maxTurns,
       adapterCommandIdentity: adapterCommand.identity,
       authorizeTurn: async () => { assertOrdinaryMatchingAssignmentActor(sessionDir, slug); },
@@ -119,18 +122,13 @@ async function drive(sessionDir: string, argv: string[], json: boolean): Promise
         continuationTurnSecret: context?.continuationTurnSecret,
         continuationRunId: context?.continuationRunId,
       }),
-      ...(evidenceSigningKeyFile ? { onTurnAccepted: async (request, adapterResult) => {
-        const next = [...observedAdapterTurns, {
-          request: structuredClone(request),
-          result: structuredClone(adapterResult),
-        }];
-        if (Buffer.byteLength(JSON.stringify(next), "utf8") > 1_048_576) {
-          throw new Error("continuation accepted-turn evidence must not exceed 1048576 aggregate bytes");
-        }
-        observedAdapterTurns.push(next.at(-1)!);
+      ...(evidenceSigningKeyFile ? { preflightTurn: async (request) => {
+        assertAcceptedTurnEvidenceCapacity(attestationTurns(continuationStore.acceptedTurns()), request);
       } } : {}),
       waitForBarrier: async (barrier) => waitForContinuationBarrier(barrier, { maxWaitMs: barrierWaitMs, pollMs: barrierPollMs }),
     });
+    if (evidenceSigningKeyFile) observedAdapterTurns = attestationTurns(continuationStore.acceptedTurns());
+    return outcome;
   });
   const output = evidenceSigner
     ? { ...result, evidence_attestation: signDriveEvidence(evidenceSigner, adapterCommand.identity, maxTurns, result, observedAdapterTurns) }
@@ -140,6 +138,23 @@ async function drive(sessionDir: string, argv: string[], json: boolean): Promise
   return 0;
 }
 
+function attestationTurns(turns: Array<{ request: Record<string, unknown>; result: Record<string, unknown> }>): Array<Record<string, unknown>> {
+  const covered = turns.map((turn) => ({ request: structuredClone(turn.request), result: structuredClone(turn.result) }));
+  if (Buffer.byteLength(JSON.stringify(covered), "utf8") > 1_048_576) {
+    throw new Error("continuation accepted-turn evidence must not exceed 1048576 aggregate bytes");
+  }
+  return covered;
+}
+
+export function assertAcceptedTurnEvidenceCapacity(observedTurns: Array<Record<string, unknown>>, request: Record<string, unknown>): void {
+  const base = [...observedTurns, { request: structuredClone(request), result: null }];
+  const bytesWithPlaceholder = Buffer.byteLength(JSON.stringify(base), "utf8");
+  const exactReservedBytes = bytesWithPlaceholder - Buffer.byteLength("null", "utf8") + MAX_CONTINUATION_TURN_RESULT_BYTES;
+  if (exactReservedBytes > 1_048_576) {
+    throw new Error("continuation accepted-turn evidence lacks capacity for another bounded result");
+  }
+}
+
 type EvidenceSigner = { privateKey: KeyObject; publicKeySpkiB64: string };
 
 function consumeEvidenceSigningKey(fileInput: string): EvidenceSigner {
@@ -328,6 +343,15 @@ async function evidence(sessionDir: string, argv: string[], json: boolean): Prom
   if (Object.hasOwn(parsed.flags, "command") && commands.length === 0) {
     throw new Error("workflow evidence --command requires a shell command value");
   }
+  const expectation = flagString(parsed.flags, "expectation")!;
+  // Operation-bound expectations deliberately have no generic evidence writer.
+  // Check before recovery, locking, or actor resolution so a locally authored
+  // operation result cannot cause any canonical or projection mutation.
+  const inspected = await inspectBuilderFlowSession({ sessionDir });
+  const operation = builderOperationForExpectation(inspected.run.definitionId, expectation);
+  if (operation) {
+    throw new Error(`workflow evidence cannot satisfy operation-bound expectation ${expectation}; ${operation} requires authenticated external ChangeProvider completion`);
+  }
   const requiresTestEvidence = flagString(parsed.flags, "expectation") === "tests-evidence" && flagString(parsed.flags, "status") === "pass";
   // Argument and command-shape rejection must be read-only. Recovery below may
   // repair stale projections, so it runs only after every command is accepted.
@@ -377,6 +401,18 @@ async function evidence(sessionDir: string, argv: string[], json: boolean): Prom
   return 0;
 }
 
+function builderOperationForExpectation(flowId: string, expectationId: string): string | null {
+  const kit = readJsonFile(path.join(PACKAGE_ROOT, "kits", "builder", "kit.json"), "Builder kit metadata");
+  const parsed = parseKitFlowStepActions(kit, "kits/builder/kit.json");
+  if (parsed.errors.length) throw new Error(`Builder kit metadata is invalid: ${parsed.errors.join("; ")}`);
+  for (const action of parsed.entries) {
+    if (action.flow_id !== flowId) continue;
+    const binding = action.expectation_bindings.find((candidate) => candidate.expectation_id === expectationId);
+    if (binding?.interface === "operation") return binding.operation ?? "the declared external operation";
+  }
+  return null;
+}
+
 async function critique(sessionDir: string, argv: string[], json: boolean): Promise<number> {
   const parsed = parseArgs(argv);
   assertOnlyFlags(parsed.flags, new Set(["artifact-root", "session-dir", "json", "id", "verdict", "summary", "artifact-ref", "finding-json", "lane-json", "timestamp"]), "workflow critique");