@kontourai/flow-agents 2.3.0 → 3.0.0

package/evals/static/test_package.sh

@@ -87,6 +87,7 @@ for (const entry of required) {
 const requiredExcludes = [
   "!evals/cases/dev/node_modules/",
   "!**/.flow-agents/",
+  "!**/.kontourai/",
   "!**/.surface/",
   "!**/.telemetry/",
   "!**/.veritas/",
@@ -99,7 +100,7 @@ const forbidden = [
   ".agents/",
   ".codex/",
   ".claude/",
-  ".flow-agents/",
+  ".kontourai/",
   ".surface/",
   ".telemetry/",
   ".veritas/",
@@ -120,7 +121,7 @@ NODE
   if node - "$ROOT_DIR/console.telemetry.json" <<'NODE'
 const fs = require("node:fs");
 const descriptor = JSON.parse(fs.readFileSync(process.argv[2], "utf8"));
-for (const id of ["builder.shape", "builder.build"]) {
+for (const id of ["builder.shape", "builder.build", "builder.publish-learn"]) {
   const flow = (descriptor.flows || []).find((candidate) => candidate.id === id);
   if (!flow) throw new Error(`missing ${id} flow descriptor`);
   if (!flow.detailAttributes || Array.isArray(flow.detailAttributes) || typeof flow.detailAttributes !== "object") {
@@ -142,14 +143,14 @@ NODE
   else
     _pass "tracked source has no legacy Flow Agents rename references"
   fi
-  if (cd "$ROOT_DIR" && FLOW_AGENTS_CONTENT_BOUNDARY_FILES='.flow-agents/example/state.json' node scripts/check-content-boundary.cjs >/tmp/content-boundary-runtime.out 2>&1); then
+  if (cd "$ROOT_DIR" && FLOW_AGENTS_CONTENT_BOUNDARY_FILES='.kontourai/flow-agents/example/state.json' node scripts/check-content-boundary.cjs >/tmp/content-boundary-runtime.out 2>&1); then
     _fail "content boundary allows ordinary workflow runtime artifacts"
   elif rg -q 'Flow Agents runtime artifact must not be tracked' /tmp/content-boundary-runtime.out; then
     _pass "content boundary blocks ordinary workflow runtime artifacts"
   else
     _fail "content boundary runtime rejection was not actionable"
   fi
-  if (cd "$ROOT_DIR" && FLOW_AGENTS_CONTENT_BOUNDARY_FILES='.flow-agents/nested/example/closeout.md' node scripts/check-content-boundary.cjs >/tmp/content-boundary-nested.out 2>&1); then
+  if (cd "$ROOT_DIR" && FLOW_AGENTS_CONTENT_BOUNDARY_FILES='.kontourai/flow-agents/nested/example/closeout.md' node scripts/check-content-boundary.cjs >/tmp/content-boundary-nested.out 2>&1); then
     _fail "content boundary allows nested workflow runtime artifacts"
   elif rg -q 'Flow Agents runtime artifact must not be tracked' /tmp/content-boundary-nested.out; then
     _pass "content boundary blocks nested workflow runtime artifacts"
@@ -157,7 +158,7 @@ NODE
     _fail "content boundary nested runtime rejection was not actionable"
   fi
   current_branch="$(cd "$ROOT_DIR" && git branch --show-current 2>/dev/null || true)"
-  tracked_runtime_artifacts="$(cd "$ROOT_DIR" && git ls-files -- '.flow-agents' 2>/dev/null || true)"
+  tracked_runtime_artifacts="$(cd "$ROOT_DIR" && git ls-files -- '.kontourai/flow-agents' 2>/dev/null || true)"
   if [[ "$current_branch" == "main" && -n "$tracked_runtime_artifacts" ]]; then
     printf '%s\n' "$tracked_runtime_artifacts" >/tmp/tracked-flow-agent-runtime-artifacts.txt
     _fail "main contains tracked workflow runtime artifacts (see /tmp/tracked-flow-agent-runtime-artifacts.txt)"
@@ -174,12 +175,12 @@ NODE
   else
     _fail "installed bundle is missing Kit Catalog or Builder Kit manifest"
   fi
-  if [[ -f "$PACKAGE_DIR/kits/builder/flows/shape.flow.json" && -f "$PACKAGE_DIR/kits/builder/flows/build.flow.json" ]]; then
+  if [[ -f "$PACKAGE_DIR/kits/builder/flows/shape.flow.json" && -f "$PACKAGE_DIR/kits/builder/flows/build.flow.json" && -f "$PACKAGE_DIR/kits/builder/flows/publish-learn.flow.json" ]]; then
     _pass "installed bundle includes Builder Kit Flow Definitions"
   else
     _fail "installed bundle is missing Builder Kit Flow Definitions"
   fi
-  if node - "$PACKAGE_DIR/kits/catalog.json" "$PACKAGE_DIR/kits/builder/kit.json" "$PACKAGE_DIR/kits/builder/flows/shape.flow.json" "$PACKAGE_DIR/kits/builder/flows/build.flow.json" <<'NODE'
+  if node - "$PACKAGE_DIR/kits/catalog.json" "$PACKAGE_DIR/kits/builder/kit.json" "$PACKAGE_DIR/kits/builder/flows/shape.flow.json" "$PACKAGE_DIR/kits/builder/flows/build.flow.json" "$PACKAGE_DIR/kits/builder/flows/publish-learn.flow.json" <<'NODE'
 const fs = require("node:fs");
 for (const file of process.argv.slice(2)) JSON.parse(fs.readFileSync(file, "utf8"));
 console.log("ok");
@@ -189,9 +190,10 @@ NODE
   else
     _fail "installed kit JSON parse failed"
   fi
-  if node - "$PACKAGE_DIR/kits/builder/flows/build.flow.json" <<'NODE'
+  if node - "$PACKAGE_DIR/kits/builder/flows/build.flow.json" "$PACKAGE_DIR/kits/builder/flows/publish-learn.flow.json" <<'NODE'
 const fs = require("node:fs");
 const flow = JSON.parse(fs.readFileSync(process.argv[2], "utf8"));
+const publishLearn = JSON.parse(fs.readFileSync(process.argv[3], "utf8"));
 const steps = Object.fromEntries((flow.steps || []).map((step) => [step.id, step.next]));
 if (steps["pull-work"] !== "design-probe") throw new Error("pull-work should route to design-probe");
 if (steps["design-probe"] !== "plan") throw new Error("design-probe should route to plan");
@@ -208,13 +210,20 @@ for (const gateId of ["verify-gate", "merge-ready-gate"]) {
   for (const [reason, target] of Object.entries(expected)) if (gate.on_route_back?.[reason] !== target) throw new Error(`${gateId} ${reason} should route to ${target}`);
   if (gate.route_back_policy?.on_exceeded !== "block") throw new Error(`${gateId} route_back_policy should block on exceeded attempts`);
 }
-const expectations = Object.values(flow.gates || {}).flatMap((gate) => gate.expects || []);
+for (const stepId of ["pr-open", "merge-ready-ci", "learn"]) {
+  const step = (flow.steps || []).find((item) => item.id === stepId);
+  if (step?.uses_flow !== "builder.publish-learn") throw new Error(`${stepId} should compose builder.publish-learn`);
+}
+const expectations = [
+  ...Object.values(flow.gates || {}).flatMap((gate) => gate.expects || []),
+  ...Object.values(publishLearn.gates || {}).flatMap((gate) => gate.expects || []),
+];
 if (!expectations.length) throw new Error("Builder build flow should declare gate expectations");
 for (const expectation of expectations) {
   if (expectation.kind !== "trust.bundle") throw new Error(`${expectation.id || "<unknown>"} should remain a trust.bundle expectation`);
   if (!expectation.bundle_claim?.claimType || !expectation.bundle_claim?.accepted_statuses) throw new Error(`${expectation.id || "<unknown>"} should declare bundle_claim claimType and accepted statuses`);
 }
-const flowText = JSON.stringify(flow).toLowerCase();
+const flowText = JSON.stringify({ flow, publishLearn }).toLowerCase();
 for (const term of ["veritas", "trust_provider", "trust-provider", "provider_name", "provider_ref", "veritas_policy", "veritas_readiness"]) {
   if (flowText.includes(term)) throw new Error(`Builder build flow should not name provider-specific trust field: ${term}`);
 }

package/evals/static/test_universal_bundles.sh

@@ -10,7 +10,7 @@ pass=0
 fail=0
 
 cleanup() {
-  rm -rf "$REPRO_FIRST_DIR" "$REPRO_SECOND_DIR"
+  rm -rf "$REPRO_FIRST_DIR" "$REPRO_SECOND_DIR" "$ROOT_DIR/kits/zzz-collision-eval-probe"
 }
 trap cleanup EXIT
 
@@ -172,11 +172,15 @@ if node - "$DIST_DIR/codex/.codex" <<'NODE'
 const fs = require("node:fs");
 const path = require("node:path");
 const root = process.argv[2];
-const expected = ["kdev", "kdev-br"];
+const expected = ["builder", "personal"];
 const missingFiles = expected.filter((name) => !fs.existsSync(path.join(root, `${name}.config.toml`)));
 if (missingFiles.length) throw new Error(`profile-v2 config files missing: ${missingFiles.join(", ")}`);
+const extra = fs.readdirSync(root).filter((name) => name.endsWith(".config.toml") && !expected.includes(name.replace(/\.config\.toml$/, "")));
+if (extra.length) throw new Error(`unexpected generated profile files: ${extra.join(", ")}`);
 const missing = expected.filter((name) => !fs.readFileSync(path.join(root, `${name}.config.toml`), "utf8").includes('approvals_reviewer = "auto_review"'));
 if (missing.length) throw new Error(`profile auto-review approval reviewer missing: ${missing.join(", ")}`);
+const personal = fs.readFileSync(path.join(root, "personal.config.toml"), "utf8");
+if (!personal.includes("Flow Agents Personal mode") || !personal.includes("knowledge-capture")) throw new Error("personal profile does not carry knowledge-work instructions");
 console.log("ok");
 NODE
 then
@@ -373,7 +377,7 @@ fi
 
 echo ""
 echo "--- Shared Task Dirs ---"
-for dir in "$DIST_DIR/claude-code/.flow-agents" "$DIST_DIR/codex/.flow-agents" "$DIST_DIR/opencode/.flow-agents" "$DIST_DIR/pi/.flow-agents"; do
+for dir in "$DIST_DIR/claude-code/.kontourai/flow-agents" "$DIST_DIR/codex/.kontourai/flow-agents" "$DIST_DIR/opencode/.kontourai/flow-agents" "$DIST_DIR/pi/.kontourai/flow-agents"; do
   if [[ -d "$dir" ]]; then
     _pass "$(realpath "$dir" 2>/dev/null || echo "$dir") exists"
   else
@@ -426,6 +430,47 @@ else
   _fail "pi adapter block path dropped the policy reason"
 fi
 
+echo ""
+echo "--- Skill collision detector (AC6) ---"
+# Positive: the real skill set across skills/ and kits/*/kit.json builds with no collision.
+if (cd "$ROOT_DIR" && FLOW_AGENTS_DIST_DIR="$(mktemp -d)" node build/src/cli.js build-bundles) >/tmp/universal-bundle-collision-clean.txt 2>&1; then
+  _pass "build succeeds with the current (collision-free) skill set"
+else
+  _fail "clean build unexpectedly failed"
+  sed -n '1,60p' /tmp/universal-bundle-collision-clean.txt
+fi
+
+# Negative: a synthetic kit re-using an existing skill directory name (deliver) must FAIL
+# the build with a diagnostic naming both source kits.
+COLLIDE_KIT="$ROOT_DIR/kits/zzz-collision-eval-probe"
+rm -rf "$COLLIDE_KIT"
+mkdir -p "$COLLIDE_KIT/skills/deliver"
+cat > "$COLLIDE_KIT/kit.json" <<'KITJSON'
+{
+  "schema_version": "1.0",
+  "id": "zzz-collision-eval-probe",
+  "name": "Collision Eval Probe",
+  "flows": [],
+  "skills": [
+    { "id": "zzz.deliver", "path": "skills/deliver/SKILL.md" }
+  ]
+}
+KITJSON
+printf '# collision probe skill\n' > "$COLLIDE_KIT/skills/deliver/SKILL.md"
+if (cd "$ROOT_DIR" && FLOW_AGENTS_DIST_DIR="$(mktemp -d)" node build/src/cli.js build-bundles) >/tmp/universal-bundle-collision.txt 2>&1; then
+  _fail "build should FAIL when two kits declare the same skill directory name"
+else
+  if grep -q "skill name collision" /tmp/universal-bundle-collision.txt \
+    && grep -q "kits/builder" /tmp/universal-bundle-collision.txt \
+    && grep -q "zzz-collision-eval-probe" /tmp/universal-bundle-collision.txt; then
+    _pass "build fails with a clear collision diagnostic naming both source kits"
+  else
+    _fail "collision diagnostic missing expected text"
+    sed -n '1,60p' /tmp/universal-bundle-collision.txt
+  fi
+fi
+rm -rf "$COLLIDE_KIT"
+
 echo ""
 echo "==========================="
 total=$((pass + fail))

package/evals/static/test_workflow_skills.sh

@@ -77,6 +77,7 @@ OPERATING_LAYERS_DOC="$ROOT/docs/operating-layers.md"
 DEVELOPER_ARCHITECTURE_DOC="$ROOT/docs/developer-architecture.md"
 GITIGNORE="$ROOT/.gitignore"
 BUILDER_BUILD_FLOW="$ROOT/kits/builder/flows/build.flow.json"
+BUILDER_PUBLISH_LEARN_FLOW="$ROOT/kits/builder/flows/publish-learn.flow.json"
 FLOW_AGENTS_FLOW_ADR="$ROOT/docs/adr/0001-flow-agents-consumes-flow.md"
 ARTIFACT_CONTRACT="$ROOT/context/contracts/artifact-contract.md"
 PLANNING_CONTRACT="$ROOT/context/contracts/planning-contract.md"
@@ -180,6 +181,7 @@ require_file "$ARTIFACT_LIFECYCLE_DOC" "workflow artifact lifecycle doc"
 require_file "$OPERATING_LAYERS_DOC" "operating layers doc"
 require_file "$DEVELOPER_ARCHITECTURE_DOC" "developer architecture doc"
 require_file "$BUILDER_BUILD_FLOW" "Builder Kit build Flow Definition"
+require_file "$BUILDER_PUBLISH_LEARN_FLOW" "Builder Kit publish-learn Flow Definition"
 require_file "$FLOW_AGENTS_FLOW_ADR" "Flow Agents Flow boundary ADR"
 require_file "$ARTIFACT_CONTRACT" "artifact contract"
 require_file "$PLANNING_CONTRACT" "planning contract"
@@ -294,7 +296,7 @@ require_text "$DELIVERY_CONTRACT" 'Final Acceptance' "delivery contract defines
 require_text "$DELIVERY_CONTRACT" 'Publish verified changes before release readiness' "delivery contract requires publish-change before release readiness"
 require_text "$DELIVERY_CONTRACT" 'verified diff committed and pushed' "final acceptance requires committed and pushed diff"
 require_text "$DELIVERY_CONTRACT" 'provider change record created or updated' "final acceptance requires provider change or explicit no-provider-change reason"
-require_text "$DELIVERY_CONTRACT" 'local `\.flow-agents/` runtime artifacts remain untracked' "final acceptance requires runtime artifacts stay untracked"
+require_text "$DELIVERY_CONTRACT" 'local `\.kontourai/flow-agents/` runtime artifacts remain untracked' "final acceptance requires runtime artifacts stay untracked"
 require_text "$DELIVERY_CONTRACT" 'GitHub PRs are the first `ChangeProvider` adapter example' "delivery contract keeps GitHub PR as adapter example"
 require_text "$DELIVERY_CONTRACT" 'Delegation Gates' "delivery contract defines delegation gates"
 require_text "$DELIVERY_CONTRACT" 'Do not replace the delegate gate with a local summary' "delivery contract forbids local gate substitution"
@@ -307,7 +309,7 @@ require_text "$ARTIFACT_LIFECYCLE_DOC" 'Runtime state remains ignored' "artifact
 require_text "$ARTIFACT_LIFECYCLE_DOC" 'Durable closeout content' "artifact lifecycle doc requires closeout"
 require_text "$ARTIFACT_LIFECYCLE_DOC" 'durable planning, decisions, evidence pointers, and acceptance notes' "artifact lifecycle doc requires durable promotion"
 require_text "$ARTIFACT_LIFECYCLE_DOC" 'Promote by ownership' "artifact lifecycle doc defines promotion targets"
-require_text "$ARTIFACT_CONTRACT" 'Do not commit local workflow runtime roots such as `\.flow-agents/<slug>/`' "artifact contract forbids committing runtime workspaces"
+require_text "$ARTIFACT_CONTRACT" 'Do not commit local workflow runtime roots such as `\.kontourai/flow-agents/<slug>/`' "artifact contract forbids committing runtime workspaces"
 require_text "$OPERATING_LAYERS_DOC" 'workflow-artifact-lifecycle.md' "operating layers links artifact lifecycle"
 require_text "$PAGES_INDEX" 'workflow-artifact-lifecycle.html' "docs index links artifact lifecycle"
 require_text "$PAGES_INDEX" 'developer-architecture.html' "docs index links developer architecture"
@@ -385,6 +387,8 @@ require_text "$KIT_REPOSITORY_DOC" 'schema_version' "kit repository doc defines
 require_text "$KIT_REPOSITORY_DOC" 'flows' "kit repository doc defines declared Flow Definitions"
 require_text "$KIT_REPOSITORY_DOC" '[Aa]bsolute paths are rejected' "kit repository doc defines path safety"
 require_text "$KIT_REPOSITORY_DOC" 'does not install remote kits' "kit repository doc states remote install non-goal"
+require_text "$ROOT/docs/kit-authoring-guide.md" 'uses_flow' "kit authoring guide documents Flow Definition composition"
+require_text "$ROOT/docs/kit-authoring-guide.md" 'builder.publish-learn' "kit authoring guide documents composed publish-learn example"
 require_text "$PAGES_INDEX" 'Quick Start' "docs index presents product quick start"
 require_text "$KIT_REPOSITORY_INTEGRATION" 'valid-local-kit' "kit repository integration covers valid fixture"
 require_text "$KIT_REPOSITORY_INTEGRATION" 'invalid-schema-version' "kit repository integration covers invalid schema version"
@@ -426,10 +430,10 @@ require_text "$TOOL_WORKER" 'docs/context-map.md' "tool-worker uses context map"
 require_text "$TOOL_VERIFIER" 'docs/context-map.md' "tool-verifier uses context map"
 require_text "$TOOL_VERIFIER" 'Report only' "tool-verifier keeps report-only role"
 require_text "$DEV_PROMPTFOO" 'deep-context contract persistence' "dev evals include deep-context contract persistence case"
-require_text "$PACKAGE_MANIFEST" 'plan-work must delegate to tool-planner' "Codex kdev profile requires planner delegation"
-require_text "$PACKAGE_MANIFEST" 'verify-work to tool-verifier' "Codex kdev profile requires verifier delegation"
-require_text "$PACKAGE_MANIFEST" 'instead of replacing it with a local summary' "Codex kdev profile preserves blocked delegation gates"
-require_text "$PACKAGE_MANIFEST" 'name exact delegate ids' "Codex kdev profile requires auditable delegate names"
+require_text "$PACKAGE_MANIFEST" 'plan-work must delegate to tool-planner' "Codex builder profile requires planner delegation"
+require_text "$PACKAGE_MANIFEST" 'verify-work to tool-verifier' "Codex builder profile requires verifier delegation"
+require_text "$PACKAGE_MANIFEST" 'instead of replacing it with a local summary' "Codex builder profile preserves blocked delegation gates"
+require_text "$PACKAGE_MANIFEST" 'name exact delegate ids' "Codex builder profile requires auditable delegate names"
 
 echo ""
 echo "--- delivery goal fit ---"
@@ -441,7 +445,8 @@ require_text "$DELIVER" 'Final Acceptance' "deliver requires Final Acceptance"
 require_text "$DELIVER" 'Required Preflight' "deliver defines pull/pickup preflight"
 require_text "$DELIVER" 'pull-work -> pickup-probe' "deliver routes missing pickup evidence through pull-work and pickup-probe"
 require_text "$DELIVER" 'continue automatically to execution' "deliver can proceed autonomously after planning"
-require_text "$DELIVER" '\.flow-agents/<slug>/archive' "deliver archives working artifacts"
+require_text "$DELIVER" '\.kontourai/flow-agents/<slug>/archive' "deliver archives working artifacts"
+require_text "$DELIVER" 'Do not skip learning just because the delivery looked clean' "deliver always routes terminal closeout through learning-review"
 require_text "$DELIVER" 'Sidecar Writer Adoption' "deliver owns sidecar writer adoption"
 require_text "$DELIVER" 'record-critique|import-critique' "deliver records critique through sidecar writer"
 require_text "$VERIFY_WORK" 'Goal Fit' "verify-work reports Goal Fit"
@@ -542,6 +547,11 @@ require_text "$CONTEXT_MAP_INTEGRATION" 'context map generation is deterministic
 require_text "$WORKFLOW_STEERING_INTEGRATION" 'workflow steering hook neutralizes multiline critique findings' "workflow steering integration covers critique sanitization"
 require_text "$WORKFLOW_STEERING_INTEGRATION" 'workflow steering hook appends context-map recovery guidance' "workflow steering integration covers context-map guidance"
 require_text "$WORKFLOW_STEERING_INTEGRATION" 'workflow steering hook emits ambient state guidance at user prompt submit' "workflow steering integration covers ambient state guidance"
+require_text "$WORKFLOW_STEERING_INTEGRATION" 'Claude hook adapter surfaces Builder workflow route for coding prompts' "workflow steering integration covers Claude Builder-route prompt guidance"
+require_text "$WORKFLOW_STEERING_INTEGRATION" 'publish/release-readiness and learning-review' "workflow steering integration covers full Builder lifecycle guidance"
+require_text "$WORKFLOW_STEERING_INTEGRATION" 'does not route explicit review-only prompts into Builder workflow' "workflow steering integration covers review-only prompt suppression"
+require_text "$WORKFLOW_STEERING_INTEGRATION" 'does not route explicit validation-only prompts into Builder workflow' "workflow steering integration covers validation-only prompt suppression"
+require_text "$WORKFLOW_STEERING_INTEGRATION" 'does not route question-only test prompts into Builder workflow' "workflow steering integration covers question-only test prompt suppression"
 require_text "$ROOT/evals/integration/test_goal_fit_hook.sh" 'goal-fit hook reports actionable sidecar guidance' "goal-fit integration covers specific sidecar guidance"
 require_text "$HOOK_INFLUENCE_CASES" 'agent_must_do' "hook influence cases define expected agent behavior"
 require_text "$HOOK_INFLUENCE_CASES" 'live-acceptance' "hook influence cases include live acceptance evidence"
@@ -1068,6 +1078,11 @@ require_text "$BUILDER_BUILD_FLOW" 'Planning is blocked until pickup Probe decis
 require_text "$BUILDER_BUILD_FLOW" 'probe_status' "Builder build flow names probe status"
 require_text "$BUILDER_BUILD_FLOW" 'probe_artifact_ref' "Builder build flow names probe artifact ref"
 require_text "$BUILDER_BUILD_FLOW" 'Stale broad continuation language after a merge is not sufficient' "Builder build flow blocks stale broad continuation"
+require_text "$BUILDER_BUILD_FLOW" '"uses_flow": "builder.publish-learn"' "Builder build flow composes publish-learn extension"
+require_text "$BUILDER_PUBLISH_LEARN_FLOW" '"builder.pr-open.pull-request"' "Builder publish-learn flow exports PR-open evidence"
+require_text "$BUILDER_PUBLISH_LEARN_FLOW" '"builder.merge-ready-ci.readiness"' "Builder publish-learn flow exports CI merge readiness evidence"
+require_text "$BUILDER_PUBLISH_LEARN_FLOW" '"builder.learn.evidence"' "Builder publish-learn flow exports learning evidence"
+require_text "$BUILDER_PUBLISH_LEARN_FLOW" '"exports"' "Builder publish-learn flow declares exported claims"
 if node - "$BUILDER_BUILD_FLOW" <<'NODE'; then
 const fs = require("node:fs");
 const flow = JSON.parse(fs.readFileSync(process.argv[2], "utf8"));
@@ -1086,6 +1101,24 @@ NODE
 else
   fail "Builder build flow keeps provider-neutral trust.bundle expectations"
 fi
+if node - "$BUILDER_BUILD_FLOW" "$BUILDER_PUBLISH_LEARN_FLOW" <<'NODE'; then
+const fs = require("node:fs");
+const parent = JSON.parse(fs.readFileSync(process.argv[2], "utf8"));
+const child = JSON.parse(fs.readFileSync(process.argv[3], "utf8"));
+for (const stepId of ["pr-open", "merge-ready-ci", "learn"]) {
+  const step = (parent.steps || []).find((item) => item.id === stepId);
+  if (step?.uses_flow !== "builder.publish-learn") throw new Error(`${stepId} should use builder.publish-learn`);
+  const childGate = Object.values(child.gates || {}).find((gate) => gate.step === stepId);
+  if (!childGate) throw new Error(`builder.publish-learn missing gate for ${stepId}`);
+  for (const expectation of childGate.expects || []) {
+    if (expectation.kind !== "trust.bundle") throw new Error(`${expectation.id || "<unknown>"} is not a trust.bundle expectation`);
+  }
+}
+NODE
+  pass "Builder publish-learn composition resolves PR, CI, and learning gates"
+else
+  fail "Builder publish-learn composition resolves PR, CI, and learning gates"
+fi
 require_text "$MAP" 'pull-work' "map includes pull-work"
 require_text "$MAP" 'pickup Probe before planning' "map documents pickup Probe before planning"
 require_text "$MAP" 'review-work' "map includes review-work"
@@ -1115,7 +1148,7 @@ require_text "$LEARNING" 'dogfood-pass' "learning-review skill adopts dogfood-pa
 require_text "$EVAL_STRATEGY" 'Activation-only behavioral evals' "eval strategy distinguishes activation evals"
 require_text "$EVAL_STRATEGY" 'Artifact-quality evals' "eval strategy distinguishes artifact evals"
 require_text "$EVAL_STRATEGY" 'Hook-influence behavioral cases' "eval strategy documents hook influence cases"
-require_text "$EVAL_STRATEGY" 'controlled writes to `.flow-agents/<slug>/\*\.md`' "artifact evals allow controlled todo writes"
+require_text "$EVAL_STRATEGY" 'controlled writes to `.kontourai/flow-agents/<slug>/\*\.md`' "artifact evals allow controlled todo writes"
 require_text "$EVAL_STRATEGY" 'test_workflow_artifacts.sh' "eval strategy documents artifact E2E integration"
 require_text "$EVAL_STRATEGY" 'HOLD' "eval strategy uses release-readiness HOLD decision"
 require_text "$SHARED_CONTRACTS_DOC" 'Codex, Kiro, Claude Code' "shared contracts doc captures cross-distribution scope"

package/kits/builder/flows/build.flow.json

@@ -18,9 +18,9 @@
     { "id": "execute", "next": "verify" },
     { "id": "verify", "next": "merge-ready" },
     { "id": "merge-ready", "next": "pr-open" },
-    { "id": "pr-open", "next": "merge-ready-ci" },
-    { "id": "merge-ready-ci", "next": "learn" },
-    { "id": "learn", "next": "done" },
+    { "id": "pr-open", "next": "merge-ready-ci", "uses_flow": "builder.publish-learn" },
+    { "id": "merge-ready-ci", "next": "learn", "uses_flow": "builder.publish-learn" },
+    { "id": "learn", "next": "done", "uses_flow": "builder.publish-learn" },
     { "id": "done", "next": null }
   ],
   "gates": {
@@ -189,77 +189,6 @@
           }
         }
       ]
-    },
-    "pr-open-gate": {
-      "step": "pr-open",
-      "expects": [
-        {
-          "id": "pull-request-opened",
-          "kind": "trust.bundle",
-          "required": true,
-          "description": "A pull request exists with linked work, implementation summary, and verification evidence.",
-          "bundle_claim": {
-            "claimType": "builder.pr-open.pull-request",
-            "subjectType": "pull-request",
-            "accepted_statuses": [
-              "trusted",
-              "accepted"
-            ]
-          }
-        }
-      ]
-    },
-    "merge-ready-ci-gate": {
-      "step": "merge-ready-ci",
-      "expects": [
-        {
-          "id": "ci-merge-readiness",
-          "kind": "trust.bundle",
-          "required": true,
-          "description": "CI and review status support a merge-ready decision.",
-          "bundle_claim": {
-            "claimType": "builder.merge-ready-ci.readiness",
-            "subjectType": "pull-request",
-            "accepted_statuses": [
-              "trusted",
-              "accepted"
-            ]
-          }
-        }
-      ]
-    },
-    "learn-gate": {
-      "step": "learn",
-      "expects": [
-        {
-          "id": "decision-evidence",
-          "kind": "trust.bundle",
-          "required": true,
-          "description": "Durable decision evidence from the build is recorded.",
-          "bundle_claim": {
-            "claimType": "builder.learn.decisions",
-            "subjectType": "decision",
-            "accepted_statuses": [
-              "trusted",
-              "accepted"
-            ]
-          }
-        },
-        {
-          "id": "learning-evidence",
-          "kind": "trust.bundle",
-          "required": true,
-          "description": "Learning evidence from delivery is recorded for future work.",
-          "bundle_claim": {
-            "claimType": "builder.learn.evidence",
-            "subjectType": "release",
-            "accepted_statuses": [
-              "trusted",
-              "accepted"
-            ]
-          }
-        }
-      ]
     }
   }
 }

