@hassangameryt/freeflow 0.2.0 → 0.4.0

package/hooks/freeflow-runtime-context.mjs

@@ -0,0 +1,419 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+const PLUGIN_ROOT = path.resolve(SCRIPT_DIR, "..");
+const VALID_MODES = new Set(["conversation", "workflow", "strict-workflow"]);
+
+function readStdinJson() {
+  const raw = fs.readFileSync(0, "utf8").trim();
+  if (!raw) {
+    return { input: {}, raw: "" };
+  }
+
+  try {
+    return { input: JSON.parse(raw), raw };
+  } catch {
+    return { input: {}, raw };
+  }
+}
+
+function readText(filePath) {
+  try {
+    return fs.readFileSync(filePath, "utf8");
+  } catch {
+    return null;
+  }
+}
+
+function findWorkspaceRoot(cwd) {
+  let current = path.resolve(cwd || process.cwd());
+
+  while (true) {
+    if (fs.existsSync(path.join(current, ".git"))) {
+      return current;
+    }
+
+    const parent = path.dirname(current);
+    if (parent === current) {
+      return path.resolve(cwd || process.cwd());
+    }
+    current = parent;
+  }
+}
+
+function loadRuntimeContext(options = {}) {
+  const includeInteractionContract = options.interactionContract === true;
+  const includeSkills = options.skills === true;
+  const includeOutputRouter = options.outputRouter === true;
+  const interactionContract = includeInteractionContract
+    ? readText(path.join(PLUGIN_ROOT, "runtime", "interaction-contract.md"))
+    : null;
+  const workflowSkill = includeSkills ? readText(path.join(PLUGIN_ROOT, "skills", "workflow", "SKILL.md")) : null;
+  const outputRouterSkill = includeOutputRouter
+    ? readText(path.join(PLUGIN_ROOT, "skills", "output-router", "SKILL.md"))
+    : null;
+
+  if (
+    (includeInteractionContract && !interactionContract) ||
+    (includeSkills && !workflowSkill) ||
+    (includeOutputRouter && !outputRouterSkill)
+  ) {
+    throw new Error("Freeflow runtime context files are missing.");
+  }
+
+  return { interactionContract, workflowSkill, outputRouterSkill };
+}
+
+function readConfig(root) {
+  const repository = readConfigLayer(path.join(root, ".freeflow", "config.json"), isValidSetupConfig);
+  const local = readConfigLayer(path.join(root, ".freeflow", "local.json"), isValidLocalConfig);
+  const localValid = !local.exists || local.valid;
+  const configured = repository.valid && localValid;
+  const core = resolveCoreConfig(repository.valid ? repository.parsed : {}, local.valid ? local.parsed : {});
+  const enabled = configured && core.config.enabled;
+  const repositoryConfig = repository.valid ? repository.parsed : {};
+
+  return {
+    exists: repository.exists,
+    valid: configured,
+    configured,
+    repositoryValid: repository.valid,
+    localExists: local.exists,
+    localValid,
+    error: !repository.valid ? repository.error : local.error,
+    enabled,
+    interactionContractEnabled: enabled && core.config.interactionContract,
+    skillsEnabled: enabled && core.config.skills.enabled,
+    defaultMode: core.config.defaultMode,
+    sources: core.sources,
+    outputRouterEnabled: enabled && repositoryConfig?.outputRouter?.enabled === true,
+  };
+}
+
+function readConfigLayer(filePath, validate) {
+  if (!fs.existsSync(filePath)) {
+    return { path: filePath, exists: false, valid: false, parsed: {}, error: null };
+  }
+
+  try {
+    const parsed = JSON.parse(fs.readFileSync(filePath, "utf8"));
+    const error = validate(parsed);
+    return {
+      path: filePath,
+      exists: true,
+      valid: error === null,
+      parsed: error === null ? parsed : {},
+      error,
+    };
+  } catch (error) {
+    return {
+      path: filePath,
+      exists: true,
+      valid: false,
+      parsed: {},
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function validateCoreConfigFields(value) {
+  if (Object.prototype.hasOwnProperty.call(value, "defaultMode") && !VALID_MODES.has(value.defaultMode)) {
+    return "defaultMode must be conversation, workflow, or strict-workflow";
+  }
+  if (Object.prototype.hasOwnProperty.call(value, "enabled") && typeof value.enabled !== "boolean") {
+    return "enabled must be a boolean";
+  }
+  if (
+    Object.prototype.hasOwnProperty.call(value, "interactionContract") &&
+    typeof value.interactionContract !== "boolean"
+  ) {
+    return "interactionContract must be a boolean";
+  }
+  if (Object.prototype.hasOwnProperty.call(value, "skills")) {
+    if (!isRecord(value.skills)) {
+      return "skills must be an object";
+    }
+    if (Object.prototype.hasOwnProperty.call(value.skills, "enabled") && typeof value.skills.enabled !== "boolean") {
+      return "skills.enabled must be a boolean";
+    }
+  }
+  return null;
+}
+
+function isValidSetupConfig(value) {
+  if (!isRecord(value)) {
+    return "repository config must be a JSON object";
+  }
+
+  const allowedKeys = new Set([
+    "enabled",
+    "defaultMode",
+    "interactionContract",
+    "skills",
+    "outputRouter",
+    "observedRouting",
+    "scriptTransform",
+  ]);
+  if (!Object.keys(value).every((key) => allowedKeys.has(key))) {
+    return "repository config contains unsupported top-level keys";
+  }
+
+  const coreError = validateCoreConfigFields(value);
+  if (coreError) {
+    return coreError;
+  }
+
+  for (const key of ["outputRouter", "observedRouting", "scriptTransform"]) {
+    if (Object.prototype.hasOwnProperty.call(value, key) && !isRecord(value[key])) {
+      return `${key} must be an object`;
+    }
+  }
+  return null;
+}
+
+function isValidLocalConfig(value) {
+  if (!isRecord(value)) {
+    return "local config must be a JSON object";
+  }
+
+  const allowedKeys = new Set(["enabled", "defaultMode", "interactionContract", "skills", "processing"]);
+  if (!Object.keys(value).every((key) => allowedKeys.has(key))) {
+    return "local config contains unsupported top-level keys";
+  }
+  return validateCoreConfigFields(value);
+}
+
+function hasOwn(value, key) {
+  return Object.prototype.hasOwnProperty.call(value, key);
+}
+
+function resolveLayeredValue(repository, local, key, fallback) {
+  if (hasOwn(local, key)) {
+    return { value: local[key], source: "local" };
+  }
+  if (hasOwn(repository, key)) {
+    return { value: repository[key], source: "repository" };
+  }
+  return { value: fallback, source: "builtin" };
+}
+
+function resolveCoreConfig(repository, local) {
+  const enabled = resolveLayeredValue(repository, local, "enabled", true);
+  const interactionContract = resolveLayeredValue(repository, local, "interactionContract", true);
+  const defaultMode = resolveLayeredValue(repository, local, "defaultMode", "workflow");
+  const repositorySkills = isRecord(repository.skills) ? repository.skills : {};
+  const localSkills = isRecord(local.skills) ? local.skills : {};
+  const skillsEnabled = resolveLayeredValue(repositorySkills, localSkills, "enabled", true);
+
+  return {
+    config: {
+      enabled: enabled.value,
+      interactionContract: interactionContract.value,
+      skills: { enabled: skillsEnabled.value },
+      defaultMode: defaultMode.value,
+    },
+    sources: {
+      enabled: enabled.source,
+      interactionContract: interactionContract.source,
+      skillsEnabled: skillsEnabled.source,
+      defaultMode: defaultMode.source,
+    },
+  };
+}
+
+function inspectSetup(root) {
+  return { config: readConfig(root) };
+}
+
+function configStatus(config) {
+  if (!config.valid) {
+    return "invalid layered configuration";
+  }
+  const source = config.sources.defaultMode;
+  const personal = config.localExists ? "; personal overrides present" : "";
+  return `defaultMode \`${config.defaultMode}\` from ${source}${personal}`;
+}
+
+function modeOverlayGuidance(mode) {
+  if (mode === "conversation") {
+    return [
+      "",
+      "## Conversation Mode Boundary",
+      "",
+      "Conversation mode is active and read-only.",
+      "",
+      "Do not call write, edit, or mutating tools. Do not create, delete, commit, push, or change repository, system, external, or durable state.",
+      "",
+      "A mutation request does not switch mode, and an execution skill does not override this boundary. Explain that conversation mode is read-only and ask the user to switch to workflow or strict-workflow.",
+    ];
+  }
+
+  if (mode === "strict-workflow") {
+    return [
+      "",
+      "## Strict Workflow Overlay",
+      "",
+      "Strict Workflow is active. Use the adaptive Workflow, but increase decision, evidence, verification, and checkpoint pressure at high-risk or hard-to-reverse boundaries.",
+      "",
+      "For work affecting security, privacy, billing, data loss, migrations, public interfaces, compatibility, deployment, or architecture:",
+      "",
+      "- stop for any user-owned choice or source conflict;",
+      "- inspect the relevant risk surface before crossing the boundary;",
+      "- select only artifacts, checkpoints, and independent review that materially reduce risk;",
+      "- verify at the affected boundary before claiming success.",
+      "",
+      "Do not manufacture ceremony for low-risk, reversible work. Strict Workflow does not authorize mutation, bypass safety, or make every implementation detail a user decision.",
+    ];
+  }
+
+  return [];
+}
+
+function modeGuidance(mode) {
+  return [
+    `Current Freeflow default mode: \`${mode}\`.`,
+    "Treat this as the resolved default at session start, resume, clear, and compact.",
+    "Mode behavior:",
+    "- `conversation`: answer, discuss, critique, and inspect read-only; switch modes before mutating state.",
+    "- `workflow`: use the adaptive workflow for normal consequential work.",
+    "- `strict-workflow`: strengthen user-owned decisions, review, and verification for high-risk or hard-to-reverse work.",
+    "Do not announce the current mode on every reply. Mention it when the user asks, setup/config is discussed, or the mode changes the next action.",
+    ...modeOverlayGuidance(mode),
+  ];
+}
+
+function buildSetupStatus(root) {
+  const { config } = inspectSetup(root);
+  if (!config.valid) {
+    return "Setup status: Freeflow is not configured for this repo.";
+  }
+
+  const modeStatus = config.skillsEnabled
+    ? modeGuidance(config.defaultMode)
+    : [`Resolved default mode: \`${config.defaultMode}\` (dormant because Skills are disabled).`];
+  return [
+    `Setup status: configured by \`.freeflow/config.json\` with ${configStatus(config)}.`,
+    "Runtime delivery: confirmed for this lifecycle-hook invocation.",
+    ...modeStatus,
+  ].join("\n");
+}
+
+function shouldInject(eventName) {
+  if (process.env.FREEFLOW_DISABLE_RUNTIME_CONTEXT === "1") {
+    return false;
+  }
+
+  return eventName === "SessionStart";
+}
+
+function capabilityStatus(config) {
+  return [
+    "## Freeflow Capabilities",
+    "",
+    `- Interaction Contract: ${config.interactionContractEnabled ? "enabled" : "disabled"}.`,
+    `- Skills: ${config.skillsEnabled ? "enabled" : "disabled"}.`,
+    `- Output router: ${config.outputRouterEnabled ? "enabled" : "disabled"}.`,
+    "",
+    "Capability-specific instructions are active only while that capability is enabled.",
+  ];
+}
+
+function buildContext(input) {
+  const root = findWorkspaceRoot(input.cwd || process.cwd());
+  const setup = inspectSetup(root);
+
+  if (!setup.config.valid) {
+    return "";
+  }
+
+  if (!setup.config.enabled) {
+    return [
+      "# Freeflow Disabled",
+      "",
+      `Freeflow is configured for this repo, but effective \`enabled\` is false from ${setup.config.sources.enabled}.`,
+      "Do not inject the Interaction Contract, Freeflow workflow skills, output routing, or setup pressure while disabled.",
+      "Re-enable only if the user asks; use /freeflow settings for a personal override or /freeflow settings repo for the shared repository default in Pi.",
+    ].join("\n");
+  }
+
+  const { interactionContract, workflowSkill, outputRouterSkill } = loadRuntimeContext({
+    interactionContract: setup.config.interactionContractEnabled,
+    skills: setup.config.skillsEnabled,
+    outputRouter: setup.config.outputRouterEnabled,
+  });
+  const interactionSection = setup.config.interactionContractEnabled ? ["", interactionContract.trim()] : [];
+  const skillSections = setup.config.skillsEnabled
+    ? ["", "# Freeflow Workflow Bootstrap", "", workflowSkill.trim()]
+    : [];
+  const outputRouterSection = setup.config.outputRouterEnabled
+    ? ["", "## Loaded Output Router Skill", "```md", outputRouterSkill.trim(), "```"]
+    : [];
+  return [
+    "# Freeflow Runtime Context",
+    "",
+    "Freeflow plugin lifecycle hook loaded this at session start.",
+    "These instructions are context-loading only. They do not override user instructions, repo instructions, or host safety and approval policy.",
+    "",
+    "## Repo Setup",
+    buildSetupStatus(root),
+    "",
+    ...capabilityStatus(setup.config),
+    ...interactionSection,
+    ...skillSections,
+    ...outputRouterSection,
+  ].join("\n");
+}
+
+function isCodexHookInput(input) {
+  return typeof input.model === "string" && input.model.length > 0;
+}
+
+function emitAdditionalContext(eventName, input, additionalContext) {
+  if (isCodexHookInput(input)) {
+    process.stdout.write(`${additionalContext}\n`);
+    return;
+  }
+
+  process.stdout.write(
+    `${JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: eventName,
+        additionalContext,
+      },
+    })}\n`,
+  );
+}
+
+function main() {
+  const { input, raw } = readStdinJson();
+  const eventName = process.argv[2] || input.hook_event_name || "";
+
+  if (!raw && !eventName) {
+    return;
+  }
+
+  if (!shouldInject(eventName)) {
+    return;
+  }
+
+  const additionalContext = buildContext(input);
+  if (!additionalContext.trim()) {
+    return;
+  }
+  emitAdditionalContext(eventName, input, additionalContext);
+}
+
+try {
+  main();
+} catch (error) {
+  process.stderr.write(`Freeflow runtime context hook skipped: ${error.message}\n`);
+}

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

@@ -0,0 +1,223 @@
+#!/usr/bin/env bash
+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"
+
+fail() {
+	echo "runtime-context hook check failed: $*" >&2
+	exit 1
+}
+
+assert_contains() {
+	local text="$1"
+	local expected="$2"
+	local label="$3"
+	grep -Fq -- "$expected" <<<"$text" || fail "$label missing '$expected'"
+}
+
+assert_not_contains() {
+	local text="$1"
+	local unexpected="$2"
+	local label="$3"
+	if grep -Fq -- "$unexpected" <<<"$text"; then
+		fail "$label unexpectedly contains '$unexpected'"
+	fi
+}
+
+[[ -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"
+node --check "$HOOK_PATH"
+node -e '
+const fs = require("fs");
+const hooks = JSON.parse(fs.readFileSync(process.argv[1], "utf8")).hooks || {};
+if (!Array.isArray(hooks.SessionStart) || hooks.SessionStart.length === 0) process.exit(1);
+if (hooks.SessionStart[0]?.matcher !== "startup|resume|clear|compact") process.exit(1);
+' "$HOOKS_JSON" || fail "hooks.json does not register the expected SessionStart lifecycle matcher"
+
+tmp_dir="$(mktemp -d)"
+trap 'rm -rf "$tmp_dir"' EXIT
+mkdir -p "$tmp_dir/.freeflow"
+printf '{"defaultMode":"workflow"}\n' >"$tmp_dir/.freeflow/config.json"
+
+codex_output="$(printf '{"cwd":"%s","model":"gpt-5"}\n' "$tmp_dir" | node "$HOOK_PATH" SessionStart)"
+disabled_by_env="$(printf '{"cwd":"%s","model":"gpt-5"}\n' "$tmp_dir" | FREEFLOW_DISABLE_RUNTIME_CONTEXT=1 node "$HOOK_PATH" SessionStart)"
+[[ -z "$disabled_by_env" ]] || fail "FREEFLOW_DISABLE_RUNTIME_CONTEXT=1 should suppress injection"
+
+post_tool_output="$(printf '{"cwd":"%s","model":"gpt-5"}\n' "$tmp_dir" | node "$HOOK_PATH" PostToolUse)"
+[[ -z "$post_tool_output" ]] || fail "PostToolUse should not inject runtime context"
+user_prompt_output="$(printf '{"cwd":"%s","model":"gpt-5"}\n' "$tmp_dir" | node "$HOOK_PATH" UserPromptSubmit)"
+[[ -z "$user_prompt_output" ]] || fail "UserPromptSubmit should not duplicate session-start runtime context"
+
+for expected in \
+	"# Freeflow Runtime Context" \
+	'Setup status: configured by `.freeflow/config.json`' \
+	"Runtime delivery: confirmed for this lifecycle-hook invocation." \
+	"# 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" \
+	'Current Freeflow default mode: `workflow`.' \
+	'Interaction Contract: enabled' \
+	'Skills: enabled' \
+	'Output router: disabled'; do
+	assert_contains "$codex_output" "$expected" "Codex config-only context"
+done
+for excluded_heading in \
+	"# Freeflow Runtime Kernel" \
+	"## Freeflow Runtime Priority" \
+	"## Loaded Mode Contract Skill" \
+	"## Loaded Workflow Skill" \
+	"## Loaded Decision Gate Skill" \
+	"## 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"
+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"
+
+for source in startup resume clear compact; do
+	event_output="$(printf '{"hook_event_name":"SessionStart","source":"%s","cwd":"%s","model":"gpt-5"}\n' "$source" "$tmp_dir" | node "$HOOK_PATH" SessionStart)"
+	assert_contains "$event_output" "# Freeflow Interaction Contract" "$source SessionStart context"
+done
+
+# Repo-owned host instructions are neither required for activation nor modified by the read-only hook.
+printf '# Repo agents\n\nKeep this guidance.\n' >"$tmp_dir/AGENTS.md"
+printf '# Repo Claude\n\nKeep this guidance too.\n' >"$tmp_dir/CLAUDE.md"
+cp "$tmp_dir/AGENTS.md" "$tmp_dir/AGENTS.before"
+cp "$tmp_dir/CLAUDE.md" "$tmp_dir/CLAUDE.before"
+host_output="$(printf '{"cwd":"%s","model":"gpt-5"}\n' "$tmp_dir" | node "$HOOK_PATH" SessionStart)"
+assert_contains "$host_output" "# Freeflow Interaction Contract" "host-independent activation"
+cmp -s "$tmp_dir/AGENTS.before" "$tmp_dir/AGENTS.md" || fail "hook modified AGENTS.md"
+cmp -s "$tmp_dir/CLAUDE.before" "$tmp_dir/CLAUDE.md" || fail "hook modified CLAUDE.md"
+
+# Repository config remains the only activation boundary; local config only overrides it.
+missing_dir="$(mktemp -d)"
+invalid_dir="$(mktemp -d)"
+mkdir -p "$invalid_dir/.freeflow"
+printf '{invalid\n' >"$invalid_dir/.freeflow/config.json"
+missing_output="$(printf '{"cwd":"%s","model":"gpt-5"}\n' "$missing_dir" | node "$HOOK_PATH" SessionStart)"
+invalid_output="$(printf '{"cwd":"%s","model":"gpt-5"}\n' "$invalid_dir" | node "$HOOK_PATH" SessionStart)"
+[[ -z "$missing_output" ]] || fail "missing config should not activate runtime context"
+[[ -z "$invalid_output" ]] || fail "invalid config should not activate runtime context"
+rm -rf "$missing_dir" "$invalid_dir"
+
+local_dir="$(mktemp -d)"
+mkdir -p "$local_dir/.freeflow"
+printf '{"defaultMode":"workflow"}\n' >"$local_dir/.freeflow/config.json"
+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" 'Current Freeflow default mode: `strict-workflow`.' "local default override"
+assert_contains "$local_output" 'defaultMode `strict-workflow` from local' "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_contains "$local_output" "# Freeflow Interaction Contract" "local default override"
+assert_contains "$local_output" "# Freeflow Workflow Bootstrap" "local default override"
+rm -rf "$local_dir"
+
+local_interaction_dir="$(mktemp -d)"
+mkdir -p "$local_interaction_dir/.freeflow"
+printf '{"defaultMode":"workflow"}\n' > "$local_interaction_dir/.freeflow/config.json"
+printf '{"interactionContract":false}\n' > "$local_interaction_dir/.freeflow/local.json"
+local_interaction_output="$(printf '{"cwd":"%s","model":"gpt-5"}\n' "$local_interaction_dir" | node "$HOOK_PATH" SessionStart)"
+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"
+rm -rf "$local_interaction_dir"
+
+local_skills_dir="$(mktemp -d)"
+mkdir -p "$local_skills_dir/.freeflow"
+printf '{"defaultMode":"workflow"}\n' >"$local_skills_dir/.freeflow/config.json"
+printf '{"defaultMode":"conversation","interactionContract":false,"skills":{"enabled":false}}\n' >"$local_skills_dir/.freeflow/local.json"
+local_skills_output="$(printf '{"cwd":"%s","model":"gpt-5"}\n' "$local_skills_dir" | node "$HOOK_PATH" SessionStart)"
+assert_contains "$local_skills_output" 'Resolved default mode: `conversation` (dormant because Skills are disabled).' "local dormant mode"
+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 Workflow Bootstrap" "local skills override"
+rm -rf "$local_skills_dir"
+
+invalid_local_dir="$(mktemp -d)"
+mkdir -p "$invalid_local_dir/.freeflow"
+printf '{"defaultMode":"workflow"}\n' >"$invalid_local_dir/.freeflow/config.json"
+printf '{"skills":{"enabled":"no"}}\n' >"$invalid_local_dir/.freeflow/local.json"
+invalid_local_output="$(printf '{"cwd":"%s","model":"gpt-5"}\n' "$invalid_local_dir" | node "$HOOK_PATH" SessionStart)"
+[[ -z "$invalid_local_output" ]] || fail "invalid local config should fail closed"
+rm -rf "$invalid_local_dir"
+
+local_disabled_dir="$(mktemp -d)"
+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" "effective \`enabled\` is false from local" "local master source"
+assert_not_contains "$local_disabled_output" "# Freeflow Interaction Contract" "local master override"
+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"
+rm -rf "$disabled_dir"
+
+router_dir="$(mktemp -d)"
+mkdir -p "$router_dir/.freeflow"
+printf '{"defaultMode":"workflow","skills":{"enabled":false},"outputRouter":{"enabled":true}}\n' >"$router_dir/.freeflow/config.json"
+router_output="$(printf '{"cwd":"%s","model":"gpt-5"}\n' "$router_dir" | node "$HOOK_PATH" SessionStart)"
+assert_contains "$router_output" "Skills: disabled" "router-only context"
+assert_contains "$router_output" "## Loaded Output Router Skill" "router-only context"
+assert_contains "$router_output" "# Freeflow Interaction Contract" "router-only context"
+assert_not_contains "$router_output" "# Freeflow Workflow Bootstrap" "router-only context"
+rm -rf "$router_dir"
+
+all_dir="$(mktemp -d)"
+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" "all-capabilities context"
+assert_contains "$all_output" "## Loaded Output Router Skill" "all-capabilities context"
+assert_contains "$all_output" 'Current Freeflow default mode: `strict-workflow`.' "all-capabilities context"
+assert_contains "$all_output" "## Strict Workflow Overlay" "all-capabilities strict overlay"
+rm -rf "$all_dir"
+
+conversation_dir="$(mktemp -d)"
+mkdir -p "$conversation_dir/.freeflow"
+printf '{"defaultMode":"conversation"}\n' >"$conversation_dir/.freeflow/config.json"
+conversation_output="$(printf '{"cwd":"%s","model":"gpt-5"}\n' "$conversation_dir" | node "$HOOK_PATH" SessionStart)"
+assert_contains "$conversation_output" 'Current Freeflow default mode: `conversation`.' "conversation context"
+assert_contains "$conversation_output" '`conversation`: answer, discuss, critique, and inspect read-only' "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"
+rm -rf "$conversation_dir"
+
+observed_dir="$(mktemp -d)"
+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" "observed-routing config"
+assert_contains "$observed_output" "## Loaded Output Router Skill" "observed-routing config"
+rm -rf "$observed_dir"
+
+echo "runtime-context hook checks passed"