@hassangameryt/freeflow 0.7.3 → 0.9.0

package/pi-extension/dist/compaction/results.js

@@ -0,0 +1,159 @@
+import { estimateTokens } from "./carry.js";
+import { currentCycle } from "./harness.js";
+import { withoutGuidanceNotices } from "../tool-execution/guidance-notices.js";
+import { isFreeflowInstruction } from "../tool-execution/skill-reads.js";
+/**
+ * The result index: this cycle's larger tool results, each with an id the agent can carry by. Ids number tool results
+ * in branch order (r1, r2, ...), so they stay stable while the branch grows, and a result from an earlier cycle still
+ * resolves because its entry stays stored after compaction.
+ */
+const SIZE_FLOOR = 500;
+const MAX_ROWS = 40;
+/**
+ * The most tokens the rendered index can take: 40 rows of at most about 140 characters (an 80-character label plus
+ * id, tool, size and carried note) and a heading. Below the warning by more than this, the index cannot reach it.
+ */
+export const INDEX_TOKEN_BOUND = 2_000;
+/** Freeflow's own control calls: no evidence to carry, as routing's evidence selection also excludes them. */
+const CONTROL_TOOLS = new Set([
+  "delegate_work",
+  "return_work",
+  "select_evidence",
+  "routing_unit",
+  "compact_context",
+  // The same tools' names before Task 003's rename, still in sessions saved earlier.
+  "freeflow_delegate",
+  "freeflow_return",
+  "freeflow_project",
+  "freeflow_unit",
+  "freeflow_compact",
+]);
+/** A result's text without the guidance notices that joined it. */
+const resultText = (message) =>
+  withoutGuidanceNotices(
+    (message?.content ?? [])
+      .map((part) => (part?.type === "text" ? part.text : part?.type === "image" ? "[image]" : ""))
+      .join(""),
+  );
+function label(name, input) {
+  const firstLine = (text) =>
+    text
+      .split("\n")
+      .map((line) => line.trim())
+      .find(Boolean) ?? "";
+  const value =
+    typeof input?.command === "string"
+      ? input.command
+      : typeof input?.path === "string"
+        ? input.path
+        : typeof input?.url === "string"
+          ? input.url
+          : typeof input?.code === "string"
+            ? `script: ${firstLine(input.code)}`
+            : Array.isArray(input?.queries)
+              ? input.queries.join("; ")
+              : typeof input?.query === "string"
+                ? input.query
+                : name;
+  const line = firstLine(String(value));
+  return line.length > 80 ? `${line.slice(0, 77)}...` : line;
+}
+/** Every tool result on the branch with its id, oldest first. */
+function allResults(branch) {
+  const calls = new Map();
+  const results = [];
+  for (const entry of branch) {
+    const message = entry?.type === "message" ? entry.message : undefined;
+    if (message?.role === "assistant")
+      for (const block of message.content ?? [])
+        if (block?.type === "toolCall") calls.set(block.id, { name: block.name, input: block.arguments });
+    if (message?.role !== "toolResult") continue;
+    const call = calls.get(message.toolCallId);
+    const text = resultText(message);
+    const tool = call?.name ?? message.toolName ?? "tool";
+    results.push({
+      id: `r${results.length + 1}`,
+      tool,
+      label: label(tool, call?.input),
+      tokens: estimateTokens(text),
+      text,
+      ...firstLineOf(tool, call?.input, message),
+      entry,
+      input: call?.input,
+    });
+  }
+  return results;
+}
+/** A text read of a file starts at its offset (Pi's read is 1-based); an image or failed read has no lines. */
+function firstLineOf(tool, input, message) {
+  if (tool !== "read" || typeof input?.path !== "string" || message?.isError) return {};
+  if ((message?.content ?? []).some((part) => part?.type === "image")) return {};
+  return { firstLine: Number.isInteger(input?.offset) && input.offset > 0 ? input.offset : 1 };
+}
+/** The first line of the read result in a session entry, for a result carried by routing ref. */
+export function resultFirstLine(branch, entryId) {
+  return allResults(branch).find((result) => result.entry?.id === entryId)?.firstLine;
+}
+export function resolveResult(branch, id) {
+  const found = allResults(branch).find((result) => result.id === id);
+  if (!found) return undefined;
+  const { entry: _entry, input: _input, ...result } = found;
+  return result;
+}
+/**
+ * The tool results of the work in progress, newest first: the current assignment's under Cognitive Routing (by
+ * routing ref), otherwise this cycle's (by r-id). Freeflow's control calls and reads of its own instructions are left
+ * out: they are how the agent works, not what it worked on.
+ */
+export function scopeResults(branch, assignment) {
+  const cycle = new Set(currentCycle(branch));
+  return allResults(branch)
+    .filter((result) => (assignment ? assignment.entryIds.has(result.entry.id) : cycle.has(result.entry)))
+    .filter((result) => !CONTROL_TOOLS.has(result.tool) && !isFreeflowInstruction(result.tool, result.input))
+    .reverse()
+    .map(({ entry, input, ...result }) => ({
+      ...result,
+      id: assignment ? `ctx:${entry.id}` : result.id,
+      entryId: entry.id,
+      ...(typeof input?.path === "string" ? { path: input.path } : {}),
+    }));
+}
+/** This cycle's results above the size floor, newest first, then results the last Freeflow compaction carried. */
+export function resultIndex(branch) {
+  const cycle = new Set(currentCycle(branch));
+  const results = allResults(branch);
+  const rows = results
+    .filter(
+      (result) =>
+        cycle.has(result.entry) &&
+        result.tokens >= SIZE_FLOOR &&
+        !CONTROL_TOOLS.has(result.tool) &&
+        !isFreeflowInstruction(result.tool, result.input),
+    )
+    .reverse()
+    .map(({ id, tool, label, tokens }) => ({ id, tool, label, tokens }));
+  const latest = [...branch].reverse().find((entry) => entry?.type === "compaction" && entry.details?.freeflow);
+  for (const item of latest?.details?.freeflow?.carried ?? []) {
+    if (item?.kind !== "result" || rows.some((row) => row.id === item.ref)) continue;
+    const result = results.find((each) => each.id === item.ref);
+    if (result)
+      rows.push({
+        id: result.id,
+        tool: result.tool,
+        label: result.label,
+        tokens: result.tokens,
+        firstCycle: item.firstCycle,
+      });
+  }
+  return rows.slice(0, MAX_ROWS);
+}
+export function renderIndex(rows) {
+  if (!rows.length) return "No tool results large enough to list; carry files by path.";
+  return [
+    "Results you can carry by id:",
+    ...rows.map(
+      (row) =>
+        `- ${row.id}  ${row.tool}  ${row.label}  ~${row.tokens} tokens${row.firstCycle ? `  (carried since cycle ${row.firstCycle})` : ""}`,
+    ),
+  ].join("\n");
+}

