@kontourai/flow-agents 3.7.0 → 3.8.0

package/evals/integration/test_bundle_install.sh

@@ -285,7 +285,7 @@ else
   _fail "pi install failed"
 fi
 
-USER_SKILLS_DIR="$CODEX_FULL_DEST/.codex/sk""ills/user-skill"
+USER_SKILLS_DIR="$CODEX_FULL_DEST/.agents/sk""ills/user-skill"
 mkdir -p "$CODEX_FULL_DEST/.codex/ag""ents" "$USER_SKILLS_DIR"
 printf 'name = "user-agent"\n' > "$CODEX_FULL_DEST/.codex/ag""ents/user-agent.toml"
 printf '# user skill\n' > "$USER_SKILLS_DIR/SKILL.md"
@@ -309,7 +309,7 @@ for dir in \
   "$CLAUDE_DEST/.flow-agents" \
   "$CLAUDE_DEST/.kontourai/flow-agents" \
   "$CODEX_DEST/.codex/agents" \
-  "$CODEX_DEST/.codex/skills" \
+  "$CODEX_DEST/.agents/skills" \
   "$CODEX_DEST/.flow-agents" \
   "$CODEX_DEST/.kontourai/flow-agents" \
   "$CODEX_FULL_DEST/.flow-agents" \
@@ -1069,7 +1069,7 @@ else
   _fail "packed npm consumer did not complete the public Builder workflow contract and lifecycle commands"
 fi
 
-if node - "$CODEX_FULL_DEST/.codex/skills" "$CODEX_FULL_DEST" <<'NODE'
+if node - "$CODEX_FULL_DEST/.agents/skills" "$CODEX_FULL_DEST" <<'NODE'
 const fs = require('node:fs');
 const path = require('node:path');
 const [root, installRoot] = process.argv.slice(2);
@@ -1094,7 +1094,12 @@ for (const skill of [...builder, 'agentic-engineering']) {
       throw new Error('verify-work must ship criterion-backed substantive verification evidence guidance');
     }
     const refs = [...text.matchAll(/\b(?:context|docs|kits)\/[A-Za-z0-9_./-]+\.(?:md|json)\b/g)].map((match) => match[0]);
-    for (const ref of refs) if (!fs.existsSync(path.join(installRoot, ref))) throw new Error(`${skill} has unresolved installed resource ${ref}`);
+    for (const ref of refs) {
+      const skillLocal = path.join(path.dirname(file), ref);
+      if (!fs.existsSync(skillLocal) && !fs.existsSync(path.join(installRoot, ref))) {
+        throw new Error(`${skill} has unresolved installed resource ${ref}`);
+      }
+    }
   }
 }
 NODE
@@ -1110,6 +1115,105 @@ else
   _fail "Codex full install removed unknown user files"
 fi
 
