@hassangameryt/freeflow 0.3.0 → 0.4.0

package/hooks/freeflow-runtime-context.mjs

@@ -46,149 +46,265 @@ function findWorkspaceRoot(cwd) {
   }
 }
 
-function loadRuntimeContext() {
-  const modeContractSkill = readText(path.join(PLUGIN_ROOT, "skills", "mode-contract", "SKILL.md"));
-  const workflowSkill = readText(path.join(PLUGIN_ROOT, "skills", "workflow", "SKILL.md"));
-  const interviewGateSkill = readText(
-    path.join(PLUGIN_ROOT, "skills", "interview-gate", "SKILL.md")
-  );
-  const discoverSkill = readText(path.join(PLUGIN_ROOT, "skills", "discover", "SKILL.md"));
-  const outputRouterSkill = readText(path.join(PLUGIN_ROOT, "skills", "output-router", "SKILL.md"));
-
-  if (!modeContractSkill || !workflowSkill || !interviewGateSkill || !discoverSkill || !outputRouterSkill) {
+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 { modeContractSkill, workflowSkill, interviewGateSkill, discoverSkill, outputRouterSkill };
+  return { interactionContract, workflowSkill, outputRouterSkill };
 }
 
 function readConfig(root) {
-  const configPath = path.join(root, ".freeflow", "config.json");
-  const body = readText(configPath);
-  if (!body) {
-    return { exists: false, valid: false, defaultMode: null };
+  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(body);
-    const valid = isValidSetupConfig(parsed);
-    return { exists: true, valid, defaultMode: parsed?.defaultMode ?? null };
-  } catch {
-    return { exists: true, valid: false, defaultMode: null };
+    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 (!value || typeof value !== "object" || Array.isArray(value)) {
-    return false;
+  if (!isRecord(value)) {
+    return "repository config must be a JSON object";
   }
 
-  const allowedKeys = new Set(["defaultMode", "outputRouter", "observedRouting", "scriptTransform"]);
+  const allowedKeys = new Set([
+    "enabled",
+    "defaultMode",
+    "interactionContract",
+    "skills",
+    "outputRouter",
+    "observedRouting",
+    "scriptTransform",
+  ]);
   if (!Object.keys(value).every((key) => allowedKeys.has(key))) {
-    return false;
+    return "repository config contains unsupported top-level keys";
   }
 
-  if (!Object.prototype.hasOwnProperty.call(value, "defaultMode") || !VALID_MODES.has(value.defaultMode)) {
-    return false;
+  const coreError = validateCoreConfigFields(value);
+  if (coreError) {
+    return coreError;
   }
 
-  if (Object.prototype.hasOwnProperty.call(value, "outputRouter")) {
-    if (!Boolean(value.outputRouter) || typeof value.outputRouter !== "object" || Array.isArray(value.outputRouter)) {
-      return false;
+  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;
+}
 
-  if (Object.prototype.hasOwnProperty.call(value, "observedRouting")) {
-    if (!Boolean(value.observedRouting) || typeof value.observedRouting !== "object" || Array.isArray(value.observedRouting)) {
-      return false;
-    }
+function isValidLocalConfig(value) {
+  if (!isRecord(value)) {
+    return "local config must be a JSON object";
   }
 
-  if (Object.prototype.hasOwnProperty.call(value, "scriptTransform")) {
-    if (!Boolean(value.scriptTransform) || typeof value.scriptTransform !== "object" || Array.isArray(value.scriptTransform)) {
-      return false;
-    }
+  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);
+}
 
-  return true;
+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) {
-  const config = readConfig(root);
-  const agents = readText(path.join(root, "AGENTS.md")) || "";
-  const claude = readText(path.join(root, "CLAUDE.md")) || "";
-  const claudeRule = readText(path.join(root, ".claude", "rules", "freeflow-core.md")) || "";
-
-  const codexActive =
-    agents.includes("## Freeflow") && agents.includes("Use Freeflow for consequential work");
-  const claudeActive =
-    claude.includes("@.claude/rules/freeflow-core.md") &&
-    claudeRule.includes("Use Freeflow for consequential work");
-  const activeHosts = [
-    codexActive ? "Codex AGENTS.md" : null,
-    claudeActive ? "Claude CLAUDE.md import" : null
-  ].filter(Boolean);
-
-  return { config, activeHosts };
+  return { config: readConfig(root) };
 }
 
 function configStatus(config) {
-  if (config.valid) {
-    return `defaultMode \`${config.defaultMode}\``;
+  if (!config.valid) {
+    return "invalid layered configuration";
   }
-  if (config.exists) {
-    return "invalid `.freeflow/config.json`; effective default mode falls back to `workflow`";
+  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 "missing `.freeflow/config.json`; effective default mode falls back to `workflow`";
+
+  return [];
 }
 
 function modeGuidance(mode) {
   return [
     `Current Freeflow default mode: \`${mode}\`.`,
-    "Treat this as the repo default at session start, resume, clear, and compact.",
-    "For mode changes or mode interpretation, use `mode-contract`.",
-    "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."
+    "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 setup = inspectSetup(root);
-  const parts = [];
-  const modeStatus = configStatus(setup.config);
-
-  if (setup.config.valid && setup.activeHosts.length > 0) {
-    parts.push(
-      `Setup status: configured for ${setup.activeHosts.join(" and ")} with ${modeStatus}.`
-    );
-    parts.push(...modeGuidance(setup.config.defaultMode));
-  } else if (setup.config.exists || setup.activeHosts.length > 0) {
-    const issues = [];
-    if (!setup.config.valid) {
-      issues.push("valid `.freeflow/config.json` is missing");
-    }
-    if (setup.activeHosts.length === 0) {
-      issues.push("no Freeflow activation block/import was found");
-    }
-    parts.push(`Setup status: partial setup; ${issues.join(" and ")}.`);
-    parts.push(`Repo default mode: ${modeStatus}.`);
-    parts.push(
-      "Required user-facing notice: in the next assistant reply, tell the user Freeflow setup is incomplete and recommend `/setup-freeflow` or completing the missing host/config setup. Do this even if the user's prompt is casual, such as a greeting."
-    );
-    parts.push(
-      "Before consequential work in this repo, complete setup or ask which host setup to complete unless the user explicitly bypasses setup."
-    );
-  } else {
-    parts.push("Setup status: this repo does not appear to be set up for Freeflow yet.");
-    parts.push(`Repo default mode: ${modeStatus}.`);
-    parts.push(
-      "Required user-facing notice: in the next assistant reply, tell the user Freeflow is installed but this repo is not set up yet, and recommend `/setup-freeflow`. Do this even if the user's prompt is casual, such as a greeting."
-    );
-    parts.push(
-      "Before consequential work in this repo, use `/setup-freeflow` or ask whether to set up Freeflow for Codex, Claude, or both. Do not start implementation solely because the plugin is installed."
-    );
+  const { config } = inspectSetup(root);
+  if (!config.valid) {
+    return "Setup status: Freeflow is not configured for this repo.";
   }
 
-  return parts.join("\n");
+  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) {
@@ -199,10 +315,48 @@ function shouldInject(eventName) {
   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 { modeContractSkill, workflowSkill, interviewGateSkill, discoverSkill, outputRouterSkill } = loadRuntimeContext();
+  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",
     "",
@@ -212,40 +366,10 @@ function buildContext(input) {
     "## Repo Setup",
     buildSetupStatus(root),
     "",
-    "## Freeflow Runtime Priority",
-    "Mode Contract handles mode setting, mode interpretation, and mode mismatch before task routing when mode is at issue.",
-    "",
-    "Priority order for matched non-mode workflow skills:",
-    "",
-    "1. Workflow classifies conversation versus consequential work.",
-    "2. Interview Gate stops silent decisions, user-owned decisions, source-truth conflicts, and question-to-action mistakes.",
-    "3. Discover handles context-building after no immediate stop condition remains. Use it before first repo/code exploration or design answers for consequential product/API/tool/runtime hypotheses.",
-    "4. Output Router chooses evidence transport after the workflow/interview/discover route is clear.",
-    "",
-    "## Loaded Mode Contract Skill",
-    "```md",
-    modeContractSkill.trim(),
-    "```",
-    "",
-    "## Loaded Workflow Skill",
-    "```md",
-    workflowSkill.trim(),
-    "```",
-    "",
-    "## Loaded Interview Gate Skill",
-    "```md",
-    interviewGateSkill.trim(),
-    "```",
-    "",
-    "## Loaded Discover Skill",
-    "```md",
-    discoverSkill.trim(),
-    "```",
-    "",
-    "## Loaded Output Router Skill",
-    "```md",
-    outputRouterSkill.trim(),
-    "```"
+    ...capabilityStatus(setup.config),
+    ...interactionSection,
+    ...skillSections,
+    ...outputRouterSection,
   ].join("\n");
 }
 
@@ -263,9 +387,9 @@ function emitAdditionalContext(eventName, input, additionalContext) {
     `${JSON.stringify({
       hookSpecificOutput: {
         hookEventName: eventName,
-        additionalContext
-      }
-    })}\n`
+        additionalContext,
+      },
+    })}\n`,
   );
 }
 
@@ -281,7 +405,11 @@ function main() {
     return;
   }
 
-  emitAdditionalContext(eventName, input, buildContext(input));
+  const additionalContext = buildContext(input);
+  if (!additionalContext.trim()) {
+    return;
+  }
+  emitAdditionalContext(eventName, input, additionalContext);
 }
 
 try {