package/pi-extension/dist/compaction/thresholds.js

@@ -0,0 +1,35 @@
+/**
+ * When compaction is due. Pi compacts on its own once context passes the window minus its reserve, and stays as the
+ * fallback for a full context. Freeflow says "compact now" 25k tokens before that, leaving room to prepare after a
+ * safe point, and warns earlier still: at 70% of the window, and at least 20k tokens before "compact now", so the
+ * agent has room to reach a safe point first.
+ */
+export const DEFAULT_RESERVE_TOKENS = 16_384;
+const WARNING_SHARE = 0.7;
+const WARNING_LEAD = 20_000;
+const COMPACT_NOW_HEADROOM = 25_000;
+/** Pi's effective reserve for a model: its per-model override, else the ordinary setting, else Pi's default. */
+export function reserveTokens(settings, model) {
+  const compaction = settings?.compaction ?? {};
+  const override = model ? compaction.modelOverrides?.[`${model.provider}/${model.id}`] : undefined;
+  const value = override?.reserveTokens ?? compaction.reserveTokens;
+  return Number.isSafeInteger(value) && value >= 0 ? value : DEFAULT_RESERVE_TOKENS;
+}
+export function thresholds(window, reserve) {
+  const trigger = Math.max(0, window - reserve);
+  const compactNow = Math.max(0, trigger - COMPACT_NOW_HEADROOM);
+  return {
+    window,
+    trigger,
+    warning: Math.max(0, Math.min(Math.floor(window * WARNING_SHARE), compactNow - WARNING_LEAD)),
+    compactNow,
+  };
+}
+/** The strictest thresholds across models that may receive the full history (the active model and routing workers). */
+export function strictest(models, settings) {
+  const all = models
+    .filter((model) => typeof model?.contextWindow === "number" && model.contextWindow > 0)
+    .map((model) => thresholds(model.contextWindow, reserveTokens(settings, model)));
+  if (!all.length) return undefined;
+  return all.reduce((a, b) => (b.warning < a.warning ? b : a));
+}

