@hassangameryt/freeflow 0.5.0 → 0.6.0

package/hooks/tests/check-runtime-context-hook.sh

@@ -4,7 +4,9 @@ set -euo pipefail
 ROOT_DIR="$(CDPATH='' cd -- "$(dirname -- "$0")/../.." && pwd)"
 HOOK_PATH="$ROOT_DIR/hooks/freeflow-runtime-context.mjs"
 HOOKS_JSON="$ROOT_DIR/hooks/hooks.json"
-WORKFLOW_SKILL="$ROOT_DIR/skills/workflow/SKILL.md"
+CORE_PROMPT="$ROOT_DIR/runtime/prompts/core.md"
+INTERACTION_PROMPT="$ROOT_DIR/runtime/prompts/interaction-contract.md"
+SKILLS_PROMPT="$ROOT_DIR/runtime/prompts/skills.md"
 
 fail() {
 	echo "runtime-context hook check failed: $*" >&2
@@ -29,11 +31,9 @@ assert_not_contains() {
 
 [[ -f "$HOOK_PATH" ]] || fail "missing hook script"
 [[ -f "$HOOKS_JSON" ]] || fail "missing hooks manifest"
-[[ -f "$WORKFLOW_SKILL" ]] || fail "missing canonical Workflow skill"
-workflow_owner_line="$(grep -m1 '^The active agent owns ' "$WORKFLOW_SKILL" || true)"
-workflow_self_review_line="$(grep -m1 '^Self-review is silent ' "$WORKFLOW_SKILL" || true)"
-[[ -n "$workflow_owner_line" ]] || fail "canonical Workflow owner sentinel missing"
-[[ -n "$workflow_self_review_line" ]] || fail "canonical Workflow self-review sentinel missing"
+for prompt_file in "$CORE_PROMPT" "$INTERACTION_PROMPT" "$SKILLS_PROMPT"; do
+	[[ -f "$prompt_file" ]] || fail "missing runtime prompt fragment: $prompt_file"
+done
 node --check "$HOOK_PATH"
 node -e '
 const fs = require("fs");
@@ -62,42 +62,55 @@ user_prompt_output="$(printf '{"cwd":"%s","model":"gpt-5"}\n' "$tmp_dir" | node
 
 for expected in \
 	'"hookEventName":"SessionStart"' \
-	"# Freeflow Runtime Context" \
-	'Runtime delivery: confirmed for this lifecycle-hook invocation.' \
+	"# Freeflow Stable Guidance" \
+	"## Mode" \
+	"## Shared Terms" \
+	"## Three Nested Loops" \
+	"## Workflow Cue" \
+	"## Action Selection Cue" \
+	"## Supported Exit" \
+	"# Freeflow Interaction Contract" \
+	"Treat questions, criticism, examples, hypotheses, and tentative ideas as" \
 	'Configured default: `workflow` (repository)' \
 	'Effective mode: `workflow` (configured default, active)' \
-	"# Freeflow Interaction Contract" \
-	"Answer questions without inferring action." \
-	"# Freeflow Workflow Bootstrap" \
-	"Use feedback to choose the smallest useful next action." \
-	"$workflow_owner_line" \
-	"$workflow_self_review_line" \
 	'Interaction Contract: enabled' \
 	'Skills: enabled'; do
 	assert_contains "$codex_output" "$expected" "Codex config-only context"
 done
 assert_not_contains "$codex_output" "Output Router" "Codex host context"
 assert_not_contains "$codex_output" "Output router:" "Codex host context"
+
+# The Pi-only capability key is tolerated by shared host validators but is not
+# injected into Codex or Claude runtime context.
+cognitive_dir="$(mktemp -d)"
+mkdir -p "$cognitive_dir/.freeflow"
+printf '{"defaultMode":"workflow","cognitiveRouting":{"enabled":true,"profiles":{"standard":{"provider":"faux","model":"standard","thinkingLevel":"high"},"reasoning":{"provider":"faux","model":"reasoning","thinkingLevel":"max"}}}}\n' >"$cognitive_dir/.freeflow/config.json"
+cognitive_output="$(printf '{"cwd":"%s","model":"gpt-5"}\n' "$cognitive_dir" | node "$HOOK_PATH" SessionStart)"
+assert_contains "$cognitive_output" "# Freeflow Stable Guidance" "Pi-only capability tolerance"
+assert_not_contains "$cognitive_output" "Cognitive Routing" "non-Pi capability isolation"
+rm -rf "$cognitive_dir"
 for excluded_heading in \
 	"# Freeflow Runtime Kernel" \
 	"## Freeflow Runtime Priority" \
 	"## Loaded Mode Contract Skill" \
 	"## Loaded Workflow Skill" \
 	"## Loaded Decision Gate Skill" \
+	"# Freeflow Workflow Bootstrap" \
 	"## Discovery-light" \
 	"## Loaded Output Router Skill"; do
 	assert_not_contains "$codex_output" "$excluded_heading" "default context"
 done
-workflow_bootstrap_count="$(grep -Fo '# Freeflow Workflow Bootstrap' <<<"$codex_output" | wc -l | tr -d ' ')"
-[[ "$workflow_bootstrap_count" == "1" ]] || fail "Codex SessionStart should load Workflow exactly once"
+skills_prompt_count="$(grep -Fo '## Shared Terms' <<<"$codex_output" | wc -l | tr -d ' ')"
+[[ "$skills_prompt_count" == "1" ]] || fail "Codex SessionStart should load the Skills prompt exactly once"
 assert_not_contains "$codex_output" "## Conversation Mode Boundary" "workflow context"
 assert_not_contains "$codex_output" "## Strict Workflow Overlay" "workflow context"
 
 claude_output="$(printf '{"hook_event_name":"SessionStart","source":"startup","cwd":"%s"}\n' "$tmp_dir" | node "$HOOK_PATH" SessionStart)"
 assert_contains "$claude_output" '"hookEventName":"SessionStart"' "Claude wrapper"
 assert_contains "$claude_output" "# Freeflow Interaction Contract" "Claude config-only context"
-assert_contains "$claude_output" "# Freeflow Workflow Bootstrap" "Claude first-turn context"
-assert_contains "$claude_output" "Answer questions without inferring action." "Claude config-only context"
+assert_contains "$claude_output" "## Shared Terms" "Claude skills context"
+assert_not_contains "$claude_output" "# Freeflow Workflow Bootstrap" "Claude first-turn context"
+assert_contains "$claude_output" "Treat questions, criticism, examples, hypotheses, and tentative ideas as" "Claude config-only context"
 
 # Session mode changes are host-managed state: they apply before the same model request,
 # survive lifecycle restoration, remain isolated by session id, and never edit repo config.
@@ -106,9 +119,12 @@ session_id="session/with unsafe path characters"
 config_before="$(shasum -a 256 "$tmp_dir/.freeflow/config.json" | awk '{print $1}')"
 mode_change_output="$(printf '{"hook_event_name":"UserPromptSubmit","session_id":"%s","cwd":"%s","prompt":"Switch to conversation mode."}\n' "$session_id" "$tmp_dir" | PLUGIN_DATA="$session_data_dir" node "$HOOK_PATH" UserPromptSubmit)"
 assert_contains "$mode_change_output" '"hookEventName":"UserPromptSubmit"' "same-turn mode change wrapper"
+assert_contains "$mode_change_output" '# Freeflow Runtime State' "same-turn mode change"
 assert_contains "$mode_change_output" 'Session override: `conversation`' "same-turn mode change"
 assert_contains "$mode_change_output" 'Effective mode: `conversation` (session override, active)' "same-turn mode change"
-assert_contains "$mode_change_output" "## Conversation Mode Boundary" "same-turn mode change"
+assert_not_contains "$mode_change_output" "# Freeflow Mode Update" "same-turn mode change"
+assert_not_contains "$mode_change_output" "## Conversation Mode Boundary" "same-turn mode change"
+assert_not_contains "$mode_change_output" "Do not call write, edit, or mutating tools" "same-turn mode change"
 
 restored_mode_output="$(printf '{"hook_event_name":"SessionStart","source":"compact","session_id":"%s","cwd":"%s","model":"gpt-5"}\n' "$session_id" "$tmp_dir" | PLUGIN_DATA="$session_data_dir" node "$HOOK_PATH" SessionStart)"
 assert_contains "$restored_mode_output" 'Configured default: `workflow` (repository)' "restored session mode"
@@ -129,8 +145,10 @@ default_prompt_output="$(printf '{"hook_event_name":"UserPromptSubmit","session_
 [[ -z "$default_prompt_output" ]] || fail "default-mode requests should remain agent-routed configuration decisions"
 
 native_change_output="$(printf '{"hook_event_name":"UserPromptSubmit","session_id":"%s","cwd":"%s","prompt":"$mode-contract strict-workflow"}\n' "$session_id" "$tmp_dir" | PLUGIN_DATA="$session_data_dir" node "$HOOK_PATH" UserPromptSubmit)"
+assert_contains "$native_change_output" '# Freeflow Runtime State' "Codex native skill mode control"
 assert_contains "$native_change_output" 'Session override: `strict-workflow`' "Codex native skill mode control"
-assert_contains "$native_change_output" "## Strict Workflow Overlay" "Codex native skill mode control"
+assert_not_contains "$native_change_output" "# Freeflow Mode Update" "Codex native skill mode control"
+assert_not_contains "$native_change_output" "## Strict Workflow Overlay" "Codex native skill mode control"
 
 claude_data_dir="$(mktemp -d)"
 claude_mode_output="$(printf '{"hook_event_name":"UserPromptSubmit","session_id":"claude-session","cwd":"%s","prompt":"/freeflow:mode-contract conversation"}\n' "$tmp_dir" | CLAUDE_PLUGIN_DATA="$claude_data_dir" node "$HOOK_PATH" UserPromptSubmit)"
@@ -173,7 +191,7 @@ printf '{"hook_event_name":"SessionEnd","reason":"clear","session_id":"claude-st
 malformed_transfer_file="$(find "$claude_data_dir/session-modes/claude-clear" -type f -name '*.json' -print -quit)"
 printf 'null\n' >"$malformed_transfer_file"
 claude_malformed_clear_output="$(printf '{"hook_event_name":"SessionStart","source":"clear","session_id":"claude-malformed-target","cwd":"%s"}\n' "$tmp_dir" | CLAUDE_PLUGIN_DATA="$claude_data_dir" CLAUDE_PID="claude-process-malformed" node "$HOOK_PATH" SessionStart)"
-assert_contains "$claude_malformed_clear_output" '# Freeflow Runtime Context' "Claude malformed clear transfer"
+assert_contains "$claude_malformed_clear_output" '# Freeflow Stable Guidance' "Claude malformed clear transfer"
 assert_contains "$claude_malformed_clear_output" 'Session override: none' "Claude malformed clear transfer"
 [[ ! -e "$malformed_transfer_file" ]] || fail "malformed Claude clear transfer should be consumed"
 
@@ -237,11 +255,12 @@ for source in startup resume clear compact; do
 			assert_contains "$event_output" '"hookEventName":"SessionStart"' "Claude $source wrapper"
 		fi
 		assert_contains "$event_output" "# Freeflow Interaction Contract" "$host $source SessionStart context"
-		assert_contains "$event_output" "# Freeflow Workflow Bootstrap" "$host $source SessionStart context"
+		assert_contains "$event_output" "## Shared Terms" "$host $source SessionStart context"
 		contract_count="$(grep -Fo '# Freeflow Interaction Contract' <<<"$event_output" | wc -l | tr -d ' ')"
-		bootstrap_count="$(grep -Fo '# Freeflow Workflow Bootstrap' <<<"$event_output" | wc -l | tr -d ' ')"
+		skills_count="$(grep -Fo '## Shared Terms' <<<"$event_output" | wc -l | tr -d ' ')"
 		[[ "$contract_count" == "1" ]] || fail "$host $source SessionStart should load the Interaction Contract exactly once"
-		[[ "$bootstrap_count" == "1" ]] || fail "$host $source SessionStart should load Workflow exactly once"
+		[[ "$skills_count" == "1" ]] || fail "$host $source SessionStart should load the Skills prompt exactly once"
+		assert_not_contains "$event_output" "# Freeflow Workflow Bootstrap" "$host $source SessionStart context"
 	done
 done
 
@@ -273,10 +292,10 @@ printf '{"defaultMode":"strict-workflow"}\n' >"$local_dir/.freeflow/local.json"
 local_output="$(printf '{"cwd":"%s","model":"gpt-5"}\n' "$local_dir" | node "$HOOK_PATH" SessionStart)"
 assert_contains "$local_output" 'Configured default: `strict-workflow` (personal)' "local default override"
 assert_contains "$local_output" 'Effective mode: `strict-workflow` (configured default, active)' "local default source"
-assert_contains "$local_output" "## Strict Workflow Overlay" "local strict overlay"
-assert_contains "$local_output" "security, privacy, billing, data loss, migrations, public interfaces" "local strict overlay"
+assert_not_contains "$local_output" "## Strict Workflow Overlay" "local strict overlay"
+assert_not_contains "$local_output" "security, privacy, billing, data loss, migrations, public interfaces" "local strict overlay"
 assert_contains "$local_output" "# Freeflow Interaction Contract" "local default override"
-assert_contains "$local_output" "# Freeflow Workflow Bootstrap" "local default override"
+assert_contains "$local_output" "## Shared Terms" "local default override"
 rm -rf "$local_dir"
 
 local_interaction_dir="$(mktemp -d)"
@@ -287,7 +306,7 @@ local_interaction_output="$(printf '{"cwd":"%s","model":"gpt-5"}\n' "$local_inte
 assert_contains "$local_interaction_output" 'Interaction Contract: disabled' "independent local interaction override"
 assert_contains "$local_interaction_output" 'Skills: enabled' "independent local interaction override"
 assert_not_contains "$local_interaction_output" "# Freeflow Interaction Contract" "independent local interaction override"
-assert_contains "$local_interaction_output" "# Freeflow Workflow Bootstrap" "independent local interaction override"
+assert_contains "$local_interaction_output" "## Shared Terms" "independent local interaction override"
 rm -rf "$local_interaction_dir"
 
 local_skills_dir="$(mktemp -d)"
@@ -299,6 +318,7 @@ assert_contains "$local_skills_output" 'Resolved mode: `conversation` (dormant b
 assert_contains "$local_skills_output" 'Interaction Contract: disabled' "local interaction override"
 assert_contains "$local_skills_output" 'Skills: disabled' "local skills override"
 assert_not_contains "$local_skills_output" "# Freeflow Interaction Contract" "local interaction override"
+assert_not_contains "$local_skills_output" "# Freeflow Mode Update" "local skills override"
 assert_not_contains "$local_skills_output" "# Freeflow Workflow Bootstrap" "local skills override"
 rm -rf "$local_skills_dir"
 
@@ -315,17 +335,14 @@ mkdir -p "$local_disabled_dir/.freeflow"
 printf '{"enabled":true,"defaultMode":"workflow"}\n' >"$local_disabled_dir/.freeflow/config.json"
 printf '{"enabled":false,"processing":{"unsafeUnsandboxed":{"enabled":true}}}\n' >"$local_disabled_dir/.freeflow/local.json"
 local_disabled_output="$(printf '{"cwd":"%s","model":"gpt-5"}\n' "$local_disabled_dir" | node "$HOOK_PATH" SessionStart)"
-assert_contains "$local_disabled_output" "# Freeflow Disabled" "local master override"
-assert_contains "$local_disabled_output" 'Configured but inactive: `enabled` is false (personal).' "local master source"
-assert_not_contains "$local_disabled_output" "# Freeflow Interaction Contract" "local master override"
+[[ -z "$local_disabled_output" ]] || fail "local master override should suppress hook prompt delivery"
 rm -rf "$local_disabled_dir"
 
 disabled_dir="$(mktemp -d)"
 mkdir -p "$disabled_dir/.freeflow"
 printf '{"enabled":false,"defaultMode":"workflow"}\n' >"$disabled_dir/.freeflow/config.json"
 disabled_output="$(printf '{"cwd":"%s","model":"gpt-5"}\n' "$disabled_dir" | node "$HOOK_PATH" SessionStart)"
-assert_contains "$disabled_output" "# Freeflow Disabled" "disabled context"
-assert_not_contains "$disabled_output" "# Freeflow Runtime Kernel" "disabled context"
+[[ -z "$disabled_output" ]] || fail "disabled Freeflow should suppress hook prompt delivery"
 rm -rf "$disabled_dir"
 
 router_dir="$(mktemp -d)"
@@ -344,11 +361,11 @@ mkdir -p "$all_dir/.freeflow"
 printf '{"defaultMode":"strict-workflow","outputRouter":{"enabled":true}}\n' >"$all_dir/.freeflow/config.json"
 all_output="$(printf '{"cwd":"%s","model":"gpt-5"}\n' "$all_dir" | node "$HOOK_PATH" SessionStart)"
 assert_contains "$all_output" "# Freeflow Interaction Contract" "Codex strict context"
-assert_contains "$all_output" "# Freeflow Workflow Bootstrap" "Codex strict context"
+assert_contains "$all_output" "## Shared Terms" "Codex strict context"
 assert_not_contains "$all_output" "Output Router" "Codex strict context"
 assert_not_contains "$all_output" "Output router:" "Codex strict context"
 assert_contains "$all_output" 'Effective mode: `strict-workflow` (configured default, active)' "Codex strict context"
-assert_contains "$all_output" "## Strict Workflow Overlay" "all-capabilities strict overlay"
+assert_not_contains "$all_output" "## Strict Workflow Overlay" "all-capabilities strict overlay"
 rm -rf "$all_dir"
 
 conversation_dir="$(mktemp -d)"
@@ -357,9 +374,9 @@ printf '{"defaultMode":"conversation"}\n' >"$conversation_dir/.freeflow/config.j
 conversation_output="$(printf '{"cwd":"%s","model":"gpt-5"}\n' "$conversation_dir" | node "$HOOK_PATH" SessionStart)"
 assert_contains "$conversation_output" 'Configured default: `conversation` (repository)' "conversation context"
 assert_contains "$conversation_output" 'Effective mode: `conversation` (configured default, active)' "conversation context"
-assert_contains "$conversation_output" "## Conversation Mode Boundary" "conversation overlay"
-assert_contains "$conversation_output" "Do not call write, edit, or mutating tools" "conversation overlay"
-assert_contains "$conversation_output" "an execution skill does not override this boundary" "conversation overlay"
+assert_not_contains "$conversation_output" "## Conversation Mode Boundary" "conversation overlay"
+assert_not_contains "$conversation_output" "Do not call write, edit, or mutating tools" "conversation overlay"
+assert_not_contains "$conversation_output" "an execution skill does not override this boundary" "conversation overlay"
 rm -rf "$conversation_dir"
 
 observed_dir="$(mktemp -d)"
@@ -367,7 +384,7 @@ mkdir -p "$observed_dir/.freeflow"
 printf '{"defaultMode":"workflow","outputRouter":{"enabled":true,"observedRouting":{"enabled":true}},"scriptTransform":{"enabled":false}}\n' >"$observed_dir/.freeflow/config.json"
 observed_output="$(printf '{"cwd":"%s","model":"gpt-5"}\n' "$observed_dir" | node "$HOOK_PATH" SessionStart)"
 assert_contains "$observed_output" "# Freeflow Interaction Contract" "Codex context with observed-routing config"
-assert_contains "$observed_output" "# Freeflow Workflow Bootstrap" "Codex context with observed-routing config"
+assert_contains "$observed_output" "## Shared Terms" "Codex context with observed-routing config"
 assert_not_contains "$observed_output" "Output Router" "Codex context with observed-routing config"
 assert_not_contains "$observed_output" "Output router:" "Codex context with observed-routing config"
 rm -rf "$observed_dir"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hassangameryt/freeflow",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Feedback-based control system for coding agents.",
   "publishConfig": {
     "access": "public"
@@ -18,24 +18,33 @@
   "scripts": {
     "format": "prettier --write .",
     "format:check": "prettier --check .",
-    "format:router-dist": "prettier --write router/dist",
     "format:pi-extension-dist": "prettier --write pi-extension/dist",
-    "build:router": "tsc -p router/tsconfig.json && npm run format:router-dist",
     "build:pi-extension": "tsc -p pi-extension/tsconfig.json && npm run format:pi-extension-dist",
-    "build": "npm run build:router && npm run build:pi-extension",
+    "build": "npm run build:pi-extension",
+    "typecheck": "tsc -p pi-extension/tsconfig.json --noEmit",
+    "check": "npm run typecheck && npm run check:source && npm run check:changelog && npm run check:release-workflow && npm run check:docs && npm run format:check && npm run check:release-version && npm run check:commands && npm run check:activation && npm run check:runtime && npm run check:package",
+    "check:source": "node scripts/validation/check-source-files.mjs",
+    "check:changelog": "node scripts/validation/check-changelog.mjs --structure",
+    "check:release-workflow": "node scripts/validation/check-release-workflow.mjs",
+    "check:docs": "node scripts/validation/check-docs.mjs",
+    "check:release-version": "node scripts/validation/check-release-version.mjs",
+    "check:commands": "scripts/validation/audit-command-surface.sh",
+    "check:activation": "scripts/validation/check-activation-contract.sh",
+    "check:runtime": "hooks/tests/check-runtime-context-hook.sh",
+    "check:package": "node scripts/validation/check-package.mjs",
+    "check:release-metadata": "scripts/validation/validate-release-metadata.sh --mode prepublish",
     "test:pi-extension": "npm run build && node --test $(find pi-extension/tests -name '*.test.js' | sort)",
-    "test:router": "npm run build:router && node --test $(find router/tests -name '*.test.js' | sort)",
     "test:skill-author": "node --test $(find .skill-eval/write-skill/tests -name '*.test.mjs' | sort)",
     "test:skill-eval": "node --test $(find .skill-eval/evaluate-skill/tests -name '*.test.mjs' | sort)",
-    "bench:router": "npm run build:router && node router/dist/benchmarks/benchmarks.js",
-    "bench:router:commands": "npm run build:router && node router/dist/benchmarks/command-benchmarks.js",
-    "bench:router:context-saving-baseline": "npm run build:router && node router/dist/benchmarks/context-saving-baseline.js",
-    "bench:router:context-mode-normalized": "npm run build:router && node router/dist/benchmarks/context-mode-normalized-benchmarks.js",
-    "bench:router:context-mode-real-deep": "npm run build:router && node router/dist/benchmarks/context-mode-real-deep-benchmark.js",
-    "bench:router:storage-policy": "npm run build:router && node router/dist/benchmarks/storage-policy-benchmarks.js",
-    "bench:router:index": "npm run build:router && node router/dist/benchmarks/index-benchmarks.js",
-    "bench:router:vault-index": "npm run build:router && node router/dist/benchmarks/vault-index-benchmarks.js",
-    "bench:router:codex-qa": "npm run build:router && node router/dist/benchmarks/codex-qa-benchmarks.js"
+    "test:track-work": "node --test .skill-eval/track-work/tests/*.test.mjs",
+    "test:freeflow-snapshot": "node --test scripts/freeflow-snapshot.test.mjs",
+    "test:release-utils": "node --test scripts/release-utils.test.mjs",
+    "test:changelog": "node --test scripts/validation/check-changelog.test.mjs",
+    "test:release-workflow": "node --test scripts/validation/check-release-workflow.test.mjs",
+    "test:docs": "node --test scripts/validation/check-docs.test.mjs",
+    "release:prepare": "node scripts/release.mjs",
+    "release:notes": "node scripts/release-notes.mjs",
+    "snapshot:refresh": "node scripts/freeflow-snapshot.mjs"
   },
   "keywords": [
     "pi-package",
@@ -67,11 +76,10 @@
     "README.md",
     "assets/**",
     "capabilities/**",
+    "runtime/**",
     "command-surface.json",
     "hooks/**",
     "pi-extension/**",
-    "router/dist/**",
-    "runtime/**",
     "skills/**"
   ],
   "peerDependencies": {

package/pi-extension/dist/cognitive-routing/commands.js

@@ -0,0 +1,96 @@
+const PROFILE_VALUES = ["standard", "reasoning", "auto"];
+const HISTORY_VALUES = ["history", "history active", "history anomalies"];
+export function cognitiveRoutingProfileCompletions(prefix) {
+  const query = prefix ?? "";
+  return [...PROFILE_VALUES, ...HISTORY_VALUES]
+    .filter((value) => value.startsWith(query))
+    .map((value) => ({
+      value,
+      label: value,
+      description:
+        value === "auto"
+          ? "Release the manual hold without changing the model"
+          : value === "history"
+            ? "Show Cognitive Routing transition history"
+            : value === "history active"
+              ? "Show current-branch Cognitive Routing history"
+              : value === "history anomalies"
+                ? "Show Cognitive Routing history anomalies"
+                : `Hold ${value} profile manually`,
+    }));
+}
+function historyOptions(value) {
+  if (value === "history") return {};
+  if (value === "history active") return { scope: "active-branch" };
+  if (value === "history anomalies") return { anomaliesOnly: true };
+  return undefined;
+}
+function formatHistory(result) {
+  const lines = [
+    `Cognitive Routing history: ${result.current.profile} · ${result.current.control}`,
+    `Events: ${result.events.length}; unresolved=${result.summary.unresolvedCount}; anomalies=${result.summary.anomalyCount}`,
+  ];
+  if (result.summary.latestSemanticEventId) lines.push(`Latest semantic: ${result.summary.latestSemanticEventId}`);
+  if (result.summary.latestCompletedEventId) lines.push(`Latest completed: ${result.summary.latestCompletedEventId}`);
+  for (const event of result.events) {
+    const transition = event.from && event.to ? ` ${event.from} → ${event.to}` : "";
+    lines.push(
+      `${event.jsonlPosition}: ${event.outcome} · ${event.classification}${transition} · changed=${event.changed} · ${event.id}`,
+    );
+  }
+  return lines.join("\n");
+}
+export async function handleCognitiveRoutingProfileCommand(args, ctx, controller) {
+  const input = (args ?? "").trim().toLowerCase();
+  const [action, ...rest] = input.split(/\s+/);
+  if (action !== "profile") return false;
+  const value = rest.join(" ");
+  const historyView = historyOptions(value);
+  if (historyView) {
+    const result = ctx.history
+      ? await ctx.history(historyView)
+      : controller?.history
+        ? controller.history(historyView)
+        : undefined;
+    if (result) {
+      ctx.ui?.notify?.(formatHistory(result), "info");
+    } else {
+      ctx.ui?.notify?.("Cognitive Routing history is unavailable for this session.", "warning");
+    }
+    return true;
+  }
+  if (!PROFILE_VALUES.includes(value)) {
+    ctx.ui?.notify?.(
+      "Usage: /freeflow profile standard, /freeflow profile reasoning, /freeflow profile auto, or /freeflow profile history [active|anomalies]",
+      "warning",
+    );
+    return true;
+  }
+  if (typeof ctx.isIdle === "function" && !ctx.isIdle()) {
+    ctx.ui?.notify?.("Freeflow settings and profile changes are available only while Pi is idle.", "warning");
+    return true;
+  }
+  if (!controller) {
+    ctx.ui?.notify?.(
+      "Cognitive Routing is unavailable for this session. It may be disabled, unsupported by the Pi host, or suppressed by an explicit startup model selection.",
+      "warning",
+    );
+    return true;
+  }
+  if (value === "auto") {
+    const result = await controller.setAutomaticControl();
+    if (result.status === "automatic") {
+      ctx.ui?.notify?.("Cognitive Routing manual hold released; automatic control is active.", "info");
+    } else {
+      ctx.ui?.notify?.(`Cognitive Routing could not release the manual hold: ${result.reason}.`, "warning");
+    }
+    return true;
+  }
+  const result = await controller.setManualProfile(value);
+  if (result.status === "active") {
+    ctx.ui?.notify?.(`Cognitive Routing manual hold set to ${result.profile}.`, "info");
+  } else {
+    ctx.ui?.notify?.(`Cognitive Routing could not set the manual profile: ${result.reason}.`, "warning");
+  }
+  return true;
+}

package/pi-extension/dist/cognitive-routing/config.js

@@ -0,0 +1,236 @@
+import {
+  COGNITIVE_ROUTING_PROFILE_NAMES,
+  COGNITIVE_ROUTING_SESSION_START_CONTROLS,
+  DEFAULT_COGNITIVE_ROUTING_SESSION_START,
+} from "./types.js";
+const THINKING_LEVELS = new Set(["off", "minimal", "low", "medium", "high", "xhigh", "max"]);
+const PROFILE_NAME_SET = new Set(COGNITIVE_ROUTING_PROFILE_NAMES);
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function invalid(source, code, message, profile) {
+  return { code, message, ...(profile ? { profile } : {}), source };
+}
+function parseProfile(value, source, name) {
+  if (!isRecord(value)) {
+    return { error: invalid(source, "invalid_profile", `${source} ${name} profile must be an object`, name) };
+  }
+  const allowedKeys = new Set(["provider", "model", "thinkingLevel"]);
+  const unsupportedKey = Object.keys(value).find((key) => !allowedKeys.has(key));
+  if (unsupportedKey) {
+    return {
+      error: invalid(
+        source,
+        "unsupported_key",
+        `${source} ${name} profile contains unsupported key: ${unsupportedKey}`,
+        name,
+      ),
+    };
+  }
+  if (typeof value.provider !== "string" || value.provider.trim() === "") {
+    return { error: invalid(source, "invalid_profile", `${source} ${name} profile requires provider`, name) };
+  }
+  if (typeof value.model !== "string" || value.model.trim() === "") {
+    return { error: invalid(source, "invalid_profile", `${source} ${name} profile requires model`, name) };
+  }
+  if (typeof value.thinkingLevel !== "string" || !THINKING_LEVELS.has(value.thinkingLevel)) {
+    return {
+      error: invalid(source, "invalid_profile", `${source} ${name} profile requires a valid thinkingLevel`, name),
+    };
+  }
+  return {
+    profile: {
+      provider: value.provider,
+      model: value.model,
+      thinkingLevel: value.thinkingLevel,
+    },
+  };
+}
+function parseSessionStart(value, source) {
+  if (!isRecord(value)) {
+    return {
+      error: invalid(source, "invalid_session_start", `${source} cognitiveRouting.sessionStart must be an object`),
+    };
+  }
+  const allowedKeys = new Set(["control", "profile"]);
+  const unsupportedKey = Object.keys(value).find((key) => !allowedKeys.has(key));
+  if (unsupportedKey) {
+    return {
+      error: invalid(
+        source,
+        "unsupported_key",
+        `${source} cognitiveRouting.sessionStart contains unsupported key: ${unsupportedKey}`,
+      ),
+    };
+  }
+  let control;
+  if (Object.hasOwn(value, "control")) {
+    if (typeof value.control !== "string" || !COGNITIVE_ROUTING_SESSION_START_CONTROLS.includes(value.control)) {
+      return {
+        error: invalid(
+          source,
+          "invalid_session_start",
+          `${source} cognitiveRouting.sessionStart.control must be automatic or manual`,
+        ),
+      };
+    }
+    control = value.control;
+  }
+  let profile;
+  if (Object.hasOwn(value, "profile")) {
+    if (typeof value.profile !== "string" || !PROFILE_NAME_SET.has(value.profile)) {
+      return {
+        error: invalid(
+          source,
+          "invalid_session_start",
+          `${source} cognitiveRouting.sessionStart.profile must be standard or reasoning`,
+        ),
+      };
+    }
+    profile = value.profile;
+  }
+  return { sessionStart: { ...(control ? { control } : {}), ...(profile ? { profile } : {}) } };
+}
+function parseLayer(value, source) {
+  if (value === undefined) {
+    return { present: false, valid: true, profiles: {}, sessionStart: {} };
+  }
+  if (!isRecord(value)) {
+    return {
+      present: true,
+      valid: false,
+      profiles: {},
+      sessionStart: {},
+      error: invalid(source, "invalid_block", `${source} cognitiveRouting must be an object`),
+    };
+  }
+  const allowedKeys = new Set(["enabled", "profiles", "sessionStart"]);
+  const unsupportedKey = Object.keys(value).find((key) => !allowedKeys.has(key));
+  if (unsupportedKey) {
+    return {
+      present: true,
+      valid: false,
+      profiles: {},
+      sessionStart: {},
+      error: invalid(
+        source,
+        "unsupported_key",
+        `${source} cognitiveRouting contains unsupported key: ${unsupportedKey}`,
+      ),
+    };
+  }
+  let enabled;
+  if (Object.hasOwn(value, "enabled")) {
+    if (typeof value.enabled !== "boolean") {
+      return {
+        present: true,
+        valid: false,
+        profiles: {},
+        sessionStart: {},
+        error: invalid(source, "invalid_enabled", `${source} cognitiveRouting.enabled must be a boolean`),
+      };
+    }
+    enabled = value.enabled;
+  }
+  let sessionStart = {};
+  if (Object.hasOwn(value, "sessionStart")) {
+    const parsed = parseSessionStart(value.sessionStart, source);
+    if (parsed.error)
+      return { present: true, valid: false, enabled, profiles: {}, sessionStart: {}, error: parsed.error };
+    sessionStart = parsed.sessionStart ?? {};
+  }
+  const profiles = {};
+  if (Object.hasOwn(value, "profiles")) {
+    if (!isRecord(value.profiles)) {
+      return {
+        present: true,
+        valid: false,
+        profiles: {},
+        sessionStart: {},
+        error: invalid(source, "invalid_profiles", `${source} cognitiveRouting.profiles must be an object`),
+      };
+    }
+    const unsupportedProfile = Object.keys(value.profiles).find((key) => !PROFILE_NAME_SET.has(key));
+    if (unsupportedProfile) {
+      return {
+        present: true,
+        valid: false,
+        profiles: {},
+        sessionStart: {},
+        error: invalid(
+          source,
+          "unsupported_key",
+          `${source} cognitiveRouting.profiles contains unsupported profile: ${unsupportedProfile}`,
+        ),
+      };
+    }
+    for (const name of COGNITIVE_ROUTING_PROFILE_NAMES) {
+      if (!Object.hasOwn(value.profiles, name)) continue;
+      const parsed = parseProfile(value.profiles[name], source, name);
+      if (parsed.error) {
+        return { present: true, valid: false, enabled, profiles: {}, sessionStart: {}, error: parsed.error };
+      }
+      profiles[name] = parsed.profile;
+    }
+  }
+  return { present: true, valid: true, enabled, profiles, sessionStart };
+}
+export function resolveCognitiveRoutingConfig(repositoryConfig, personalConfig) {
+  const repositoryValue = isRecord(repositoryConfig) ? repositoryConfig.cognitiveRouting : undefined;
+  const personalValue = isRecord(personalConfig) ? personalConfig.cognitiveRouting : undefined;
+  const repository = parseLayer(repositoryValue, "repository");
+  const personal = parseLayer(personalValue, "personal");
+  const configured = repository.present || personal.present;
+  const profiles = {};
+  const profileSources = {};
+  for (const name of COGNITIVE_ROUTING_PROFILE_NAMES) {
+    if (repository.profiles[name]) {
+      profiles[name] = repository.profiles[name];
+      profileSources[name] = "repository";
+    }
+    if (personal.profiles[name]) {
+      profiles[name] = personal.profiles[name];
+      profileSources[name] = "personal";
+    }
+  }
+  const enabled = personal.enabled ?? repository.enabled ?? false;
+  let enabledSource = "default";
+  if (repository.enabled !== undefined) enabledSource = "repository";
+  if (personal.enabled !== undefined) enabledSource = "personal";
+  const sessionStart = {
+    control:
+      personal.sessionStart.control ??
+      repository.sessionStart.control ??
+      DEFAULT_COGNITIVE_ROUTING_SESSION_START.control,
+    profile:
+      personal.sessionStart.profile ??
+      repository.sessionStart.profile ??
+      DEFAULT_COGNITIVE_ROUTING_SESSION_START.profile,
+  };
+  const sessionStartSources = {
+    control:
+      personal.sessionStart.control !== undefined
+        ? "personal"
+        : repository.sessionStart.control !== undefined
+          ? "repository"
+          : "default",
+    profile:
+      personal.sessionStart.profile !== undefined
+        ? "personal"
+        : repository.sessionStart.profile !== undefined
+          ? "repository"
+          : "default",
+  };
+  const error = repository.error ?? personal.error;
+  return {
+    configured,
+    valid: repository.valid && personal.valid,
+    enabled,
+    enabledSource,
+    profiles,
+    profileSources,
+    sessionStart,
+    sessionStartSources,
+    ...(error ? { error } : {}),
+  };
+}