package/kits/builder/flows/publish-learn.flow.json

@@ -0,0 +1,90 @@
+{
+  "id": "builder.publish-learn",
+  "version": "1.0",
+  "description": "Reusable delivery closeout extension: publish the verified change, confirm merge readiness from provider/CI evidence, and record learning feedback.",
+  "steps": [
+    { "id": "pr-open", "next": "merge-ready-ci" },
+    { "id": "merge-ready-ci", "next": "learn" },
+    { "id": "learn", "next": "done" },
+    { "id": "done", "next": null }
+  ],
+  "exports": [
+    "builder.pr-open.pull-request",
+    "builder.merge-ready-ci.readiness",
+    "builder.learn.decisions",
+    "builder.learn.evidence"
+  ],
+  "gates": {
+    "pr-open-gate": {
+      "step": "pr-open",
+      "expects": [
+        {
+          "id": "pull-request-opened",
+          "kind": "trust.bundle",
+          "required": true,
+          "description": "A pull request exists with linked work, implementation summary, and verification evidence.",
+          "bundle_claim": {
+            "claimType": "builder.pr-open.pull-request",
+            "subjectType": "pull-request",
+            "accepted_statuses": [
+              "trusted",
+              "accepted"
+            ]
+          }
+        }
+      ]
+    },
+    "merge-ready-ci-gate": {
+      "step": "merge-ready-ci",
+      "expects": [
+        {
+          "id": "ci-merge-readiness",
+          "kind": "trust.bundle",
+          "required": true,
+          "description": "CI and review status support a merge-ready decision.",
+          "bundle_claim": {
+            "claimType": "builder.merge-ready-ci.readiness",
+            "subjectType": "pull-request",
+            "accepted_statuses": [
+              "trusted",
+              "accepted"
+            ]
+          }
+        }
+      ]
+    },
+    "learn-gate": {
+      "step": "learn",
+      "expects": [
+        {
+          "id": "decision-evidence",
+          "kind": "trust.bundle",
+          "required": true,
+          "description": "Durable decision evidence from the build is recorded.",
+          "bundle_claim": {
+            "claimType": "builder.learn.decisions",
+            "subjectType": "decision",
+            "accepted_statuses": [
+              "trusted",
+              "accepted"
+            ]
+          }
+        },
+        {
+          "id": "learning-evidence",
+          "kind": "trust.bundle",
+          "required": true,
+          "description": "Learning evidence from delivery is recorded for future work.",
+          "bundle_claim": {
+            "claimType": "builder.learn.evidence",
+            "subjectType": "release",
+            "accepted_statuses": [
+              "trusted",
+              "accepted"
+            ]
+          }
+        }
+      ]
+    }
+  }
+}