package/pi-extension/dist/compaction/tool.js

@@ -0,0 +1,57 @@
+export const COMPACT_CONTEXT = "compact_context";
+const DESCRIPTION =
+  "Compact the conversation into a new cycle. Use only when Freeflow says compaction is due or the user asks, and read the compaction skill first. Pass your summary and what to carry; compaction happens at the end of this turn, and the run continues from the summary, the carried context and a recovery message.";
+/** Registered once, declared only while Freeflow compaction is effective (see applyCompactionTools). */
+export function registerCompactionTool(pi, controller) {
+  pi.registerTool({
+    name: COMPACT_CONTEXT,
+    label: "Compact",
+    description: DESCRIPTION,
+    parameters: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        summary: {
+          type: "string",
+          description:
+            "The next cycle's working state, for a reader with none of this conversation. The compaction skill says what it must keep.",
+        },
+        carry: {
+          type: "array",
+          description:
+            "What to carry into the next cycle, within the budget the notice gives: files by path (read fresh at compaction, optional line ranges) and tool results by id from the notice's index.",
+          items: {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+              file: { type: "string" },
+              lines: { type: "array", items: { type: "integer" }, description: "[first, last], 1-based" },
+              result: {
+                type: "string",
+                description:
+                  "A tool result: its routing ref (such as ctx:1a2b3c4d) when Cognitive Routing is on, otherwise its id from the notice's list (such as r12)",
+              },
+            },
+          },
+        },
+      },
+      required: ["summary"],
+    },
+    // Callable from codemode scripts as well: agents that look for tools there first concluded, when it was missing,
+    // that they could not compact. The compaction still happens at the end of the turn, after the script returns.
+    exposure: "direct",
+    defaultActive: false,
+    executionMode: "sequential",
+    async execute(_id, params, _signal, _update, ctx) {
+      return { content: [{ type: "text", text: await controller.request(params, ctx) }] };
+    },
+  });
+}
+/** Declare or withdraw compact_context when compaction's effective state changes, keeping other tools in place. */
+export function applyCompactionTools(pi, effective) {
+  if (typeof pi.getActiveTools !== "function" || typeof pi.setActiveTools !== "function") return;
+  const current = pi.getActiveTools();
+  const present = current.includes(COMPACT_CONTEXT);
+  if (effective && !present) pi.setActiveTools([...current, COMPACT_CONTEXT]);
+  if (!effective && present) pi.setActiveTools(current.filter((name) => name !== COMPACT_CONTEXT));
+}

package/pi-extension/dist/host/branch.js