+echo ""
+echo "--- Dedicated Codex Home Universal Skills ---"
+GLOBAL_HOME="$TMPDIR_EVAL/global-home"
+GLOBAL_CODEX="$TMPDIR_EVAL/global-codex"
+GLOBAL_SKILLS="$TMPDIR_EVAL/global-agents/skills"
+mkdir -p "$GLOBAL_SKILLS/user-skill"
+printf '# user skill\n' > "$GLOBAL_SKILLS/user-skill/SKILL.md"
+GLOBAL_OUTPUT="$TMPDIR_EVAL/global-install.out"
+if HOME="$GLOBAL_HOME" CODEX_REAL_HOME="$GLOBAL_CODEX" bash "$ROOT_DIR/scripts/install-codex-home.sh" "$GLOBAL_CODEX" --skills-dir "$GLOBAL_SKILLS" >"$GLOBAL_OUTPUT"; then
+  _pass "dedicated Codex installer accepts independent hermetic runtime and skill roots"
+else
+  _fail "dedicated Codex installer failed with independent hermetic roots"
+fi
+if [[ -f "$GLOBAL_SKILLS/plan-work/SKILL.md" && -f "$GLOBAL_SKILLS/plan-work/context/contracts/planning-contract.md" && -f "$GLOBAL_SKILLS/user-skill/SKILL.md" && ! -e "$GLOBAL_CODEX/skills/plan-work" ]]; then
+  _pass "global install uses self-contained universal skills and preserves user skills"
+else
+  _fail "global universal skill layout, resource closure, or user preservation is wrong"
+fi
+if rg -q 'Installed Flow Agents into Codex home at .+/global-codex$' "$GLOBAL_OUTPUT" && rg -q 'Installed portable skills at .+/global-agents/skills$' "$GLOBAL_OUTPUT"; then
+  _pass "installer reports both runtime and portable skill destinations"
+else
+  _fail "installer output does not report both destinations"
+fi
+if HOME="$GLOBAL_HOME" CODEX_REAL_HOME="$GLOBAL_CODEX" bash "$ROOT_DIR/scripts/install-codex-home.sh" "$GLOBAL_CODEX" --skills-dir "$GLOBAL_SKILLS" >/dev/null; then
+  _pass "split-root reinstall is idempotent"
+else
+  _fail "split-root reinstall is not idempotent"
+fi
+
+CONFLICT_CODEX="$TMPDIR_EVAL/conflict-codex"
+CONFLICT_SKILLS="$TMPDIR_EVAL/conflict-agents/skills"
+mkdir -p "$CONFLICT_SKILLS/plan-work" "$CONFLICT_CODEX/skills/plan-work" "$CONFLICT_CODEX/.flow-agents"
+printf '# user collision\n' > "$CONFLICT_SKILLS/plan-work/SKILL.md"
+cp "$ROOT_DIR/dist/codex/.agents/skills/plan-work/SKILL.md" "$CONFLICT_CODEX/skills/plan-work/SKILL.md"
+printf 'runtime sentinel\n' > "$CONFLICT_CODEX/runtime-sentinel"
+node - "$CONFLICT_CODEX" <<'NODE'
+const fs=require('node:fs'), path=require('node:path'), crypto=require('node:crypto'); const root=process.argv[2];
+const rel='skills' + '/plan-work/SKILL.md'; const sha256=crypto.createHash('sha256').update(fs.readFileSync(path.join(root,rel))).digest('hex');
+fs.writeFileSync(path.join(root,'.flow-agents/codex-install-manifest.json'), JSON.stringify({schema_version:'1.0',files:[{path:rel,sha256}]},null,2)+'\n');
+NODE
+CONFLICT_RUNTIME_BEFORE="$(shasum -a 256 "$CONFLICT_CODEX/skills/plan-work/SKILL.md" "$CONFLICT_CODEX/.flow-agents/codex-install-manifest.json" "$CONFLICT_CODEX/runtime-sentinel")"
+if HOME="$GLOBAL_HOME" CODEX_REAL_HOME="$CONFLICT_CODEX" bash "$ROOT_DIR/scripts/install-codex-home.sh" "$CONFLICT_CODEX" --skills-dir "$CONFLICT_SKILLS" >/dev/null 2>&1; then
+  _fail "global installer overwrote a user-owned skill collision"
+else
+  CONFLICT_RUNTIME_AFTER="$(shasum -a 256 "$CONFLICT_CODEX/skills/plan-work/SKILL.md" "$CONFLICT_CODEX/.flow-agents/codex-install-manifest.json" "$CONFLICT_CODEX/runtime-sentinel")"
+  if [[ "$(cat "$CONFLICT_SKILLS/plan-work/SKILL.md")" == "# user collision" && "$CONFLICT_RUNTIME_BEFORE" == "$CONFLICT_RUNTIME_AFTER" && ! -e "$CONFLICT_SKILLS/.flow-agents" ]]; then
+    _pass "cross-root collision preflight preserves universal content, legacy skill, runtime sentinel, and manifests"
+  else
+    _fail "cross-root collision failure partially mutated an install root"
+  fi
+fi
+
+SYMLINK_TARGET="$TMPDIR_EVAL/symlink-target"
+SYMLINK_PARENT="$TMPDIR_EVAL/symlink-parent"
+mkdir -p "$SYMLINK_TARGET" "$SYMLINK_PARENT"
+ln -s "$SYMLINK_TARGET" "$SYMLINK_PARENT/catalog"
+if HOME="$GLOBAL_HOME" CODEX_REAL_HOME="$TMPDIR_EVAL/symlink-codex" bash "$ROOT_DIR/scripts/install-codex-home.sh" "$TMPDIR_EVAL/symlink-codex" --skills-dir "$SYMLINK_PARENT/catalog/skills" >/dev/null 2>&1; then
+  _fail "global installer followed a symlinked skill destination component"
+else
+  [[ ! -e "$SYMLINK_TARGET/skills" ]] && _pass "global installer refuses symlinked skill destination components without mutation" || _fail "symlink rejection mutated its target"
+fi
+
+SOURCE_ANCESTOR="$(dirname "$ROOT_DIR")"
+SOURCE_DESCENDANT="$ROOT_DIR/.fa-550-forbidden-skills"
+for unsafe in / "$SOURCE_ANCESTOR" "$SOURCE_DESCENDANT"; do
+  rm -rf "$SOURCE_DESCENDANT"
+  if HOME="$GLOBAL_HOME" CODEX_REAL_HOME="$TMPDIR_EVAL/unsafe-codex" bash "$ROOT_DIR/scripts/install-codex-home.sh" "$TMPDIR_EVAL/unsafe-codex" --skills-dir "$unsafe" >/dev/null 2>&1; then
+    _fail "global installer accepted unsafe skill namespace root: $unsafe"
+  elif [[ ! -e "$SOURCE_DESCENDANT" && ! -e "$TMPDIR_EVAL/unsafe-codex" ]]; then
+    _pass "unsafe root/overlap rejection occurs before destination mutation: $unsafe"
+  else
+    _fail "unsafe root/overlap rejection left destination mutations: $unsafe"
+  fi
+done
+
+MIGRATE_CODEX="$TMPDIR_EVAL/migrate-codex"
+MIGRATE_SKILLS="$TMPDIR_EVAL/migrate-agents/skills"
+LEGACY_SKILLS_SEGMENT="skills"
+LEGACY_USER_DIR="$MIGRATE_CODEX/$LEGACY_SKILLS_SEGMENT/user-legacy"
+mkdir -p "$MIGRATE_CODEX/skills/plan-work" "$LEGACY_USER_DIR" "$MIGRATE_CODEX/.flow-agents"
+cp "$ROOT_DIR/dist/codex/.agents/skills/plan-work/SKILL.md" "$MIGRATE_CODEX/skills/plan-work/SKILL.md"
+printf '# modified legacy user content\n' > "$LEGACY_USER_DIR/SKILL.md"
+node - "$MIGRATE_CODEX" <<'NODE'
+const fs = require('node:fs'); const path = require('node:path'); const crypto = require('node:crypto');
+const root = process.argv[2];
+const rels = ['skills' + '/plan-work/SKILL.md', 'skills' + '/user-legacy/SKILL.md'];
+const files = rels.map(p => ({path:p, sha256:crypto.createHash('sha256').update(fs.readFileSync(path.join(root,p))).digest('hex')}));
+fs.writeFileSync(path.join(root,'.flow-agents/codex-install-manifest.json'), JSON.stringify({schema_version:'1.0',files},null,2)+'\n');
+fs.appendFileSync(path.join(root,'skills' + '/user-legacy/SKILL.md'), 'kept modification\n');
+NODE
+if HOME="$GLOBAL_HOME" CODEX_REAL_HOME="$MIGRATE_CODEX" bash "$ROOT_DIR/scripts/install-codex-home.sh" "$MIGRATE_CODEX" --skills-dir "$MIGRATE_SKILLS" >/dev/null 2>"$TMPDIR_EVAL/migrate.err" \
+  && [[ ! -e "$MIGRATE_CODEX/skills/plan-work/SKILL.md" ]] \
+  && rg -q 'kept modification' "$LEGACY_USER_DIR/SKILL.md" \
+  && [[ -f "$MIGRATE_SKILLS/plan-work/SKILL.md" ]]; then
+  _pass "legacy migration removes unchanged owned skills and preserves modified legacy content"
+else
+  _fail "legacy Flow Agents skill migration was destructive or incomplete"
+fi
+
 OPENCODE_AGENTS_DIR="$OPENCODE_FULL_DEST/.opencode/agents"
 if [[ -f "$OPENCODE_AGENTS_DIR/tool-planner.md" && -f "$OPENCODE_AGENTS_DIR/dev.md" ]]; then
   _pass "opencode full install ships the complete agent base"

