@kontourai/flow-agents 2.2.0 → 2.4.0

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

@@ -22,7 +22,7 @@ Inherited from primitives:
 
 ## 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
 
@@ -52,9 +52,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 +80,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 +100,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 +133,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 +220,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 +239,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 +255,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
 

package/kits/builder/skills/design-probe/SKILL.md

@@ -107,21 +107,21 @@ This applies whether the probe is run directly (generic) or as part of a Builder
 **Claim 1 — Pickup readiness** (probe passed, goal fit and scope confirmed):
 
 ```bash
-npm run workflow:sidecar -- record-gate-claim .flow-agents/<slug> \
+npm run workflow:sidecar -- record-gate-claim .kontourai/flow-agents/<slug> \
   --expectation pickup-probe-readiness \
   --status pass \
   --summary "Design probe passed: goal fit confirmed, scope aligned, planning readiness verified." \
-  --evidence-ref-json '{"kind":"artifact","file":".flow-agents/<slug>/<slug>--<artifact>.md","summary":"Design-probe artifact with decisions, accepted gaps, and planning readiness."}'
+  --evidence-ref-json '{"kind":"artifact","file":".kontourai/flow-agents/<slug>/<slug>--<artifact>.md","summary":"Design-probe artifact with decisions, accepted gaps, and planning readiness."}'
 ```
 
 **Claim 2 — Probe decisions captured**:
 
 ```bash
-npm run workflow:sidecar -- record-gate-claim .flow-agents/<slug> \
+npm run workflow:sidecar -- record-gate-claim .kontourai/flow-agents/<slug> \
   --expectation probe-decisions-or-accepted-gaps \
   --status pass \
   --summary "Probe decisions recorded: decisions made, unresolved questions explicit, planning readiness confirmed." \
-  --evidence-ref-json '{"kind":"artifact","file":".flow-agents/<slug>/<slug>--<artifact>.md","summary":"Design-probe artifact with decisions and accepted gaps."}'
+  --evidence-ref-json '{"kind":"artifact","file":".kontourai/flow-agents/<slug>/<slug>--<artifact>.md","summary":"Design-probe artifact with decisions and accepted gaps."}'
 ```
 
 Record both claims when shared understanding exists and the next action is `plan-work` or equivalent. Use `--status fail` when stopping due to an unresolved blocker. Skip these claims entirely when `design-probe` is used outside a Builder Kit flow (no active `builder.build` flow step in `current.json`).

package/kits/builder/skills/evidence-gate/SKILL.md

@@ -28,10 +28,13 @@ Evidence Gate is not Release Readiness. It asks whether completed work has enoug
 - Provider change / branch / check run links when available.
 - Changed-file summary.
 - Active TODOs, issue links, and release/rollback notes.
+- Cross-repo dependency/provider coverage matrix when work spans multiple
+  products, package-manager roots, generated artifact locations, install
+  scripts, CI, or shared workflow guidance.
 
 ## Artifact Contract
 
-Write or update `.flow-agents/<slug>/<slug>--evidence-gate.md` with:
+Write or update `.kontourai/flow-agents/<slug>/<slug>--evidence-gate.md` with:
 
 - `intent`: issue/brief, acceptance criteria, non-goals, risk class
 - `evidence_manifest`: command/check name, source, timestamp, result, link/output pointer
@@ -102,6 +105,13 @@ Check for process gaming or accidental drift:
 
 Sensitive areas include auth, security middleware, data migrations, CI config, deployment scripts, feature flags, test helpers, lint/type config, payment, crypto, and filesystem/network operations.
 
+For multi-repo or cross-product changes, require an explicit coverage matrix
+before a clean pass. The matrix must list every affected product/repo root and
+the status of build/test evidence, dependency/security review, provider/CI
+evidence, and any accepted gaps. A clean evidence verdict requires every
+applicable root to be covered or a human-accepted gap recorded with the reason.
+Do not infer cross-product coverage from a passing subset.
+
 ### 4. CI And Flake Assessment
 
 Use `github-cli` / `gh` when available.
@@ -179,6 +189,21 @@ Use `git` and the active `ChangeProvider` adapter when available to:
 
 If commit, push, provider change publication, or provider checks are blocked, keep the release path at `NOT_VERIFIED` or `HOLD` until the blocker is resolved or explicitly accepted by the user.
 
+### 8. Dependency And External-Audit Coverage
+
+When dependency review is in scope, evidence-gate must preserve both local
+inventory evidence and external advisory/audit evidence separately. External
+audit commands and registry/advisory lookups may disclose private dependency
+metadata; if the execution policy rejects the command or the user has not
+explicitly approved that disclosure, record the affected roots as
+`NOT_VERIFIED` for external audit and name the privacy/approval blocker.
+
+For cross-product work, a dependency/security lane can pass only when every
+applicable package-manager root has one of these recorded outcomes: `pass`,
+`fail`, `skip_no_manifest`, or an accepted `not_verified` gap. Existing
+vulnerabilities are still `FAIL` for the dependency lane unless the user
+explicitly accepts them as unrelated residual risk.
+
 ## Gate
 
 Evidence passes only when acceptance criteria, scope integrity, CI/runtime evidence, and residual risk are sufficient for the risk class.

package/kits/builder/skills/execute-plan/SKILL.md

@@ -29,7 +29,7 @@ This skill owns orchestration between waves. The contracts own artifact continui
 
 ## Input
 
-- **Plan artifact path**: path to the `-plan.md` file in `.flow-agents/<slug>/`
+- **Plan artifact path**: path to the `-plan.md` file in `.kontourai/flow-agents/<slug>/`
 - **Session file path**: the session file to update with progress
 
 ## Workflow
@@ -67,7 +67,7 @@ This skill owns orchestration between waves. The contracts own artifact continui
    - Record worker progress with `npm run workflow:sidecar -- record-agent-event --artifact-dir <artifact-dir> --agent-id <worker-id> --kind evidence --status active|done --summary ...`
 9. After all waves: set session file `status: executed` and update `state.json` / `handoff.json` with `advance-state`
 
-The orchestrator owns root `state.json` updates. Workers should receive the workflow artifact root explicitly and append agent events under that root instead of inferring the slug or rewriting shared sidecars.
+The orchestrator is responsible for keeping root `state.json` current, and performs that update **exclusively** through `npm run workflow:sidecar -- advance-state` — 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. Workers should receive the workflow artifact root explicitly and append agent events under that root instead of inferring the slug or rewriting shared sidecars.
 
 ## Pre-Fan-Out Freshness Re-Check
 

package/kits/builder/skills/fix-bug/SKILL.md

@@ -70,6 +70,8 @@ Root cause from tool-planner.
 - iteration 2: pass — bug fixed, no regressions
 ```
 
+`<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.
+
 ## Workflow
 
 ### 1. Create session file