@@ -0,0 +1,13 @@
+// Keyed by the reader and its getBranch function, so a reader whose source is swapped is walked again.
+const cache = new WeakMap();
+export function cachedBranch(reader) {
+  if (!reader?.getBranch) return [];
+  // Without a leaf id the branch cannot be keyed; fall back to Pi's walk.
+  if (!reader.getLeafId) return reader.getBranch();
+  const leaf = reader.getLeafId();
+  const hit = cache.get(reader);
+  if (hit && hit.leaf === leaf && hit.source === reader.getBranch) return hit.branch;
+  const branch = Object.freeze([...reader.getBranch()]);
+  cache.set(reader, { leaf, source: reader.getBranch, branch });
+  return branch;
+}

package/pi-extension/dist/host/canonical.js

@@ -0,0 +1,12 @@
+const isObject = (value) => !!value && typeof value === "object" && !Array.isArray(value);
+/** Deterministic JSON: object keys sorted, undefined properties omitted, so equal values serialize equally. */
+export function canonical(value) {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
+  if (isObject(value))
+    return `{${Object.keys(value)
+      .filter((k) => value[k] !== undefined)
+      .sort()
+      .map((k) => `${JSON.stringify(k)}:${canonical(value[k])}`)
+      .join(",")}}`;
+  return JSON.stringify(value) ?? "null";
+}

package/pi-extension/dist/host/catalog.js

@@ -0,0 +1,62 @@
+import { fileURLToPath } from "node:url";
+/**
+ * Freeflow's fixed command and skill surface: the commands it registers, the skills it lists to the model, and where
+ * their files live.
+ */
+export const WORKFLOW_COMMANDS = [
+  { command: "discuss-work", skill: "discuss-work" },
+  { command: "track-work", skill: "track-work" },
+  { command: "write-docs", skill: "write-docs" },
+  { command: "execute-work", skill: "execute-work" },
+  { command: "verify-work", skill: "verify-work" },
+  { command: "review-work", skill: "review-work" },
+  { command: "deliver-work", skill: "deliver-work" },
+];
+export const CONTRIBUTOR_COMMANDS = ["setup-freeflow", "write-skill", "evaluate-behavior"];
+/**
+ * Every portable skill Freeflow ships, by directory name. The canonical list: validation scripts and tests compare the
+ * skills directory, the package and the coverage matrix against it instead of a fixed count.
+ */
+export const FREEFLOW_MODEL_SKILL_NAMES = [
+  "deliver-work",
+  "discuss-work",
+  "evaluate-behavior",
+  "execute-work",
+  "review-work",
+  "setup-freeflow",
+  "track-work",
+  "verify-work",
+  "write-docs",
+  "write-skill",
+];
+export const STABLE_FREEFLOW_SURFACE = Object.freeze({
+  enabled: true,
+  cognitiveRouting: { effective: true },
+  toolExecution: { effective: true },
+  compaction: { effective: true },
+  taskMemory: { effective: true },
+  messaging: { effective: true },
+});
+export function freeflowSkillPath(skillName) {
+  return fileURLToPath(new URL(`../../../skills/${skillName}/SKILL.md`, import.meta.url));
+}
+export function freeflowCapabilitySkillPath(skillName) {
+  return fileURLToPath(new URL(`../../../capabilities/${skillName}/SKILL.md`, import.meta.url));
+}
+export function freeflowModelSkillPaths(capabilityState = undefined) {
+  // A skill the user turned off is not loaded (config-validation.ts SWITCHABLE_SKILLS).
+  const off = capabilityState?.skills?.off ?? [];
+  const paths = FREEFLOW_MODEL_SKILL_NAMES.filter((skillName) => !off.includes(skillName)).map((skillName) =>
+    freeflowSkillPath(skillName),
+  );
+  if (capabilityState?.cognitiveRouting?.effective === true)
+    paths.push(freeflowCapabilitySkillPath("cognitive-routing"));
+  if (capabilityState?.compaction?.effective === true) paths.push(freeflowCapabilitySkillPath("compaction"));
+  if (capabilityState?.taskMemory?.effective === true) paths.push(freeflowCapabilitySkillPath("task-memory"));
+  if (capabilityState?.messaging?.effective === true) paths.push(freeflowCapabilitySkillPath("messaging"));
+  return paths;
+}
+export function skillPrompt(skill, args) {
+  const trimmed = args?.trim();
+  return trimmed ? `/skill:${skill}\n\n${trimmed}` : `/skill:${skill}`;
+}