package/evals/integration/test_bundle_lifecycle.sh

@@ -164,7 +164,7 @@ OPENCODE_UPGRADE="$TMPDIR_EVAL/upgrade-opencode"
 # Touch a marker into skill files in the COPIES (not dist/ originals)
 UPGRADE_MARKER="# flow-agents-upgrade-test-marker"
 CLAUDE_SKILL_FILE="$CLAUDE_BUNDLE_COPY/.claude/skills/plan-work/SKILL.md"
-CODEX_SKILL_FILE="$CODEX_BUNDLE_COPY/.codex/skills/plan-work/SKILL.md"
+CODEX_SKILL_FILE="$CODEX_BUNDLE_COPY/.agents/skills/plan-work/SKILL.md"
 OPENCODE_SKILL_FILE="$OPENCODE_BUNDLE_COPY/.opencode/skills/plan-work/SKILL.md"
 
 if [[ -f "$CLAUDE_SKILL_FILE" ]]; then
@@ -191,12 +191,10 @@ else
   _fail "claude-code upgrade: skill change did not propagate to workspace"
 fi
 
-if [[ -f "$CODEX_SKILL_FILE" ]] && grep -qF "$UPGRADE_MARKER" "$CODEX_UPGRADE/.codex/skills/plan-work/SKILL.md" 2>/dev/null; then
+if [[ -f "$CODEX_SKILL_FILE" ]] && grep -qF "$UPGRADE_MARKER" "$CODEX_UPGRADE/.agents/skills/plan-work/SKILL.md" 2>/dev/null; then
   _pass "codex upgrade: modified skill file propagated to workspace"
-elif [[ ! -f "$CODEX_SKILL_FILE" ]]; then
-  _pass "codex upgrade: skill file not in bundle (skipped)"
 else
-  _fail "codex upgrade: skill change did not propagate to workspace"
+  _fail "codex upgrade: required universal skill missing or change did not propagate"
 fi
 
 if [[ -f "$OPENCODE_SKILL_FILE" ]] && grep -qF "$UPGRADE_MARKER" "$OPENCODE_UPGRADE/.opencode/skills/plan-work/SKILL.md" 2>/dev/null; then
@@ -246,7 +244,7 @@ echo '{"custom":"data"}' > "$OPENCODE_USER/.kontourai/flow-agents/my-session/sta
 
 # Modify an installed skill file to simulate user edits
 CLAUDE_INSTALLED_SKILL="$CLAUDE_USER/.claude/skills/plan-work/SKILL.md"
-CODEX_INSTALLED_SKILL="$CODEX_USER/.codex/skills/plan-work/SKILL.md"
+CODEX_INSTALLED_SKILL="$CODEX_USER/.agents/skills/plan-work/SKILL.md"
 OPENCODE_INSTALLED_SKILL="$OPENCODE_USER/.opencode/skills/plan-work/SKILL.md"
 
 USER_EDIT_MARKER="# USER EDIT - should be overwritten by re-install"

package/evals/integration/test_install_merge.sh

@@ -22,6 +22,10 @@ set -euo pipefail
 
 ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
 TMPDIR_EVAL="$(mktemp -d /tmp/install-merge.XXXXXX)"
+export HOME="$TMPDIR_EVAL/hermetic-home"
+export FLOW_AGENTS_SKILLS_DIR="$TMPDIR_EVAL/hermetic-universal/skills"
+mkdir -p "$HOME/.agents" "$FLOW_AGENTS_SKILLS_DIR"
+printf 'installer tests must not replace this file\n' > "$HOME/.agents/ambient-sentinel"
 pass=0
 fail=0
 
@@ -1138,7 +1142,8 @@ echo ""
 echo "--- CH4: codex-home preserves user config, profiles, hooks, local kit state, and user skills ---"
 
 CH4_DEST="$TMPDIR_EVAL/codex-home-ch4"
