@kontourai/flow-agents 3.11.0 → 3.12.0

package/dist/pi/evals/integration/test_builder_step_producers.sh

@@ -190,6 +190,41 @@ test_produce_claim() {
     || _fail "$label: bundle missing or incorrect $expected_claim_type claim"
 }
 
+test_operation_claim_rejection() {
+  local label="$1" step="$2" expectation="$3" expected_claim_type="$4"
+  echo ""
+  echo "=== OPERATION REJECTION: $label ==="
+
+  local slug
+  slug="$(echo "operation-$step-$expectation" | tr '/' '-' | tr '.' '-')"
+  local aroot="$TMP/$slug/.kontourai/flow-agents"
+  setup_session_for_produce "$aroot" "$slug" "$step"
+  local artifact="$aroot/$slug/publish-change.result.json"
+  printf '{"provider":"fixture","repository":"acme/builder","number":1,"url":"https://example.test/acme/builder/pull/1","head_ref":"fixture","base_ref":"main"}\n' > "$artifact"
+
+  if flow_agents_node "workflow-sidecar" record-gate-claim "$aroot/$slug" \
+    --status pass \
+    --summary "Locally authored operation result must not self-complete." \
+    --expectation "$expectation" \
+    --evidence-ref-json "{\"kind\":\"artifact\",\"file\":\"$artifact\",\"summary\":\"Locally authored provider-shaped result.\"}" \
+    --timestamp "2026-06-26T00:02:00Z" >/dev/null 2>&1; then
+    _fail "$label: record-gate-claim accepted operation self-completion"
+  else
+    _pass "$label: record-gate-claim rejects operation self-completion"
+  fi
+
+  node -e "
+    const fs = require('fs');
+    const current = JSON.parse(fs.readFileSync('$aroot/current.json', 'utf8'));
+    if (current.active_step_id !== '$step') throw new Error('expected active step $step, got ' + current.active_step_id);
+    const bundleFile = '$aroot/$slug/trust.bundle';
+    const bundle = fs.existsSync(bundleFile) ? JSON.parse(fs.readFileSync(bundleFile, 'utf8')) : { claims: [] };
+    if ((bundle.claims || []).some((claim) => claim.claimType === '$expected_claim_type')) throw new Error('operation-bound claim was recorded');
+  " 2>/dev/null \
+    && _pass "$label: no operation claim is recorded and pr-open remains active" \
+    || _fail "$label: operation rejection recorded a claim or changed the active step"
+}
+
 # ─── Test: tampered bundle at given step BLOCKS ───────────────────────────────
 test_tamper_blocks() {
   local label="$1" step="$2" claim_type="$3" subject_type="$4"
@@ -376,11 +411,11 @@ test_tamper_blocks \
   "builder.design-probe.decisions" \
   "design-probe" "builder.design-probe.decisions" "decision"
 
-# Claim 4: builder.pr-open.pull-request
-test_produce_claim \
+# Claim 4: builder.pr-open.pull-request is external-only and generic claims must reject it.
+test_operation_claim_rejection \
   "builder.pr-open.pull-request" \
   "pr-open" "pull-request-opened" \
-  "builder.pr-open.pull-request" "pull-request"
+  "builder.pr-open.pull-request"
 test_tamper_blocks \
   "builder.pr-open.pull-request" \
   "pr-open" "builder.pr-open.pull-request" "pull-request"
@@ -405,17 +440,17 @@ test_tamper_blocks \
 
 # ─── Public CLI happy path + route-back ─────────────────────────────────────
 echo ""
-echo "=== PUBLIC CLI: complete canonical skill/operation path ==="
+echo "=== PUBLIC CLI: canonical skill path and external operation boundary ==="
 flow_agents_build_ts || _fail "public CLI fixture build failed"
 PUBLIC_ROOT="$TMP/public/.kontourai/flow-agents"
 PUBLIC_SESSION="$PUBLIC_ROOT/acme-builder-901"
 
 public_flow() {
-  CODEX_SESSION_ID=builder-public-producers node "$ROOT/build/src/cli.js" workflow "$@"
+  env -u CODEX_THREAD_ID CODEX_SESSION_ID=builder-public-producers node "$ROOT/build/src/cli.js" workflow "$@"
 }
 
 public_review() {
-  CODEX_SESSION_ID=builder-public-reviewer node "$ROOT/build/src/cli.js" workflow "$@"
+  env -u CODEX_THREAD_ID CODEX_SESSION_ID=builder-public-reviewer node "$ROOT/build/src/cli.js" workflow "$@"
 }
 
 assert_public_step() {
@@ -578,25 +613,29 @@ else
 fi
 assert_public_step "merge-ready" "evidence-gate" ""
 record_public_expectation "merge-readiness"
-assert_public_step "pr-open" "" "publish-change"
-record_public_expectation "pull-request-opened"
-assert_public_step "merge-ready-ci" "release-readiness" ""
-record_public_expectation "ci-merge-readiness"
-assert_public_step "learn" "learning-review" ""
-record_public_expectation "decision-evidence"
-assert_public_step "learn" "learning-review" "" "active-or-blocked"
-record_public_expectation "learning-evidence"
-if node - "$PUBLIC_SESSION/trust.bundle" <<'NODE'
-const fs = require('node:fs');
-const bundle = JSON.parse(fs.readFileSync(process.argv[2], 'utf8'));
-if (!bundle.claims.some((claim) => claim.claimType === 'builder.learn.evidence' && claim.subjectType === 'release' && claim.status === 'verified')) process.exit(1);
+assert_public_step "pr-open" "" "publish-change" "active-or-blocked"
+PUBLIC_PR_OPEN_REPORT="$(public_flow status --session-dir "$PUBLIC_SESSION" --json 2>/dev/null)"
+if node - "$PUBLIC_PR_OPEN_REPORT" <<'NODE'
+const report = JSON.parse(process.argv[2]);
+const capability = report.next_action?.external_capability;
+if (report.current_step !== 'pr-open' || report.next_action?.status !== 'blocked') process.exit(1);
+if (capability?.operation !== 'publish-change' || capability?.completion !== 'external_verification_required') process.exit(2);
 NODE
 then
-  _pass "learning-review records verified learning.json evidence"
+  _pass "pr-open projects the external publish-change capability block"
+else
+  _fail "pr-open did not expose the required external capability block: $PUBLIC_PR_OPEN_REPORT"
+fi
+node - "$PUBLIC_SESSION/publish-change.result.json" <<'NODE'
+const fs = require('node:fs');
+fs.writeFileSync(process.argv[2], JSON.stringify({ provider: 'fixture', repository: 'acme/builder', number: 901, url: 'https://example.test/acme/builder/pull/901', head_ref: 'fixture', base_ref: 'main' }));
+NODE
+if public_flow evidence --session-dir "$PUBLIC_SESSION" --expectation pull-request-opened --status pass --summary "Locally authored result must not self-complete publish-change." --evidence-ref-json "{\"kind\":\"artifact\",\"file\":\".kontourai/flow-agents/$(basename "$PUBLIC_SESSION")/publish-change.result.json\",\"summary\":\"Locally authored provider-shaped result.\"}" >/dev/null 2>&1; then
+  _fail "generic workflow evidence accepted operation self-completion"
 else
-  _fail "learning-review did not record durable learning.json evidence in trust.bundle"
+  _pass "generic workflow evidence rejects operation self-completion"
 fi
-assert_public_step "learn" "" "" "completed"
+assert_public_step "pr-open" "" "publish-change" "active-or-blocked"
 
 echo ""
 echo "=== PUBLIC CLI: failed verify route-back remains canonical ==="

package/dist/pi/evals/integration/test_bundle_install.sh

@@ -1061,18 +1061,6 @@ NODE
   package_flow evidence --session-dir "$PACKAGE_SESSION" --expectation merge-readiness --status pass \
     --summary "Packed fixture records the declared merge-readiness artifact." \
     --evidence-ref-json "{\"kind\":\"artifact\",\"file\":\"$PACKAGE_SESSION/acme-builder-901--evidence-gate.md\",\"summary\":\"Durable merge-readiness artifact.\"}" >/dev/null \
-  && package_flow evidence --session-dir "$PACKAGE_SESSION" --expectation pull-request-opened --status pass \
-    --summary "Packed fixture records the declared release artifact." \
-    --evidence-ref-json "{\"kind\":\"artifact\",\"file\":\"$PACKAGE_SESSION/release.json\",\"summary\":\"Durable release artifact.\"}" >/dev/null \
-  && package_flow evidence --session-dir "$PACKAGE_SESSION" --expectation ci-merge-readiness --status pass \
-    --summary "Packed fixture records the declared CI readiness artifact." \
-    --evidence-ref-json "{\"kind\":\"artifact\",\"file\":\"$PACKAGE_SESSION/release.json\",\"summary\":\"Durable CI readiness artifact.\"}" >/dev/null \
-  && package_flow evidence --session-dir "$PACKAGE_SESSION" --expectation decision-evidence --status pass \
-    --summary "Packed fixture records the declared learning decision artifact." \
-    --evidence-ref-json "{\"kind\":\"artifact\",\"file\":\"$PACKAGE_SESSION/learning.json\",\"summary\":\"Durable learning decision artifact.\"}" >/dev/null \
-  && package_flow evidence --session-dir "$PACKAGE_SESSION" --expectation learning-evidence --status pass \
-    --summary "Packed fixture records the declared learning evidence artifact." \
-    --evidence-ref-json "{\"kind\":\"artifact\",\"file\":\"$PACKAGE_SESSION/learning.json\",\"summary\":\"Durable learning evidence artifact.\"}" >/dev/null \
   && node - "$PACKAGE_SESSION" <<'NODE' &&
 const fs = require('node:fs');
 const path = require('node:path');
@@ -1087,14 +1075,26 @@ const requiredTypes = [
   'builder.execute.scope',
   'builder.verify.tests',
   'builder.merge-ready.readiness',
-  'builder.learn.decisions',
-  'builder.learn.evidence',
 ];
 const missingTypes = requiredTypes.filter((type) => !types.has(type));
 if (missingTypes.length > 0) {
-  console.error(`missing verified public workflow claims: ${missingTypes.join(', ')}`);
+  console.error(`missing verified pre-operation workflow claims: ${missingTypes.join(', ')}`);
   process.exit(1);
 }
+fs.writeFileSync(path.join(session, 'publish-change.result.json'), JSON.stringify({ provider: 'fixture', repository: 'acme/builder', number: 901, url: 'https://example.test/acme/builder/pull/901', head_ref: 'fixture', base_ref: 'main' }));
+NODE
+  ! package_flow evidence --session-dir "$PACKAGE_SESSION" --expectation pull-request-opened --status pass \
+    --summary "Locally authored publish-change result must not self-complete." \
+    --evidence-ref-json "{\"kind\":\"artifact\",\"file\":\"$PACKAGE_SESSION/publish-change.result.json\",\"summary\":\"Locally authored provider-shaped result.\"}" >/dev/null 2>&1 \
+  && node - "$PACKAGE_SESSION" "$PACKAGE_PROJECT" <<'NODE' &&
+const fs = require('node:fs');
+const path = require('node:path');
+const [session, project] = process.argv.slice(2);
+const state = JSON.parse(fs.readFileSync(path.join(session, 'state.json'), 'utf8'));
+const flow = JSON.parse(fs.readFileSync(path.join(project, '.kontourai', 'flow', 'runs', path.basename(session), 'state.json'), 'utf8'));
+const bundle = JSON.parse(fs.readFileSync(path.join(session, 'trust.bundle'), 'utf8'));
+if (state.flow_run?.current_step !== 'pr-open' || flow.current_step !== 'pr-open' || state.next_action?.status !== 'blocked') process.exit(1);
+if ((bundle.claims || []).some((claim) => claim.claimType === 'builder.pr-open.pull-request')) process.exit(2);
 NODE
   printf 'Selected Work Item: acme/builder#902\n' > "$PACKAGE_LIFECYCLE_SESSION/acme-builder-902--pull-work.md" \
   && package_flow start --artifact-root "$PACKAGE_PROJECT/.kontourai/flow-agents" \

package/dist/pi/evals/integration/test_phase_map_and_gate_claim.sh

@@ -206,7 +206,7 @@ node -e "
   || _fail "bundle missing selected-work claim or declared durable artifact evidence"
 
 echo ""
-echo "=== 4b. composed publish-learn gate claim emits builder.pr-open.pull-request ==="
+echo "=== 4b. composed publish-learn operation cannot self-complete through record-gate-claim ==="
 
 COMPOSED_ROOT="$TMP/composed-gate-claim-project/.kontourai/flow-agents"
 mkdir -p "$COMPOSED_ROOT"
@@ -237,9 +237,9 @@ if flow_agents_node "workflow-sidecar" record-gate-claim "$COMPOSED_ROOT/compose
   --expectation pull-request-opened \
   --evidence-ref-json "{\"kind\":\"artifact\",\"file\":\"$COMPOSED_ARTIFACT\",\"summary\":\"Declared durable release artifact for pull-request-opened.\"}" \
   --timestamp "2026-06-26T00:01:00Z" >/dev/null 2>&1; then
-  _pass "record-gate-claim exits 0 at composed pr-open step"
+  _fail "record-gate-claim accepted composed operation self-completion"
 else
-  _fail "record-gate-claim failed at composed pr-open step"
+  _pass "record-gate-claim rejects composed operation self-completion"
 fi
 
 node -e "
@@ -247,32 +247,19 @@ node -e "
   const current = JSON.parse(fs.readFileSync('$COMPOSED_ROOT/current.json', 'utf8'));
   if (current.active_flow_id !== 'builder.build') throw new Error('expected active_flow_id=builder.build, got ' + current.active_flow_id);
   if (current.active_step_id !== 'pr-open') throw new Error('expected active_step_id=pr-open, got ' + current.active_step_id);
-  const bundle = JSON.parse(fs.readFileSync('$COMPOSED_ROOT/composed-gate-claim/trust.bundle', 'utf8'));
-  const target = (bundle.claims || []).find(c => c.claimType === 'builder.pr-open.pull-request');
-  if (!target) {
-    console.error('no builder.pr-open.pull-request claim found; claims:', (bundle.claims||[]).map(c=>c.claimType).join(', '));
-    process.exit(1);
-  }
-  if (target.subjectType !== 'pull-request') {
-    console.error('expected subjectType=pull-request, got', target.subjectType);
-    process.exit(1);
-  }
-  if (target.status !== 'verified') {
-    console.error('expected status=verified, got', target.status);
+  const bundleFile = '$COMPOSED_ROOT/composed-gate-claim/trust.bundle';
+  const bundle = fs.existsSync(bundleFile) ? JSON.parse(fs.readFileSync(bundleFile, 'utf8')) : { claims: [] };
+  if ((bundle.claims || []).some(c => c.claimType === 'builder.pr-open.pull-request')) {
+    console.error('operation-bound claim was recorded despite generic producer rejection');
     process.exit(1);
   }
-  const expectedArtifact = '.kontourai/flow-agents/composed-gate-claim/release.json';
   if (!fs.existsSync('$COMPOSED_ARTIFACT')) {
     console.error('missing declared durable pr-open artifact:', '$COMPOSED_ARTIFACT');
     process.exit(1);
   }
-  if (!target.metadata?.artifact_refs?.some(ref => ref.kind === 'artifact' && ref.file === expectedArtifact)) {
-    console.error('pr-open claim does not cite declared artifact:', JSON.stringify(target.metadata?.artifact_refs));
-    process.exit(1);
-  }
 " 2>/dev/null \
-  && _pass "composed bundle contains builder.pr-open.pull-request with declared durable artifact evidence" \
-  || _fail "composed bundle missing pr-open claim or declared durable artifact evidence"
+  && _pass "composed operation rejection leaves pr-open active with no claim or advancement" \
+  || _fail "composed operation rejection changed pr-open state or recorded a claim"
 
 # ─── Tamper-blocks: stored verified + evidence fail → BLOCK (exit 2) ─────────
 echo ""

package/dist/pi/install.sh

@@ -72,7 +72,7 @@ if [[ ! -e "$DEST/AGENTS.md" && ! -L "$DEST/AGENTS.md" ]]; then
   rm -f "$instruction_tmp"
 fi
 if command -v node >/dev/null 2>&1; then
-  node "$DEST/scripts/install-merge.js" --stamp-only --version "3.11.0" --install-record "$DEST/.flow-agents/install.json" --runtime "pi" || true
+  node "$DEST/scripts/install-merge.js" --stamp-only --version "3.12.0" --install-record "$DEST/.flow-agents/install.json" --runtime "pi" || true
 fi
 if [[ ${#CONSOLE_CONFIG_ARGS[@]} -gt 0 || -n "${FLOW_AGENTS_TELEMETRY_SINK:-}" || -n "${FLOW_AGENTS_TELEMETRY_SINKS:-}" || -n "${FLOW_AGENTS_CONSOLE_URL:-}" || -n "${CONSOLE_TELEMETRY_URL:-}" || -n "${CONSOLE_URL:-}" || -n "${FLOW_AGENTS_CONSOLE_TOKEN_FILE:-}" || -n "${CONSOLE_TELEMETRY_TOKEN_FILE:-}" ]]; then
   bash "$DEST/scripts/telemetry/install-console-config.sh" "$DEST/scripts/telemetry/telemetry.conf" "${CONSOLE_CONFIG_ARGS[@]}"

package/dist/pi/kits/builder/kit.json

@@ -49,87 +49,161 @@
       "flow_id": "builder.build",
       "step_id": "pull-work",
       "skills": ["pull-work"],
-      "expectation_ids": ["selected-work"]
+      "implementation_allowed": false,
+      "artifacts": ["<slug>--pull-work.md", "trust.bundle#selected-work"],
+      "expectation_ids": ["selected-work"],
+      "expectation_bindings": [{ "expectation_id": "selected-work", "interface": "workflow.evidence" }],
+      "artifact_bindings": [{ "artifact": "<slug>--pull-work.md", "expectation_ids": ["selected-work"] }, { "artifact": "trust.bundle#selected-work", "expectation_ids": ["selected-work"] }]
     },
     {
       "flow_id": "builder.build",
       "step_id": "design-probe",
       "skills": ["pickup-probe"],
-      "expectation_ids": ["pickup-probe-readiness", "probe-decisions-or-accepted-gaps"]
+      "implementation_allowed": false,
+      "artifacts": ["<slug>--pull-work.md", "trust.bundle#pickup-probe"],
+      "expectation_ids": ["pickup-probe-readiness", "probe-decisions-or-accepted-gaps"],
+      "expectation_bindings": [
+        { "expectation_id": "pickup-probe-readiness", "interface": "workflow.evidence" },
+        { "expectation_id": "probe-decisions-or-accepted-gaps", "interface": "workflow.evidence" }
+      ],
+      "artifact_bindings": [{ "artifact": "<slug>--pull-work.md", "expectation_ids": ["pickup-probe-readiness", "probe-decisions-or-accepted-gaps"] }, { "artifact": "trust.bundle#pickup-probe", "expectation_ids": ["pickup-probe-readiness", "probe-decisions-or-accepted-gaps"] }]
     },
     {
       "flow_id": "builder.build",
       "step_id": "plan",
       "skills": ["plan-work"],
-      "expectation_ids": ["implementation-plan"]
+      "implementation_allowed": false,
+      "artifacts": ["<slug>--plan-work.md", "acceptance.json", "handoff.json", "trust.bundle#implementation-plan"],
+      "expectation_ids": ["implementation-plan"],
+      "expectation_bindings": [{ "expectation_id": "implementation-plan", "interface": "workflow.evidence" }],
+      "artifact_bindings": [{ "artifact": "<slug>--plan-work.md", "expectation_ids": ["implementation-plan"] }, { "artifact": "acceptance.json", "expectation_ids": ["implementation-plan"] }, { "artifact": "handoff.json", "expectation_ids": ["implementation-plan"] }, { "artifact": "trust.bundle#implementation-plan", "expectation_ids": ["implementation-plan"] }]
     },
     {
       "flow_id": "builder.build",
       "step_id": "execute",
       "skills": ["execute-plan"],
-      "expectation_ids": ["implementation-scope"]
+      "implementation_allowed": true,
+      "artifacts": ["<slug>--deliver.md", "state.json", "trust.bundle#implementation-scope"],
+      "expectation_ids": ["implementation-scope"],
+      "expectation_bindings": [{ "expectation_id": "implementation-scope", "interface": "workflow.evidence" }],
+      "artifact_bindings": [{ "artifact": "<slug>--deliver.md", "expectation_ids": ["implementation-scope"] }, { "artifact": "state.json", "expectation_ids": [] }, { "artifact": "trust.bundle#implementation-scope", "expectation_ids": ["implementation-scope"] }]
     },
     {
       "flow_id": "builder.build",
       "step_id": "verify",
       "skills": ["review-work", "verify-work"],
-      "expectation_ids": ["clean-critique", "acceptance-criteria", "tests-evidence", "policy-compliance"]
+      "implementation_allowed": false,
+      "artifacts": ["trust.bundle#critique", "trust.bundle#acceptance-criteria", "trust.bundle#tests-evidence", "trust.bundle#policy-compliance"],
+      "expectation_ids": ["clean-critique", "acceptance-criteria", "tests-evidence", "policy-compliance"],
+      "expectation_bindings": [
+        { "expectation_id": "clean-critique", "interface": "workflow.critique" },
+        { "expectation_id": "acceptance-criteria", "interface": "workflow.evidence" },
+        { "expectation_id": "tests-evidence", "interface": "workflow.evidence" },
+        { "expectation_id": "policy-compliance", "interface": "workflow.evidence" }
+      ],
+      "artifact_bindings": [{ "artifact": "trust.bundle#critique", "expectation_ids": ["clean-critique"] }, { "artifact": "trust.bundle#acceptance-criteria", "expectation_ids": ["acceptance-criteria"] }, { "artifact": "trust.bundle#tests-evidence", "expectation_ids": ["tests-evidence"] }, { "artifact": "trust.bundle#policy-compliance", "expectation_ids": ["policy-compliance"] }]
     },
     {
       "flow_id": "builder.build",
       "step_id": "merge-ready",
       "skills": ["evidence-gate"],
-      "expectation_ids": ["merge-readiness"]
+      "implementation_allowed": false,
+      "artifacts": ["<slug>--evidence-gate.md", "trust.bundle#merge-readiness"],
+      "expectation_ids": ["merge-readiness"],
+      "expectation_bindings": [{ "expectation_id": "merge-readiness", "interface": "workflow.evidence" }],
+      "artifact_bindings": [{ "artifact": "<slug>--evidence-gate.md", "expectation_ids": ["merge-readiness"] }, { "artifact": "trust.bundle#merge-readiness", "expectation_ids": ["merge-readiness"] }]
     },
     {
       "flow_id": "builder.build",
       "step_id": "pr-open",
       "skills": [],
       "operations": ["publish-change"],
+      "implementation_allowed": false,
       "expectation_ids": ["pull-request-opened"],
-      "artifacts": ["release.json"]
+      "artifacts": ["publish-change.result.json"],
+      "expectation_bindings": [{ "expectation_id": "pull-request-opened", "interface": "operation", "operation": "publish-change" }],
+      "artifact_bindings": [{ "artifact": "publish-change.result.json", "expectation_ids": ["pull-request-opened"] }]
     },
     {
       "flow_id": "builder.build",
       "step_id": "merge-ready-ci",
       "skills": ["release-readiness"],
-      "expectation_ids": ["ci-merge-readiness"]
+      "implementation_allowed": false,
+      "artifacts": ["release.json", "trust.bundle#ci-merge-readiness"],
+      "expectation_ids": ["ci-merge-readiness"],
+      "expectation_bindings": [{ "expectation_id": "ci-merge-readiness", "interface": "workflow.evidence" }],
+      "artifact_bindings": [{ "artifact": "release.json", "expectation_ids": ["ci-merge-readiness"] }, { "artifact": "trust.bundle#ci-merge-readiness", "expectation_ids": ["ci-merge-readiness"] }]
     },
     {
       "flow_id": "builder.build",
       "step_id": "learn",
       "skills": ["learning-review"],
-      "expectation_ids": ["decision-evidence", "learning-evidence"]
+      "implementation_allowed": false,
+      "artifacts": ["learning.json", "trust.bundle#decision-evidence", "trust.bundle#learning-evidence"],
+      "expectation_ids": ["decision-evidence", "learning-evidence"],
+      "expectation_bindings": [
+        { "expectation_id": "decision-evidence", "interface": "workflow.evidence" },
+        { "expectation_id": "learning-evidence", "interface": "workflow.evidence" }
+      ],
+      "artifact_bindings": [{ "artifact": "learning.json", "expectation_ids": ["decision-evidence", "learning-evidence"] }, { "artifact": "trust.bundle#decision-evidence", "expectation_ids": ["decision-evidence"] }, { "artifact": "trust.bundle#learning-evidence", "expectation_ids": ["learning-evidence"] }]
     },
     {
       "flow_id": "builder.build",
       "step_id": "done",
       "skills": [],
-      "expectation_ids": []
+      "implementation_allowed": false,
+      "artifacts": [],
+      "expectation_ids": [],
+      "expectation_bindings": [],
+      "artifact_bindings": []
     },
     {
       "flow_id": "builder.shape",
       "step_id": "shape",
       "skills": ["idea-to-backlog"],
-      "expectation_ids": ["shaped-problem", "shaped-outcome", "shaped-constraints", "shaped-non-goals", "shaped-success", "shaped-risk", "open-decisions"]
+      "implementation_allowed": false,
+      "artifacts": ["<slug>--idea-to-backlog.md", "trust.bundle#builder.shape"],
+      "expectation_ids": ["shaped-problem", "shaped-outcome", "shaped-constraints", "shaped-non-goals", "shaped-success", "shaped-risk", "open-decisions"],
+      "expectation_bindings": [
+        { "expectation_id": "shaped-problem", "interface": "workflow.evidence" },
+        { "expectation_id": "shaped-outcome", "interface": "workflow.evidence" },
+        { "expectation_id": "shaped-constraints", "interface": "workflow.evidence" },
+        { "expectation_id": "shaped-non-goals", "interface": "workflow.evidence" },
+        { "expectation_id": "shaped-success", "interface": "workflow.evidence" },
+        { "expectation_id": "shaped-risk", "interface": "workflow.evidence" },
+        { "expectation_id": "open-decisions", "interface": "workflow.evidence" }
+      ],
+      "artifact_bindings": [{ "artifact": "<slug>--idea-to-backlog.md", "expectation_ids": ["shaped-problem", "shaped-outcome", "shaped-constraints", "shaped-non-goals", "shaped-success", "shaped-risk", "open-decisions"] }, { "artifact": "trust.bundle#builder.shape", "expectation_ids": ["shaped-problem", "shaped-outcome", "shaped-constraints", "shaped-non-goals", "shaped-success", "shaped-risk", "open-decisions"] }]
     },
     {
       "flow_id": "builder.shape",
       "step_id": "breakdown",
       "skills": ["idea-to-backlog"],
-      "expectation_ids": ["slices-defined"]
+      "implementation_allowed": false,
+      "artifacts": ["<slug>--idea-to-backlog.md", "trust.bundle#builder.shape"],
+      "expectation_ids": ["slices-defined"],
+      "expectation_bindings": [{ "expectation_id": "slices-defined", "interface": "workflow.evidence" }],
+      "artifact_bindings": [{ "artifact": "<slug>--idea-to-backlog.md", "expectation_ids": ["slices-defined"] }, { "artifact": "trust.bundle#builder.shape", "expectation_ids": ["slices-defined"] }]
     },
     {
       "flow_id": "builder.shape",
       "step_id": "file-issues",
       "skills": ["idea-to-backlog"],
-      "expectation_ids": ["work-items-filed"]
+      "implementation_allowed": false,
+      "artifacts": ["<slug>--idea-to-backlog.md", "trust.bundle#builder.shape"],
+      "expectation_ids": ["work-items-filed"],
+      "expectation_bindings": [{ "expectation_id": "work-items-filed", "interface": "workflow.evidence" }],
+      "artifact_bindings": [{ "artifact": "<slug>--idea-to-backlog.md", "expectation_ids": ["work-items-filed"] }, { "artifact": "trust.bundle#builder.shape", "expectation_ids": ["work-items-filed"] }]
     },
     {
       "flow_id": "builder.shape",
       "step_id": "shape-done",
       "skills": [],
-      "expectation_ids": []
+      "implementation_allowed": false,
+      "artifacts": [],
+      "expectation_ids": [],
+      "expectation_bindings": [],
+      "artifact_bindings": []
     }
   ],
   "hook_influence_expectations": [

package/docs/public-workflow-cli.md

@@ -90,9 +90,10 @@ Critique derives reviewer identity from the calling runtime actor. An active
 implementation assignment is required, and its actor cannot review its own
 work; the delegated reviewer invokes the command directly under a distinct
 identity. The public interface does not accept a caller-selected reviewer
-label. Every critique includes an explicit verdict, at least one substantive
-`--lane-json`, and local reviewed `--artifact-ref` values. Passing critiques
-require every lane to pass; reviewed files and the workspace snapshot are
+label. Every critique includes an explicit `pass`, `fail`, or `not_verified`
+verdict and at least one substantive `--lane-json`. Passing critiques additionally
+require local reviewed `--artifact-ref` values and every lane to pass; reviewed
+files and the workspace snapshot are
 hashed into the stored review target so later implementation changes invalidate
 stale clean critiques.
 
@@ -173,7 +174,13 @@ flow_agents workflow drive \
 Driver state and its append-only event stream live under
 `.kontourai/flow-agents/<slug>/continuation-driver/`. The mission turn count survives reinvocation;
 subsequent invocations must use the same `--max-turns` value. The request contains the
-canonical run id, definition id, current step, projected `next_action`, iteration, and budget. It
+canonical run id, definition id, current step, projected `next_action`, iteration, and budget. Builder
+turns additionally carry one bounded top-level `gate_action_envelope` with immutable skill identities,
+declared artifacts/evidence, requirement satisfaction and unresolved ids, typed public
+`workflow.evidence`/`workflow.critique` argv or product-operation bindings, one-turn stop semantics,
+product-declared implementation policy, and prior canonical progress/stagnation. Parameter values are
+appended as separate argv entries; adapters must not perform string substitution into a shell command. The
+envelope is request-only and is not duplicated in projected `next_action` or durable `state.json`. It
 does not mutate or replace the runtime system prompt. Adapter errors are recorded as failed turns
 and fail open to canonical resynchronization and the next bounded turn; they cannot bypass the
 persisted mission budget. The Builder Flow projection supplies the canonical continue/wait/done/failed
@@ -188,6 +195,15 @@ state rollback or deletion is rejected when its append-only event history proves
 started. These local coordination records detect accidental or in-process rollback; they are not a
 cryptographic boundary against a process that can rewrite the entire artifact directory.
 
+An operation mutation is a structured product protocol, not necessarily a directly executable CLI
+command. In particular, `publish-change` identifies the provider capability `pull_request.create`,
+its bounded parameters, the required provider result, and `publish-change.result.json` as its dedicated
+result artifact. This release has no authenticated ChangeProvider executor. The operation therefore
+reports `external_capability_required` and `external_verification_required`, exposes no completion
+mutation, and parks the continuation. A locally authored result is not provider evidence. The installed
+`flow-agents publish-change` helper renders and validates publish artifacts and provider checks; it does
+not create a pull request and must not be treated as the operation executor.
+
 Immediately before spawning an adapter turn, the driver writes a transient, schema-versioned
 `active-turn.json` beside its mission state and passes a raw 32-byte turn secret plus the path-safe,
 signed run id in `FLOW_AGENTS_CONTINUATION_TURN_SECRET` and
@@ -230,7 +246,27 @@ The event stream records `turn_completed`, `gate_not_advanced`, `turn_failed`, a
 outcome. Failed turns carry
 `failure_kind` of `timeout` or `adapter_error`; a completed adapter turn whose canonical run remains
 active at the same current step records `gate_not_advanced`. These events describe driver execution only and do not
-change canonical Flow state.
+change canonical Flow state. Adapter-returned `evidence` is not interpreted as gate evidence; only
+the public `workflow evidence` path can attach evidence for Flow evaluation. Same-step canonical
+evidence or declared-artifact hash changes are recorded as progress, while repeated no-progress turns are
+classified as possible stagnation and then stagnant without fabricating a gate outcome.
+Progress uses run-wide canonical evidence/artifact manifests and resumes
+from the durable `last_progress` baseline after interruption or reinvocation. Kit metadata, skill source,
+and observed artifact reads are bounded descriptor-stable regular-file reads that reject symlinks and
+identity changes.
+Request-facing declared and required artifacts exclude control `state.json`, even where legacy kit
+ownership metadata retains it.
+Kit validation and envelope construction both cap an action at 16 skills and a flow at 128 distinct
+observable file artifacts, excluding virtual trust-bundle refs and control artifacts consistently.
+Synchronization measures an interrupted, waiting, terminal, or callback-failed turn before clearing
+its recovery marker. Evidence-free canonical gate evaluation is limited to accepted exceptions and
+gates whose effective expectations are all optional; ordinary missing-required gates remain unevaluated.
+Signed drives reserve aggregate attestation capacity before adapter execution when another bounded
+signed result cannot fit.
+The complete serialized adapter result is capped at 74,000 bytes, and preflight reserves that exact
+maximum plus the actual request and JSON structure. Accepted request/result pairs and measured progress
+are journaled durably before the active marker is cleared. Restart idempotently completes missing audit
+writes, and signed attestation fails closed when persisted accepted events lack journal coverage.
 
 ## Compatibility Doctor
 

package/docs/spec/builder-flow-runtime.md

@@ -153,6 +153,123 @@ composed steps that have no legacy sidecar phase (`merge-ready-ci` and `learn`).
 Both the legacy `current.json` pointer and every matching per-actor pointer are
 updated from that canonical step; `phase_map` is presentation metadata, not the
 authority for pointer navigation.
+
+### Gate-Action Envelope
+
+Every active Builder continuation request includes a bounded
+`gate_action_envelope` with schema version `1.0`. Flow Agents derives it from
+the persisted canonical Flow run and effective Flow Definition, then joins it
+to the installed Builder Kit's validated `flow_step_actions` record. It is an
+execution context, not a second gate evaluator: Flow remains the only authority
+that evaluates requirements, advances steps, routes back, or consumes attempt
+budget.
+
+The envelope provides the current gate ids and claim shapes, including each
+expectation's required flag and `satisfied`, `accepted_exception`, or `unresolved`
+status. Accepted exceptions are identified separately. Flow Agents evaluates
+these statuses with the run's effective Flow config, including gate overrides,
+so waived, satisfied, and optional work is never mislabeled as required. Skill
+identities bind package, version, stable package-relative source
+path, and SHA-256, so durable attestations never retain a stale absolute install path.
+Requirement status comes from Flow's canonical gate evaluation and therefore
+uses the expectation's trust-bundle selector, Surface-derived claim status,
+supersession, freshness, and current gate visit; `expectation_ids` labels alone
+never mark a requirement satisfied.
+Declared operations, artifacts, and evidence expectation ids come from product
+metadata. `implementation_allowed` is also product metadata; the shipped Builder
+Kit declares it true only for `builder.build/execute`.
+
+The read-only status interface is an exact version-pinned command. Mutation
+interfaces are typed per expectation: `workflow.evidence`, `workflow.critique`,
+or a named product operation such as `publish-change`. Evidence and critique
+interfaces expose fixed argv plus typed required parameters and allowed values;
+they do not publish shell strings with substitution placeholders. Consumers add
+parameter values as distinct argv entries.
+
+`publish-change` is a provider-capability protocol, not a claim that the local
+`flow-agents publish-change` helper opens a pull request. Its envelope binds the
+exact `pull_request.create` capability, bounded structured inputs, the required
+provider result, and the dedicated session-relative
+`publish-change.result.json` artifact. No authenticated ChangeProvider executor
+ships in this issue, so the operation is explicitly unavailable locally and has
+an `external_verification_required` completion state. It exposes no
+`record_completion` mutation, a self-authored result cannot satisfy
+`pull-request-opened`, and the projection waits instead of scheduling repeated
+adapter turns. The protocol remains the future provider contract. The local
+publish-change helper only renders and validates publish artifacts and provider
+checks; it is not the provider action executor.
+
+`flow_step_actions` must explicitly declare `artifacts`, `artifact_bindings`,
+`expectation_ids`, `expectation_bindings`, and `implementation_allowed`, including
+empty lists for terminal actions. Expectation ids must exactly equal the resolved
+Flow expectation set. Artifact bindings map each artifact to its owning
+expectations, allowing optional artifacts to remain declared without appearing
+under `stop_condition.required`. Operation bindings must resolve through the
+canonical public operation catalog, not merely a self-declared string. Artifact
+refs are either lexically safe session-relative paths or validated
+`trust.bundle#<safe-id>` virtual refs; absolute paths, traversal, and arbitrary
+fragments fail closed. Malformed,
+unknown-field, duplicate, oversized, unmatched, symlinked, or otherwise
+unbounded action metadata fails closed before an adapter is launched. The
+runtime verifies every named skill against the installed Builder package and
+binds its contents by SHA-256. Kit JSON, skill source, and artifact identity/hash
+reads open the final path once with `O_NOFOLLOW`, bound size from `fstat`, read
+through that descriptor, and recheck descriptor/path identity after the read.
+Run-wide artifact observation deduplicates refs and enforces count plus aggregate
+byte/hash budgets before reading file contents. Product validation and runtime
+both cap each action at 16 skills and each flow at 128 distinct observable file
+artifacts; virtual trust-bundle refs and control artifacts are excluded using the
+same classification in both layers.
+
+After every successful or failed adapter turn, Flow Agents synchronizes the
+canonical run and records a delta: step advancement, newly attached canonical
+evidence, changed hashes of declared artifacts (`artifact_changes`), or no
+progress. Evidence identities and the artifact manifest are run-wide rather
+than selected-step scoped, so the evidence/artifact that advances a gate remains
+attributable and files already present for later steps are part of the baseline.
+Control `state.json` is excluded from both request-facing declared/required
+artifacts and artifact progress. Legacy kit ownership metadata may retain it,
+but the envelope never instructs an adapter to produce Flow Agents control
+state or observes its own hash. Repeated
+no-progress deltas are classified as `possible` and then `stagnant`; they never
+invent evidence, auto-pass a gate, or change Flow state. A same-step evidence
+attachment is recorded as progress even though the legacy `gate_not_advanced`
+event remains for compatibility. Adapter-returned `evidence` remains optional
+adapter telemetry only and is never gate evidence.
+
+The durable `last_progress` snapshot is the recovery baseline. A durable active
+turn phase and pre-turn snapshot identify an adapter turn interrupted before its
+post-turn measurement. Reinvocation compares freshly synchronized canonical
+state with that snapshot, counts an unchanged started turn as no progress exactly
+once, records any delta, and clears the recovery marker. Synchronization and this
+reconciliation occur before waiting or terminal disposition handling, so the
+turn's audit and progress survive either outcome. Accepted turns, wait turns, and
+callback failures are likewise synchronized and measured before their durable
+turn marker is cleared. Signed workflow drives preflight the aggregate attestation
+capacity before launching an adapter when another bounded signed result cannot fit.
+Accepted request/result pairs and their measured progress are first stored in a
+durable idempotent journal while the active turn remains in `measured` phase.
+Only after journal and completion-event persistence does the driver clear that
+marker. Restart completes either write exactly once. Signed attestations reload
+the journal and fail closed if an accepted event lacks request/result coverage.
+The complete serialized turn result is capped at 74,000 bytes; signed preflight
+reserves that exact maximum in addition to the actual request and JSON structure.
+The authoritative envelope
+exists only at top-level in the turn request; projected `next_action` and durable
+`state.json` do not contain a duplicate.
+
+Canonical synchronization normally waits for attached bundle evidence before
+evaluating a gate. It may evaluate an evidence-free gate only when the run's
+effective config proves the gate can pass without new evidence: an accepted
+exception applies, or every effective expectation is optional. This advances
+those gates without prematurely evaluating ordinary missing-required gates, and
+once the run advances no obsolete action skill remains required.
+
+The envelope and its prior-turn delta are additive fields of
+`ContinuationTurnRequest` schema `1.0`; adapters that only consume the existing
+request fields remain compatible. When `workflow drive` produces its optional
+signed request/result attestation, the exact request object (including the
+envelope) is included in the signed payload without transformation.
 # Builder Lifecycle Authority
 
 The canonical Flow run owns pause, resume, and cancellation. The current assignment actor may