package/pi-extension/dist/host/config-validation.js

@@ -0,0 +1,233 @@
+import { validateCompactionConfig } from "../compaction/config.js";
+import { validateTaskMemoryConfig } from "../task-memory/config.js";
+import { validateMessagingConfig } from "../messaging/config.js";
+import { validateToolExecutionConfig } from "../tool-execution/config.js";
+import { FREEFLOW_MODEL_SKILL_NAMES } from "./catalog.js";
+/**
+ * Whether a Freeflow config file is valid: one answer for Pi and for the session-start hooks of the other hosts, which
+ * import the built file. Also how the settings every host reads, `prompts`, `review` and `skills`, layer. Keep this module and its
+ * imports free of Pi packages; the hooks run in plain Node.
+ */
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** The runtime prompts Freeflow delivers on every host, each on unless a config turns it off. */
+export const RUNTIME_PROMPTS = ["core", "interactionContract", "workingMethod"];
+/** The keys `prompts` accepts: a master switch for all three, and one switch per prompt. */
+export const PROMPTS_KEYS = ["enabled", ...RUNTIME_PROMPTS];
+/** A section's master switch (`prompts.enabled`, `skills.enabled`) for two valid layers; on unless a config turns it off. */
+export function sectionEnabled(repository, local, section) {
+  const layer = (config) => (isRecord(config?.[section]) ? config[section] : {});
+  return (layer(local).enabled ?? layer(repository).enabled ?? true) === true;
+}
+function validatePromptsConfig(value) {
+  if (!isRecord(value)) return "prompts must be an object";
+  const unknown = Object.keys(value).find((key) => !PROMPTS_KEYS.includes(key));
+  if (unknown) return `prompts has unsupported key: ${unknown}`;
+  for (const key of PROMPTS_KEYS)
+    if (value[key] !== undefined && typeof value[key] !== "boolean") return `prompts.${key} must be a boolean`;
+  return null;
+}
+/**
+ * The prompts Freeflow delivers for two valid config layers: the personal layer overrides the repository's, and the
+ * master switch off turns all three off.
+ */
+export function selectedRuntimePrompts(repository, local) {
+  const layer = (config) => (isRecord(config?.prompts) ? config.prompts : {});
+  const [shared, personal] = [layer(repository), layer(local)];
+  const master = sectionEnabled(repository, local, "prompts");
+  const selection = {};
+  for (const key of RUNTIME_PROMPTS) selection[key] = master && (personal[key] ?? shared[key] ?? true) === true;
+  return selection;
+}
+/**
+ * The skills a user can turn off. Setup Freeflow always stays, so a user can repair a configuration; the capability
+ * skills follow their capability's switch. On Pi an off skill is not loaded; other hosts load plugin skills themselves,
+ * so there the Runtime State only tells the agent not to use it.
+ */
+export const SWITCHABLE_SKILLS = FREEFLOW_MODEL_SKILL_NAMES.filter((name) => name !== "setup-freeflow").sort();
+/** The keys `skills` accepts: a master switch for every switchable skill, and one switch per skill. */
+export const SKILLS_KEYS = ["enabled", ...SWITCHABLE_SKILLS];
+function validateSkillsConfig(value) {
+  if (!isRecord(value)) return "skills must be an object";
+  const unknown = Object.keys(value).find((key) => !SKILLS_KEYS.includes(key));
+  if (unknown) return `skills has unsupported key: ${unknown}; use ${SKILLS_KEYS.join(", ")}`;
+  for (const [key, on] of Object.entries(value)) if (typeof on !== "boolean") return `skills.${key} must be a boolean`;
+  return null;
+}
+/**
+ * The skills turned off for two valid config layers: the personal layer overrides the repository's, skill by skill,
+ * and the master switch off turns every switchable skill off.
+ */
+export function skillsOff(repository, local) {
+  const layer = (config) => (isRecord(config?.skills) ? config.skills : {});
+  const [shared, personal] = [layer(repository), layer(local)];
+  if (!sectionEnabled(repository, local, "skills")) return [...SWITCHABLE_SKILLS];
+  return SWITCHABLE_SKILLS.filter((name) => (personal[name] ?? shared[name] ?? true) === false);
+}
+/** The Runtime State line for skills the user turned off; none while every skill is on. */
+export function skillsStateLine(off) {
+  return off?.length ? `Skills off: ${off.map((name) => `\`${name}\``).join(", ")}; do not open or follow them.` : null;
+}
+/**
+ * How Review Work reviews finished work. Without the key it runs `auto`, its own risk gate; `off` and `always` are the
+ * user's choice for every task, and `model` names the model a reviewer runs on. `auto` is accepted so a personal file
+ * can return a shared `off` or `always` to the default.
+ */
+export const REVIEW_MODES = ["auto", "off", "always"];
+export const REVIEW_KEYS = ["mode", "model"];
+function validateReviewConfig(value) {
+  if (!isRecord(value)) return "review must be an object";
+  const unknown = Object.keys(value).find((key) => !REVIEW_KEYS.includes(key));
+  if (unknown) return `review has unsupported key: ${unknown}`;
+  if (value.mode !== undefined && !REVIEW_MODES.includes(value.mode))
+    return `review.mode must be one of ${REVIEW_MODES.join(", ")}`;
+  // The model is shown to the agent in the Runtime State, so it must fit on one line in a code span.
+  if (
+    value.model !== undefined &&
+    (typeof value.model !== "string" || !value.model.trim() || /[\p{Cc}`]/u.test(value.model))
+  )
+    return "review.model must be a non-empty model name on one line";
+  return null;
+}
+/** Review settings for two valid config layers: the personal layer overrides the repository's, field by field. */
+export function resolveReviewSettings(repository, local) {
+  const layer = (config) => (isRecord(config?.review) ? config.review : {});
+  const [shared, personal] = [layer(repository), layer(local)];
+  const mode = personal.mode ?? shared.mode ?? "auto";
+  const model = personal.model ?? shared.model;
+  return model === undefined ? { mode } : { mode, model };
+}
+/** The Runtime State line for the user's review choice; none for the default, `auto` with no model. */
+export function reviewStateLine(review) {
+  if (!review || (review.mode === "auto" && review.model === undefined)) return null;
+  return `Review: \`${review.mode}\`${review.model === undefined ? "" : `, reviewer model \`${review.model}\``}`;
+}
+function removedContextConfigError(value, filePath) {
+  const removedKeys = ["contextVirtualization", "conversationHistory"].filter((key) =>
+    Object.prototype.hasOwnProperty.call(value, key),
+  );
+  return removedKeys.length > 0
+    ? `Removed Freeflow context setting(s) in ${filePath}: ${removedKeys.join(", ")}. Delete those keys before using Freeflow.`
+    : null;
+}
+function validateCoreConfigFields(value) {
+  if (value.enabled !== undefined && typeof value.enabled !== "boolean") {
+    return "enabled must be a boolean";
+  }
+  return null;
+}
+/** The top-level keys Freeflow acts on; the settings test checks that every key under them has a settings row. */
+export const CONFIG_SECTIONS = [
+  "enabled",
+  "cognitiveRouting",
+  "toolExecution",
+  "compaction",
+  "taskMemory",
+  "messaging",
+  "prompts",
+  "review",
+  "skills",
+];
+// outputRouter, observedRouting, and scriptTransform belong to retired features; they are accepted and ignored so
+// existing configs keep loading.
+const RETIRED_SECTIONS = ["outputRouter", "observedRouting", "scriptTransform"];
+export function validateRepositoryConfig(value) {
+  if (!isRecord(value)) {
+    return "config must be a JSON object";
+  }
+  const removedContextError = removedContextConfigError(value, ".freeflow/config.json");
+  if (removedContextError) return removedContextError;
+  const allowedKeys = new Set([...CONFIG_SECTIONS, ...RETIRED_SECTIONS]);
+  for (const key of Object.keys(value)) {
+    if (!allowedKeys.has(key)) {
+      return `unsupported top-level config key: ${key}`;
+    }
+  }
+  const coreError = validateCoreConfigFields(value);
+  if (coreError) return coreError;
+  for (const key of ["outputRouter", "observedRouting", "scriptTransform"]) {
+    if (value[key] !== undefined && !isRecord(value[key])) {
+      return `${key} must be an object`;
+    }
+  }
+  if (value.toolExecution !== undefined) {
+    const error = validateToolExecutionConfig(value.toolExecution);
+    if (error) return error;
+  }
+  if (value.prompts !== undefined) {
+    const error = validatePromptsConfig(value.prompts);
+    if (error) return error;
+  }
+  if (value.compaction !== undefined) {
+    const error = validateCompactionConfig(value.compaction);
+    if (error) return error;
+  }
+  if (value.taskMemory !== undefined) {
+    const error = validateTaskMemoryConfig(value.taskMemory);
+    if (error) return error;
+  }
+  if (value.messaging !== undefined) {
+    const error = validateMessagingConfig(value.messaging);
+    if (error) return error;
+  }
+  if (value.skills !== undefined) {
+    const error = validateSkillsConfig(value.skills);
+    if (error) return error;
+  }
+  if (value.review !== undefined) return validateReviewConfig(value.review);
+  return null;
+}
+export function validateLocalConfig(value) {
+  if (!isRecord(value)) {
+    return "local config must be a JSON object";
+  }
+  const removedContextError = removedContextConfigError(value, ".freeflow/local.json");
+  if (removedContextError) return removedContextError;
+  // processing belongs to a retired feature; it is accepted and ignored so existing local configs keep loading.
+  const allowedKeys = new Set([
+    "enabled",
+    "processing",
+    "cognitiveRouting",
+    "toolExecution",
+    "compaction",
+    "taskMemory",
+    "messaging",
+    "prompts",
+    "review",
+    "skills",
+  ]);
+  for (const key of Object.keys(value)) {
+    if (!allowedKeys.has(key)) {
+      return `unsupported top-level local config key: ${key}`;
+    }
+  }
+  const coreError = validateCoreConfigFields(value);
+  if (coreError) return coreError;
+  if (value.toolExecution !== undefined) {
+    const error = validateToolExecutionConfig(value.toolExecution);
+    if (error) return error;
+  }
+  if (value.prompts !== undefined) {
+    const error = validatePromptsConfig(value.prompts);
+    if (error) return error;
+  }
+  if (value.compaction !== undefined) {
+    const error = validateCompactionConfig(value.compaction);
+    if (error) return error;
+  }
+  if (value.taskMemory !== undefined) {
+    const error = validateTaskMemoryConfig(value.taskMemory);
+    if (error) return error;
+  }
+  if (value.messaging !== undefined) {
+    const error = validateMessagingConfig(value.messaging);
+    if (error) return error;
+  }
+  if (value.skills !== undefined) {
+    const error = validateSkillsConfig(value.skills);
+    if (error) return error;
+  }
+  if (value.review !== undefined) return validateReviewConfig(value.review);
+  return null;
+}