-mkdir -p "$CH4_DEST/kits/local/repositories/user-kit" "$CH4_DEST/sk""ills/user-owned-skill" "$CH4_DEST/ag""ents"
+CH4_SKILLS="$TMPDIR_EVAL/codex-home-ch4-universal-skills"
+mkdir -p "$CH4_DEST/kits/local/repositories/user-kit" "$CH4_SKILLS/user-owned-skill" "$CH4_DEST/ag""ents"
 
 CH4_GENERIC_DIRS=(agent-cards build context docs evals integrations packaging powers prompts schemas scripts kits)
 for CH4_DIR in "${CH4_GENERIC_DIRS[@]}"; do
@@ -1197,14 +1202,14 @@ JSON
 cat > "$CH4_DEST/kits/local/repositories/user-kit/kit.json" << 'JSON'
 {"id":"user-kit","name":"User Kit"}
 JSON
-cat > "$CH4_DEST/sk""ills/user-owned-skill/SKILL.md" << 'EOF_SKILL'
+cat > "$CH4_SKILLS/user-owned-skill/SKILL.md" << 'EOF_SKILL'
 # User Owned Skill
 EOF_SKILL
 cat > "$CH4_DEST/ag""ents/user-owned-agent.toml" << 'EOF_AGENT'
 name = "user-owned-agent"
 EOF_AGENT
 
-CODEX_REAL_HOME="$TMPDIR_EVAL/fake-real-codex" bash "$ROOT_DIR/scripts/install-codex-home.sh" "$CH4_DEST" >/dev/null 2>&1
+CODEX_REAL_HOME="$TMPDIR_EVAL/fake-real-codex" FLOW_AGENTS_SKILLS_DIR="$CH4_SKILLS" bash "$ROOT_DIR/scripts/install-codex-home.sh" "$CH4_DEST" >/dev/null 2>&1
 
 if grep -q 'user-model' "$CH4_DEST/config.toml" \
   && grep -q 'user-profile-model' "$CH4_DEST/custom.config.toml" \
@@ -1243,10 +1248,10 @@ else
   _fail "CH4: kits/local registry or repository was removed"
 fi
 
-if [[ -f "$CH4_DEST/sk""ills/search-first/SKILL.md" && -f "$CH4_DEST/sk""ills/plan-work/SKILL.md" && -f "$CH4_DEST/sk""ills/user-owned-skill/SKILL.md" ]]; then
-  _pass "CH4: root, Builder Kit workflow, and user-owned skills coexist in flattened Codex skills"
+if [[ -f "$CH4_SKILLS/search-first/SKILL.md" && -f "$CH4_SKILLS/plan-work/SKILL.md" && -f "$CH4_SKILLS/user-owned-skill/SKILL.md" ]]; then
+  _pass "CH4: root, Builder Kit workflow, and user-owned skills coexist in universal Codex skills"
 else
-  _fail "CH4: root skill, Builder Kit workflow skill, or user-owned skill missing from flattened Codex skills"
+  _fail "CH4: root skill, Builder Kit workflow skill, or user-owned skill missing from universal Codex skills"
 fi
 
 if [[ -f "$CH4_DEST/scripts/install-merge.js" && -f "$CH4_DEST/build/src/cli/kit.js" && -f "$CH4_DEST/ag""ents/tool-worker.toml" && -f "$CH4_DEST/ag""ents/user-owned-agent.toml" && -f "$CH4_DEST/hooks.json" ]] \
@@ -1272,7 +1277,7 @@ else
   _fail "CH4: installed scripts/kit.js could not run with installed build bundle"
 fi
 
-CODEX_REAL_HOME="$TMPDIR_EVAL/fake-real-codex" bash "$ROOT_DIR/scripts/install-codex-home.sh" "$CH4_DEST" >/dev/null 2>&1
+CODEX_REAL_HOME="$TMPDIR_EVAL/fake-real-codex" FLOW_AGENTS_SKILLS_DIR="$CH4_SKILLS" bash "$ROOT_DIR/scripts/install-codex-home.sh" "$CH4_DEST" >/dev/null 2>&1
 CH4_GENERIC_PRESERVED=1
 for CH4_DIR in "${CH4_GENERIC_DIRS[@]}"; do
   [[ "$(cat "$CH4_DEST/$CH4_DIR/user-owned.txt" 2>/dev/null)" == "user-owned-$CH4_DIR" ]] || CH4_GENERIC_PRESERVED=0
@@ -1288,7 +1293,7 @@ echo ""
 # ─── codex-home: CH5: destination symlink containment ───────────────────────
 echo "--- CH5: codex-home refuses managed destination symlinks ---"
 
-for CH5_REL in scripts kits sk""ills hooks.json; do
+for CH5_REL in scripts kits hooks.json; do
   CH5_DEST="$TMPDIR_EVAL/codex-home-ch5-${CH5_REL//\//-}"
   CH5_OUTSIDE="$TMPDIR_EVAL/codex-home-ch5-outside-${CH5_REL//\//-}"
   mkdir -p "$CH5_DEST" "$CH5_OUTSIDE"
@@ -1680,6 +1685,11 @@ echo ""
 
 echo ""
 echo "==========================="
+if [[ "$(cat "$HOME/.agents/ambient-sentinel" 2>/dev/null)" == "installer tests must not replace this file" ]]; then
+  _pass "dedicated Codex installer calls remain inside hermetic universal roots"
+else
+  _fail "dedicated Codex installer calls mutated the isolated default-home sentinel"
+fi
 total=$((pass + fail))
 echo "Results: ${pass}/${total} passed, ${fail} failed"
 [[ "$fail" -gt 0 ]] && exit 1

package/evals/integration/test_public_workflow_cli.sh