package/kits/builder/kit.json

@@ -14,6 +14,17 @@
       "id": "builder.build",
       "path": "flows/build.flow.json",
       "description": "Pull ready work through design probing, planning, implementation, verification, pull request readiness, merge readiness, and learning."
+    },
+    {
+      "id": "builder.publish-learn",
+      "path": "flows/publish-learn.flow.json",
+      "description": "Reusable delivery closeout extension for publish, provider/CI merge readiness, and learning feedback gates."
+    }
+  ],
+  "dependencies": [
+    {
+      "kit_id": "knowledge",
+      "reason": "learning-review invokes knowledge-capture (kits/knowledge/skills/knowledge-capture/SKILL.md) for durable knowledge storage"
     }
   ],
   "skills": [

package/kits/builder/skills/builder-shape/SKILL.md

@@ -37,7 +37,7 @@ When activated:
 2. State that Builder Kit shape delegates to `idea-to-backlog` and uses `kits/builder/flows/shape.flow.json`.
 3. Gather the raw idea or current conversation context.
 4. If needed, use `design-probe`: ask one Probe/alignment question at a time before shaping. Prefer questions that clarify user outcome, constraints, non-goals, success criteria, risk, or whether bundled ideas truly belong together.
-5. Create or update the standard `.flow-agents/<slug>/<slug>--idea-to-backlog.md` artifact using the `idea-to-backlog` artifact contract.
+5. Create or update the standard `.kontourai/flow-agents/<slug>/<slug>--idea-to-backlog.md` artifact using the `idea-to-backlog` artifact contract.
 6. Add a `builder_kit_shape` or equivalent note in the artifact that links to `kits/builder/flows/shape.flow.json` and records that the product-level Builder Kit shape surface was used.
 7. Stop at `next_gate: Backlog Gate` unless the user explicitly requested GitHub issue sync.
 8. If the user asked for guided Builder Kit continuation, record the expected next step as `pull-work` after issue sync or backlog approval; otherwise record manual mode and stop.

package/kits/builder/skills/deliver/SKILL.md

@@ -20,13 +20,32 @@ Inherited from primitives:
 | tool-verifier | verify-work |
 | tool-playwright | verify-work |
 
+## Model Routing
+
+Delegates are spawned with an explicit model override resolved from
+`.datum/config.json` via `npx @kontourai/datum resolve <role> --json`
+(see `context/contracts/execution-contract.md` § Delegation: Model Routing —
+that contract is the consumption instruction, `.datum/config.json` is the
+source of truth for the mapping):
+
+| Delegate | Role |
+|---|---|
+| tool-worker | `delegate-mechanical` for fully-specified mechanical tasks, `delegate-implementation` for precisely-planned implementation, `delegate-design` when the task needs design latitude |
+| tool-planner | `delegate-design` |
+| tool-code-reviewer / tool-security-reviewer | `delegate-implementation` |
+| tool-verifier / tool-playwright | `delegate-implementation` |
+
+If datum or the config is absent, fall back to the runtime's inherited model
+and note the fallback in the session artifact.
+
 ## Orchestrator Rule
 
-You never use `read`, `glob`, `grep`, or `code` on source files. You only read/write the session file and artifact files in `.flow-agents/<slug>/`.
+You never use `read`, `glob`, `grep`, or `code` on source files. You only read/write the session file and artifact files in `.kontourai/flow-agents/<slug>/`.
 
 ## Shared Contracts
 
 Follow:
+- `context/contracts/standing-directives.md`
 - `context/contracts/artifact-contract.md`
 - `context/contracts/planning-contract.md`
 - `context/contracts/execution-contract.md`
@@ -52,9 +71,9 @@ When the repository provides `npm run workflow:sidecar --`, use it for routine w
 - `record-learning` for learning-review outcomes
 - `dogfood-pass` for Flow Agents repo changes that should record evidence, critique, optional learning, state, and handoff in one validated pass
 
-After writer updates, run `npm run workflow:validate-artifacts -- --require-sidecars .flow-agents/<slug>` when local validation is available. If the writer or validation is unavailable or blocked by sandbox policy, record the exact gap in the session artifact as `NOT_VERIFIED` instead of pretending structured state exists.
+After writer updates, run `npm run workflow:validate-artifacts -- --require-sidecars .kontourai/flow-agents/<slug>` when local validation is available. If the writer or validation is unavailable or blocked by sandbox policy, record the exact gap in the session artifact as `NOT_VERIFIED` instead of pretending structured state exists.
 
-`ensure-session` maintains `.flow-agents/current.json`. The orchestrator owns root `state.json` and `handoff.json` updates. Delegated agents must be given the workflow artifact root and should append events under `agents/<agent-id>/events.jsonl` through `record-agent-event` instead of guessing the slug or rewriting root state.
+`ensure-session` maintains `.kontourai/flow-agents/current.json`. The orchestrator is responsible for keeping root `state.json` and `handoff.json` current, but performs every such update **exclusively** through the sidecar writer (`npm run workflow:sidecar -- advance-state` for state transitions, `init-plan` for the initial plan write) — never through a direct Write/Edit tool call against the sidecar path. `config-protection.js` blocks direct tool-mediated writes to `state.json` by design; that block is expected and correct, not a bug to route around. Delegated agents must be given the workflow artifact root and should append events under `agents/<agent-id>/events.jsonl` through `record-agent-event` instead of guessing the slug or rewriting root state.
 
 ## Input
 
@@ -80,7 +99,7 @@ Direct ad hoc implementation requests that are not provider-backed backlog picku
 
 ## Session File
 
-Path: `.flow-agents/<slug>/<slug>--deliver.md`
+Path: `.kontourai/flow-agents/<slug>/<slug>--deliver.md`
 
 ```markdown
 # <Goal one-liner>
@@ -100,8 +119,8 @@ iteration: 0
 - Loop exits only after the Goal Fit Gate is fully checked or explicitly accepted
 - CRITICAL/HIGH → re-plan → execute → review → verify
 - MEDIUM/FAIL → execute fix pass → review → verify
-- Temporary planning and execution artifacts live in `.flow-agents/<slug>/`; durable feature documentation is promoted after CI/merge
-- Local runtime work stays under `.flow-agents/` and remains untracked; durable outcomes must be promoted before merge to `main`
+- Temporary planning and execution artifacts live in `.kontourai/flow-agents/<slug>/`; durable feature documentation is promoted after CI/merge
+- Local runtime work stays under `.kontourai/flow-agents/` and remains untracked; durable outcomes must be promoted before merge to `main`
 
 ## Plan
 
@@ -133,6 +152,8 @@ Use the Final Acceptance checklist from `context/contracts/delivery-contract.md`
 - iteration 2: pass — all acceptance criteria met
 ```
 
+`<branch>` is the branch recorded in `state.json`'s `branch` field (`ensure-session` derives `agent/<actor>/<slug>`; an explicit `--branch` flag overrides on a new session). `ensure-session` only records the name — creating and checking out the actual git branch/worktree remains this skill's responsibility.
+
 The `status:` values in this Markdown session file are human-readable delivery progress labels. They are not the machine-readable `state.phase` enum; structured workflow sidecars must use the canonical lifecycle values from `context/contracts/artifact-contract.md`. In particular, review-work records critique through the critique artifact/sink while the sidecar lifecycle remains in a canonical phase such as `execution`, not a `review` phase.
 
 ## Workflow
@@ -218,7 +239,7 @@ After review, verification, evidence, and Goal Fit are clean for the same diff:
 2. Publish the session trust bundle to `delivery/` so the CI trust-reconcile job can verify what the agent claimed. `record-release` (via the sidecar writer) does this automatically (best-effort). To publish or re-publish explicitly:
 
    ```bash
-   npm run workflow:sidecar -- publish-delivery .flow-agents/<slug>
+   npm run workflow:sidecar -- publish-delivery .kontourai/flow-agents/<slug>
    ```
 
    Then force-stage the trust artifacts for the delivery commit. They are gitignored
@@ -237,7 +258,7 @@ After review, verification, evidence, and Goal Fit are clean for the same diff:
 7. Record the gate claim for the Builder Kit `pr-open` step immediately after the PR is opened or updated:
 
 ```bash
-npm run workflow:sidecar -- record-gate-claim .flow-agents/<slug> \
+npm run workflow:sidecar -- record-gate-claim .kontourai/flow-agents/<slug> \
   --expectation pull-request-opened \
   --status pass \
   --summary "PR opened: <pr-url>. Linked to <work-item-ref>, implementation summary and verification evidence attached." \
@@ -253,13 +274,13 @@ Do not invoke `release-readiness` before this gate unless the user explicitly ac
 After CI passes and the work is merged or otherwise accepted:
 
 1. Update `## Final Acceptance` in the session file.
-2. Archive the working artifacts under `.flow-agents/<slug>/archive/` or keep a stable link to them.
+2. Archive the working artifacts under `.kontourai/flow-agents/<slug>/archive/` or keep a stable link to them.
 3. Record provider records, verification evidence, durable docs targets, accepted gaps, and follow-up routing in durable docs or provider records.
 4. Promote the relevant plan, decision, evidence, and usage notes into long-lived docs such as `docs/`, `README.md`, or a project decision record.
 5. Link the long-lived doc back to the provider record, archived plan artifact, or accepted evidence when useful so future readers can see why and how the feature was built.
-6. Confirm `.flow-agents/` runtime artifacts remain untracked before merge to `main`.
+6. Confirm `.kontourai/flow-agents/` runtime artifacts remain untracked before merge to `main`.
 7. **Clean up the workspace once the merge is confirmed.** First verify the merge actually happened from the provider's own record (a merge commit / `mergedAt`) — not a green check or a watcher's exit code. Then honor the `worktree_lifecycle` recorded by `pull-work` (`retain_until: pr_merged`): remove the isolated worktree (`git worktree remove <path>`) and delete the now-merged branch locally and on the remote. Never delete a branch or worktree before the merge is confirmed — a closed-but-unmerged PR or a prematurely deleted branch loses work. The task is not done while it leaves a stale worktree or merged branch behind.
-8. Hand off to `learning-review` when the delivery exposed workflow, testing, documentation, or product follow-up.
+8. Hand off to `learning-review` for terminal closeout. Clean runs record a lightweight no-correction-needed learning record (`correction.needed: false`, closed routing such as `target: "none"`); mismatches, friction, missing docs, failed gates, incidents, or product follow-up record `correction.needed: true` or `FOLLOWUP_REQUIRED` with routed prevention/follow-up. Do not skip learning just because the delivery looked clean.
 
 ### 11. Deliver