@@ -160,15 +160,21 @@ pass "status is canonical and byte-read-only"
 
 FLOW_MANIFEST="$CONSUMER/.kontourai/flow/runs/acme-widgets-101/evidence/manifest.json"
 BEFORE_EVIDENCE="$(node -p "JSON.parse(require('fs').readFileSync('$FLOW_MANIFEST')).evidence.length")"
-run_candidate evidence --session-dir "$RELEASE_SESSION" --expectation pickup-probe-readiness --status not_verified --summary "Consumer fixture intentionally leaves this claim unverified." --json >/dev/null
+PARTIAL_EVIDENCE="$(run_candidate evidence --session-dir "$RELEASE_SESSION" --expectation pickup-probe-readiness --status not_verified --summary "Consumer fixture intentionally leaves this claim unverified." --json)"
 AFTER_EVIDENCE="$(node -p "JSON.parse(require('fs').readFileSync('$FLOW_MANIFEST')).evidence.length")"
-[[ "$AFTER_EVIDENCE" -eq $((BEFORE_EVIDENCE + 1)) ]] || fail "evidence invocation did not attach exactly once"
-pass "evidence records and synchronizes exactly once"
+[[ "$AFTER_EVIDENCE" -eq "$BEFORE_EVIDENCE" ]] || fail "partial evidence changed the canonical manifest"
+node -e 'const r=JSON.parse(process.argv[1]);if(r.attached!==false||r.awaiting_evidence!==true||r.current_step!=="design-probe")process.exit(1)' "$PARTIAL_EVIDENCE" || fail "partial evidence did not report an explicit awaiting-evidence result"
+pass "partial evidence records locally without evaluation or canonical attachment"
 
 PULL_REPORT="$RELEASE_SESSION/$(basename "$RELEASE_SESSION")--pull-work.md"
 PULL_REPORT_REF="{\"kind\":\"artifact\",\"file\":\"$PULL_REPORT\",\"summary\":\"Concrete selected-work and probe report.\"}"
-run_candidate evidence --session-dir "$RELEASE_SESSION" --expectation pickup-probe-readiness --status pass --summary "Complete the consumer readiness expectation after exercising NOT_VERIFIED." --evidence-ref-json "$PULL_REPORT_REF" --json >/dev/null
-run_candidate evidence --session-dir "$RELEASE_SESSION" --expectation probe-decisions-or-accepted-gaps --status pass --summary "Complete the consumer probe gate." --evidence-ref-json "$PULL_REPORT_REF" --json >/dev/null
+READINESS_PARTIAL="$(run_candidate evidence --session-dir "$RELEASE_SESSION" --expectation pickup-probe-readiness --status pass --summary "Complete the consumer readiness expectation after exercising NOT_VERIFIED." --evidence-ref-json "$PULL_REPORT_REF" --json)"
+node -e 'const r=JSON.parse(process.argv[1]);if(r.attached!==false||r.awaiting_evidence!==true||r.current_step!=="design-probe")process.exit(1)' "$READINESS_PARTIAL" || fail "first passing member of a multi-expectation gate did not remain pending"
+PROBE_COMPLETE="$(run_candidate evidence --session-dir "$RELEASE_SESSION" --expectation probe-decisions-or-accepted-gaps --status pass --summary "Complete the consumer probe gate." --evidence-ref-json "$PULL_REPORT_REF" --json)"
+node -e 'const r=JSON.parse(process.argv[1]);if(r.attached!==true||r.awaiting_evidence!==false||r.current_step!=="plan")process.exit(1)' "$PROBE_COMPLETE" || fail "complete multi-expectation gate did not attach and advance exactly once"
+AFTER_COMPLETE_EVIDENCE="$(node -p "JSON.parse(require('fs').readFileSync('$FLOW_MANIFEST')).evidence.length")"
+[[ "$AFTER_COMPLETE_EVIDENCE" -eq $((BEFORE_EVIDENCE + 1)) ]] || fail "complete multi-expectation gate did not attach exactly once"
+pass "multi-expectation evidence attaches atomically only when complete"
 seed_pull_work acme/widgets#104
 run_candidate_as poison-pointer start --artifact-root "$ARTIFACT_ROOT" --flow builder.build --work-item acme/widgets#104 --assignment-provider local-file --summary "Poison global pointer fixture" >/dev/null
 node - "$ARTIFACT_ROOT" "$(basename "$RELEASE_SESSION")" <<'NODE'

package/evals/static/test_universal_bundles.sh

@@ -10,7 +10,7 @@ pass=0
 fail=0
 
 cleanup() {
-  rm -rf "$REPRO_FIRST_DIR" "$REPRO_SECOND_DIR" "$ROOT_DIR/kits/zzz-collision-eval-probe"
+  rm -rf "$REPRO_FIRST_DIR" "$REPRO_SECOND_DIR" "$ROOT_DIR/kits/zzz-collision-eval-probe" "${MISSING_SKILL_DIR:-}"
 }
 trap cleanup EXIT
 
@@ -65,6 +65,49 @@ for dir in "$DIST_DIR/kiro" "$DIST_DIR/claude-code" "$DIST_DIR/codex" "$DIST_DIR
   fi
 done
 
+if [[ -d "$DIST_DIR/codex/.agents/skills/plan-work" && ! -e "$DIST_DIR/codex/.codex/skills" ]]; then
+  _pass "Codex exports portable skills only in the universal .agents catalog"
+else
+  _fail "Codex portable skills are not rooted exclusively at .agents/skills"
+fi
+
+if node - "$DIST_DIR/codex/.agents/skills" <<'NODE'
+const fs = require("node:fs");
+const path = require("node:path");
+const root = process.argv[2];
+const pattern = /(?:^|[`("'\s])(context\/contracts\/[A-Za-z0-9._/-]+\.md)(?=$|[`),"'\s])/gm;
+for (const name of fs.readdirSync(root)) {
+  const skill = path.join(root, name);
+  const file = path.join(skill, "SKILL.md");
+  if (!fs.existsSync(file)) continue;
+  for (const match of fs.readFileSync(file, "utf8").matchAll(pattern)) {
+    const resolved = path.resolve(skill, match[1]);
+    if (!resolved.startsWith(`${path.resolve(skill)}${path.sep}`) || !fs.existsSync(resolved)) throw new Error(`${name}: ${match[1]}`);
+  }
+}
+NODE
+then
+  _pass "Codex skill-local instruction resources resolve inside each package"
+else
+  _fail "Codex skill-local instruction resource closure failed"
+fi
+
+MISSING_SKILL_DIR="$ROOT_DIR/${SKILLS_SEGMENT:-skills}/zzz-missing-resource-probe"
+MISSING_CONTRACT="${CONTEXT_SEGMENT:-context}/contracts/definitely-missing.md"
+mkdir -p "$MISSING_SKILL_DIR"
+printf '%s\n' '# Probe' '' "Read \`$MISSING_CONTRACT\`." > "$MISSING_SKILL_DIR/SKILL.md"
+if (cd "$ROOT_DIR" && npm run build:bundles >/tmp/missing-skill-resource.stdout 2>/tmp/missing-skill-resource.stderr); then
+  _fail "bundle generation accepted a missing skill instruction resource"
+else
+  if rg -q "skill 'zzz-missing-resource-probe': missing local resource '$MISSING_CONTRACT'" /tmp/missing-skill-resource.stderr; then
+    _pass "bundle generation rejects missing skill resources with actionable diagnostics"
+  else
+    _fail "missing skill resource failure did not name its skill and path"
+  fi
+fi
+rm -rf "$MISSING_SKILL_DIR"
+(cd "$ROOT_DIR" && npm run build:bundles >/dev/null)
+
 source_agents=$(find "$ROOT_DIR/agents" -maxdepth 1 -name '*.json' | wc -l | tr -d ' ')
 codex_excluded_agents=$(node - "$ROOT_DIR/packaging/manifest.json" <<'NODE'
 const fs = require("node:fs");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontourai/flow-agents",
-  "version": "3.7.0",
+  "version": "3.8.0",
   "description": "Flow Agents — a Kontour product that applies Flow and Veritas discipline as a portable process layer inside the agent tools you already use: Claude Code, Codex, Kiro, opencode, pi, and GitHub Actions — with framework adapters (AWS Strands preview) on the same policy-engine contract.",
   "keywords": [
     "agents",

package/packaging/README.md

@@ -19,7 +19,7 @@ For the full source/generated/runtime inventory, see [Repository Structure](../d
 
 - `dist/kiro/` keeps native Kiro JSON agents and rewrites path-bound config through the install token.
 - `dist/claude-code/` exports `.claude/agents/*.md` and `.claude/skills/*/SKILL.md`.
-- `dist/codex/` exports `.codex/agents/*.toml`, `.codex/skills/*/SKILL.md`, and generated profile config for operating intents such as `builder` and `personal`.
+- `dist/codex/` exports Codex-only agents and profiles beneath `.codex/`, and portable, self-contained skills beneath the universal `.agents/skills/` catalog.
 
 All targets also receive shared canonical directories where supported: `context/`, `powers/`, `prompts/`, `scripts/`, and `evals/`.
 

package/scripts/README.md

@@ -113,7 +113,7 @@ prompting. Add `--allow-network` to probe a non-local HTTPS Console endpoint.
 
 ## Install And Repo Utilities
 
-- `install-codex-home.sh`: installs the generated Codex bundle into `CODEX_HOME`, or `~/.codex` when `CODEX_HOME` is unset. A positional destination argument is the explicit override for isolated homes and tests.
+- `install-codex-home.sh`: installs Codex runtime assets into `CODEX_HOME` (or `~/.codex`) and portable skills into `$HOME/.agents/skills`. Use `--skills-dir PATH` or `FLOW_AGENTS_SKILLS_DIR` to select a hermetic or advanced-user skill catalog independently of the positional runtime destination. The installer reports both resolved roots, preserves user-owned files, migrates only unchanged Flow Agents-owned legacy skills, and refuses symlink destinations rather than creating a compatibility symlink.
 - `setup-repo-hooks.sh`: configures this clone's Git hook path.
 - `check-content-boundary.cjs`, `detect-tools.sh`, `discover-agents.sh`, `git-status.sh`: repo-local helper commands.
 - `context-budget/` and `statusline/`: specialized support tooling copied into bundles where needed.

package/scripts/install-codex-home.sh

@@ -16,14 +16,21 @@ Options:
   --console-token-file PATH
                           Read Console telemetry bearer token from a file.
   --console-tenant ID     Persist Console tenant identifier.
+  --skills-dir PATH       Install portable skills here (default: $HOME/.agents/skills).
 EOF
 }
 
 DEST="${CODEX_HOME:-$HOME/.codex}"
+SKILLS_DIR="${FLOW_AGENTS_SKILLS_DIR:-$HOME/.agents/skills}"
 DEST_SET=0
 CONSOLE_CONFIG_ARGS=()
 while [[ $# -gt 0 ]]; do
   case "$1" in
+    --skills-dir)
+      [[ $# -ge 2 ]] || { echo "install-codex-home.sh: $1 requires a value" >&2; exit 2; }
+      SKILLS_DIR="$2"
+      shift 2
+      ;;
     --telemetry-sink|--telemetry-sinks|--console-url|--console-endpoint|--console-endpoint-url|--console-token-file|--console-tenant|--console-tenant-id)
       [[ $# -ge 2 ]] || { echo "install-codex-home.sh: $1 requires a value" >&2; exit 2; }
       CONSOLE_CONFIG_ARGS+=("$1" "$2")
@@ -69,9 +76,26 @@ NODE
 }
 
 [[ ! -L "$DEST" ]] || { echo "install-codex-home.sh: refusing symlink destination root: $DEST" >&2; exit 1; }
+[[ ! -L "$SKILLS_DIR" ]] || { echo "install-codex-home.sh: refusing symlink skills destination root: $SKILLS_DIR" >&2; exit 1; }
 ROOT_REAL="$(canonicalize_path "$ROOT_DIR")"
 BUNDLE_SOURCE_REAL="$(canonicalize_path "$ROOT_DIR/dist/codex")"
 DEST_REAL="$(canonicalize_path "$DEST")"
+SKILLS_DIR_REAL="$(canonicalize_path "$SKILLS_DIR")"
+if ! node - "$SKILLS_DIR" <<'NODE'
+const fs = require("node:fs"); const path = require("node:path");
+const absolute = path.resolve(process.argv[2]);
+let current = path.parse(absolute).root;
+for (const part of absolute.slice(current.length).split(path.sep).filter(Boolean)) {
+  current = path.join(current, part);
+  // macOS exposes /tmp as the system-managed /private/tmp symlink. Treat that
+  // mount alias as trusted while rejecting caller-controlled components.
+  if (current !== "/tmp" && fs.existsSync(current) && fs.lstatSync(current).isSymbolicLink()) process.exit(1);
+}
+NODE
+then
+  echo "install-codex-home.sh: refusing symlink component in skills destination: $SKILLS_DIR" >&2
+  exit 1
+fi
 REAL_CODEX_HOME_REAL="$(canonicalize_path "$REAL_CODEX_HOME")"
 case "$DEST_REAL/" in
   "$ROOT_REAL/"*|"$BUNDLE_SOURCE_REAL/"*)
@@ -85,6 +109,17 @@ case "$ROOT_REAL/" in
     exit 1
     ;;
 esac
+case "$SKILLS_DIR_REAL/" in
+  "$ROOT_REAL/"*|"$BUNDLE_SOURCE_REAL/"*) echo "install-codex-home.sh: skills destination overlaps Flow Agents source: $SKILLS_DIR_REAL" >&2; exit 1 ;;
+esac
+case "$ROOT_REAL/" in
+  "$SKILLS_DIR_REAL/"*) echo "install-codex-home.sh: Flow Agents source overlaps skills destination: $SKILLS_DIR_REAL" >&2; exit 1 ;;
+esac
+case "$BUNDLE_SOURCE_REAL/" in
+  "$SKILLS_DIR_REAL/"*) echo "install-codex-home.sh: generated bundle source overlaps skills destination: $SKILLS_DIR_REAL" >&2; exit 1 ;;
+esac
+SKILLS_PATH_ROOT="$(node -e 'process.stdout.write(require("node:path").parse(process.argv[1]).root)' "$SKILLS_DIR_REAL")"
+[[ "$SKILLS_DIR_REAL" != "$SKILLS_PATH_ROOT" ]] || { echo "install-codex-home.sh: refusing filesystem-root skills destination: $SKILLS_DIR_REAL" >&2; exit 1; }
 
 if command -v npm >/dev/null 2>&1; then
   (cd "$ROOT_DIR" && FLOW_AGENTS_EXPORT_DIAGNOSTICS=0 npm run build:bundles --silent >/dev/null)
@@ -93,10 +128,6 @@ else
   exit 1
 fi
 
-mkdir -p "$DEST"
-DEST="$(cd "$DEST" && pwd -P)"
-DEST_REAL="$DEST"
-
 assert_safe_dest_path() {
   local rel="$1"
   local current="$DEST"
@@ -122,22 +153,17 @@ assert_safe_dest_path() {
   esac
 }
 
-# Stash the user's existing hooks.json (if any), so the merge step below can
-# preserve user hooks across installs while replacing Flow Agents-managed groups.
 FA_USER_HOOKS_STASH=""
-assert_safe_dest_path "hooks.json"
-if [[ -f "$DEST/hooks.json" ]]; then
-  FA_USER_HOOKS_STASH="$(mktemp /tmp/fa-user-hooks.XXXXXX.json)"
-  cp "$DEST/hooks.json" "$FA_USER_HOOKS_STASH"
-fi
 
 # A real Codex home can contain user-owned files in every shared directory.
 # Prepare an exact Flow Agents overlay, then synchronize only files recorded in
 # the ownership manifest. The synchronizer never uses directory-wide --delete:
 # it removes only unchanged files from its prior manifest and refuses collisions.
 FA_OWNED_OVERLAY="$(mktemp -d /tmp/fa-codex-overlay.XXXXXX)"
+FA_SKILLS_OVERLAY="$(mktemp -d /tmp/fa-codex-skills-overlay.XXXXXX)"
 cleanup_install_temps() {
   rm -rf "$FA_OWNED_OVERLAY"
+  rm -rf "$FA_SKILLS_OVERLAY"
   [[ -z "${FA_USER_HOOKS_STASH:-}" ]] || rm -f "$FA_USER_HOOKS_STASH"
 }
 trap cleanup_install_temps EXIT
@@ -157,22 +183,14 @@ for managed_dir in \
   scripts
 do
   if [[ -d "$ROOT_DIR/dist/codex/$managed_dir" ]]; then
-    assert_safe_dest_path "$managed_dir"
     mkdir -p "$FA_OWNED_OVERLAY/$managed_dir"
     rsync -a "$ROOT_DIR/dist/codex/$managed_dir/" "$FA_OWNED_OVERLAY/$managed_dir/"
   fi
 done
 
-# Skills are user-extensible in a real Codex home. Merge both bundle skill
-# layers into the flattened destination without deleting user-owned skills.
-if [[ -d "$ROOT_DIR/dist/codex/skills" ]]; then
-  mkdir -p "$FA_OWNED_OVERLAY/skills"
-  rsync -a "$ROOT_DIR/dist/codex/skills/" "$FA_OWNED_OVERLAY/skills/"
-fi
-
-if [[ -d "$ROOT_DIR/dist/codex/.codex/skills" ]]; then
-  mkdir -p "$FA_OWNED_OVERLAY/skills"
-  rsync -a "$ROOT_DIR/dist/codex/.codex/skills/" "$FA_OWNED_OVERLAY/skills/"
+# Portable skills use Codex's universal catalog, independently of CODEX_HOME.
+if [[ -d "$ROOT_DIR/dist/codex/.agents/skills" ]]; then
+  rsync -a "$ROOT_DIR/dist/codex/.agents/skills/" "$FA_SKILLS_OVERLAY/"
 fi
 
 if [[ -d "$ROOT_DIR/dist/codex/kits" ]]; then
@@ -193,10 +211,31 @@ for bundle_file in README.md console.telemetry.json install.sh; do
   fi
 done
 
-assert_safe_dest_path ".flow-agents/codex-install-manifest.json"
+# Check both destinations with the exact synchronizer before either can mutate.
+node "$ROOT_DIR/scripts/install-owned-files.js" \
+  --check "$FA_SKILLS_OVERLAY" "$SKILLS_DIR_REAL" ".flow-agents/codex-universal-skills-install-manifest.json"
+node "$ROOT_DIR/scripts/install-owned-files.js" \
+  --check "$FA_OWNED_OVERLAY" "$DEST_REAL" ".flow-agents/codex-install-manifest.json"
+
+mkdir -p "$SKILLS_DIR"
+SKILLS_DIR="$(cd "$SKILLS_DIR" && pwd -P)"
+node "$ROOT_DIR/scripts/install-owned-files.js" \
+  "$FA_SKILLS_OVERLAY" "$SKILLS_DIR" ".flow-agents/codex-universal-skills-install-manifest.json"
+
+mkdir -p "$DEST"
+DEST="$(cd "$DEST" && pwd -P)"
+DEST_REAL="$DEST"
 node "$ROOT_DIR/scripts/install-owned-files.js" \
   "$FA_OWNED_OVERLAY" "$DEST" ".flow-agents/codex-install-manifest.json"
 
+# Stash the user's existing hooks.json (if any), so the merge step below can
+# preserve user hooks across installs while replacing Flow Agents-managed groups.
+assert_safe_dest_path "hooks.json"
+if [[ -f "$DEST/hooks.json" ]]; then
+  FA_USER_HOOKS_STASH="$(mktemp /tmp/fa-user-hooks.XXXXXX.json)"
+  cp "$DEST/hooks.json" "$FA_USER_HOOKS_STASH"
+fi
+
 atomic_copy() {
   local source="$1"
   local rel="$2"
@@ -289,6 +328,7 @@ if [[ ${#CONSOLE_CONFIG_ARGS[@]} -gt 0 || -n "${FLOW_AGENTS_TELEMETRY_SINK:-}" |
 fi
 
 echo "Installed Flow Agents into Codex home at $DEST"
+echo "Installed portable skills at $SKILLS_DIR"
 if [[ "${#profile_names[@]}" -gt 0 ]]; then
   echo "Profiles: ${profile_names[*]}"
 fi

package/scripts/install-owned-files.js

@@ -9,10 +9,24 @@ function fail(message) {
   process.exit(1);
 }
 
-const [sourceArg, destArg, manifestArg] = process.argv.slice(2);
+const args = process.argv.slice(2);
+const checkOnly = args[0] === "--check";
+if (checkOnly) args.shift();
+const [sourceArg, destArg, manifestArg] = args;
 if (!sourceArg || !destArg || !manifestArg) fail("usage: install-owned-files.js <overlay> <destination> <manifest-relative-path>");
 const source = fs.realpathSync(sourceArg);
-const dest = fs.realpathSync(destArg);
+function canonicalizeMissing(value) {
+  let current = path.resolve(value);
+  const missing = [];
+  while (!fs.existsSync(current)) {
+    missing.unshift(path.basename(current));
+    const parent = path.dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  return path.resolve(fs.realpathSync(current), ...missing);
+}
+const dest = canonicalizeMissing(destArg);
 const manifestPath = path.join(dest, manifestArg);
 
 function hashFile(file) {
@@ -132,6 +146,8 @@ for (const [rel] of previous) {
   if (fs.existsSync(target) && fs.lstatSync(target).isSymbolicLink()) fail(`refusing to remove symlink replacing owned file: ${target}`);
 }
 
+if (checkOnly) process.exit(0);
+
 for (const entry of incoming) {
   const target = targetFor(entry.rel);
   ensureSafeParent(target, true);