@hassangameryt/freeflow 0.8.0 → 0.9.0

package/hooks/claude/hooks.json

@@ -1,15 +1,25 @@
 {
-  "description": "Load Freeflow core runtime context in Claude Code.",
+  "description": "Load Freeflow core runtime context in Claude Code, one hook per prompt: Claude Code caps each hook's context at 10,000 characters.",
   "hooks": {
     "SessionStart": [
       {
-        "matcher": "startup|resume|clear|compact",
+        "matcher": "startup|resume|clear|compact|fork",
         "hooks": [
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/adapters/claude-session-start.mjs\" SessionStart",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/adapters/claude-session-start.mjs\" SessionStart core",
             "timeout": 5,
             "statusMessage": "Loading Freeflow context"
+          },
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/adapters/claude-session-start.mjs\" SessionStart interactionContract",
+            "timeout": 5
+          },
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/adapters/claude-session-start.mjs\" SessionStart workingMethod",
+            "timeout": 5
           }
         ]
       }

package/hooks/codex/hooks.json

@@ -9,7 +9,8 @@
             "type": "command",
             "command": "node \"${PLUGIN_ROOT}/hooks/adapters/codex-session-start.mjs\" SessionStart",
             "timeout": 5,
-            "statusMessage": "Loading Freeflow context"
+            "statusMessage": "Loading Freeflow context",
+            "additionalContextLimit": 8000
           }
         ]
       }

package/hooks/shared/runtime-context.mjs

@@ -2,6 +2,16 @@ import fs from "node:fs";
 import path from "node:path";
 import process from "node:process";
 import { fileURLToPath, pathToFileURL } from "node:url";
+// The validator Pi uses, so a config is valid or invalid on every host alike.
+import {
+  resolveReviewSettings,
+  reviewStateLine,
+  selectedRuntimePrompts,
+  skillsOff,
+  skillsStateLine,
+  validateLocalConfig,
+  validateRepositoryConfig,
+} from "../../pi-extension/dist/host/config-validation.js";
 
 const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
 export const PLUGIN_ROOT = path.resolve(SCRIPT_DIR, "../..");
@@ -62,57 +72,6 @@ function readConfigLayer(filePath, validate) {
   }
 }
 
-function isRecord(value) {
-  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
-}
-
-function removedContextConfigError(value, filePath) {
-  const removedKeys = ["contextVirtualization", "conversationHistory"].filter((key) => Object.hasOwn(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 (Object.hasOwn(value, "enabled") && typeof value.enabled !== "boolean") {
-    return "enabled must be a boolean";
-  }
-  return null;
-}
-
-function isValidSetupConfig(value) {
-  if (!isRecord(value)) return "repository config must be a JSON object";
-
-  const removedContextError = removedContextConfigError(value, ".freeflow/config.json");
-  if (removedContextError) return removedContextError;
-
-  const allowedKeys = new Set(["enabled", "outputRouter", "observedRouting", "scriptTransform", "cognitiveRouting"]);
-  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.hasOwn(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 removedContextError = removedContextConfigError(value, ".freeflow/local.json");
-  if (removedContextError) return removedContextError;
-
-  const allowedKeys = new Set(["enabled", "processing", "cognitiveRouting"]);
-  if (!Object.keys(value).every((key) => allowedKeys.has(key))) {
-    return "local config contains unsupported top-level keys";
-  }
-  return validateCoreConfigFields(value);
-}
-
 function resolveLayeredValue(repository, local, key, fallback) {
   if (Object.hasOwn(local, key)) return local[key];
   if (Object.hasOwn(repository, key)) return repository[key];
@@ -124,8 +83,8 @@ function resolveCoreConfig(repository, local) {
 }
 
 export function readConfig(root) {
-  const repository = readConfigLayer(path.join(root, ".freeflow", "config.json"), isValidSetupConfig);
-  const local = readConfigLayer(path.join(root, ".freeflow", "local.json"), isValidLocalConfig);
+  const repository = readConfigLayer(path.join(root, ".freeflow", "config.json"), validateRepositoryConfig);
+  const local = readConfigLayer(path.join(root, ".freeflow", "local.json"), validateLocalConfig);
   const localValid = !local.exists || local.valid;
   const configured = repository.valid && localValid;
   const core = resolveCoreConfig(repository.valid ? repository.parsed : {}, local.valid ? local.parsed : {});
@@ -139,42 +98,67 @@ export function readConfig(root) {
     localExists: local.exists,
     localValid,
     error: repository.valid ? local.error : repository.error,
+    errorPath: repository.valid ? ".freeflow/local.json" : ".freeflow/config.json",
     enabled,
+    prompts: selectedRuntimePrompts(repository.parsed, local.parsed),
+    review: resolveReviewSettings(repository.parsed, local.parsed),
+    skillsOff: skillsOff(repository.parsed, local.parsed),
   };
 }
 
-function loadRuntimeContext() {
-  const corePrompt = readText(path.join(PLUGIN_ROOT, "runtime", "prompts", "core.md"));
-  const interactionContract = readText(path.join(PLUGIN_ROOT, "runtime", "prompts", "interaction-contract.md"));
-
-  if (!corePrompt || !interactionContract) {
-    throw new Error("Freeflow core runtime prompt files are missing.");
+const PROMPT_FILES = {
+  core: "core.md",
+  interactionContract: "interaction-contract.md",
+  workingMethod: "working-method.md",
+};
+
+/**
+ * The selected prompts in Pi's order, or only `part` when a host delivers each prompt through its own hook. A selected
+ * core or Interaction Contract must exist; the Working Method is optional, as on Pi.
+ */
+function loadRuntimeContext(selection, part) {
+  const prompts = [];
+  for (const [key, file] of Object.entries(PROMPT_FILES)) {
+    if (!selection[key] || (part && key !== part)) continue;
+    const text = readText(path.join(PLUGIN_ROOT, "runtime", "prompts", file));
+    if (!text && key !== "workingMethod") throw new Error("Freeflow core runtime prompt files are missing.");
+    if (text) prompts.push(text);
   }
-
-  return { corePrompt, interactionContract };
+  return prompts;
 }
 
-function runtimeStateContext() {
-  return ["# Freeflow Runtime State", "", "Freeflow: active"].join("\n");
+// The review and skills lines are Pi's, and as on Pi only a choice the user made adds them. This host loads plugin
+// skills itself, so the skills line is how an off skill reaches the agent here.
+function runtimeStateContext(config) {
+  const lines = [reviewStateLine(config.review), skillsStateLine(config.skillsOff)].filter(Boolean);
+  return ["# Freeflow Runtime State", "", "Freeflow: active", ...lines].join("\n");
 }
 
-export function renderRuntimeContext(root) {
+/**
+ * The session-start context for the repository at `root`: every selected prompt, or one `part` of it (`core`,
+ * `interactionContract`, `workingMethod`). Claude Code caps each hook's context at 10,000 characters, so it runs one
+ * hook per part. A configuration error and the Runtime State, which the core prompt refers to, travel with the core.
+ */
+export function renderRuntimeContext(root, part = undefined) {
+  if (part !== undefined && !Object.hasOwn(PROMPT_FILES, part)) return "";
   const config = readConfig(root);
   if (!config.valid) {
-    if (config.error?.startsWith("Removed Freeflow context setting(s) in ")) {
-      return [
-        "# Freeflow Configuration Error",
-        "",
-        `Freeflow is inactive. ${config.error}`,
-        "Remove the named key(s), then restart the session.",
-      ].join("\n");
-    }
-    return "";
+    // A missing repository config means Freeflow is not set up here: stay silent. An existing invalid file is reported,
+    // as Pi's status does, so Freeflow is not silently missing.
+    if (!config.error || (part && part !== "core")) return "";
+    return [
+      "# Freeflow Configuration Error",
+      "",
+      `Freeflow is inactive because ${config.errorPath} is invalid: ${config.error}`,
+      `Fix ${config.errorPath} or use the setup-freeflow skill, then start a new session.`,
+    ].join("\n");
   }
   if (!config.enabled) return "";
 
-  const { corePrompt, interactionContract } = loadRuntimeContext();
-  return [corePrompt, interactionContract, runtimeStateContext()].filter(Boolean).join("\n\n");
+  // The user chooses the prompts on hosts other than Pi; with none selected there is nothing to deliver.
+  const prompts = loadRuntimeContext(config.prompts, part);
+  if (config.prompts.core && (!part || part === "core")) prompts.push(runtimeStateContext(config));
+  return prompts.join("\n\n");
 }
 
 export function emitHookOutput(output) {
@@ -188,7 +172,8 @@ export function runSessionStartAdapter({ eventNames, getWorkspaceCwd, formatOutp
   if (!eventNames.includes(eventName)) return;
 
   const root = findWorkspaceRoot(getWorkspaceCwd(input));
-  const additionalContext = renderRuntimeContext(root);
+  // An optional third argument names the one prompt this hook delivers.
+  const additionalContext = renderRuntimeContext(root, process.argv[3]);
   if (additionalContext.trim()) {
     emitHookOutput(formatOutput({ eventName, input, additionalContext }));
   }
@@ -204,5 +189,12 @@ export function runSafely(run) {
 }
 
 export function isMainModule(metaUrl) {
-  return process.argv[1] && pathToFileURL(path.resolve(process.argv[1])).href === metaUrl;
+  if (!process.argv[1]) return false;
+  // Compare real paths: Node resolves symlinks in import.meta.url but not in argv, and a host may run the plugin from a
+  // symlinked directory (macOS /var is /private/var).
+  try {
+    return fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(metaUrl));
+  } catch {
+    return pathToFileURL(path.resolve(process.argv[1])).href === metaUrl;
+  }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hassangameryt/freeflow",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Feedback-based control system for coding agents.",
   "publishConfig": {
     "access": "public"
@@ -22,31 +22,46 @@
     "build:pi-extension": "node -e \"require('node:fs').rmSync('pi-extension/dist', { recursive: true, force: true })\" && tsc -p pi-extension/tsconfig.json && npm run format:pi-extension-dist",
     "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:host-manifests && 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 && npm run check:eval-coverage",
+    "lint": "eslint pi-extension/src",
+    "check": "npm run typecheck && npm run lint && npm run check:source && npm run check:host-manifests && npm run check:changelog && npm run check:release-workflow && npm run check:docs && npm run check:dev-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 && npm run check:eval-coverage && npm run check:eval-definitions && npm run check:coverage-matrix && npm run check:skill-routing && npm run check:incident-fixtures",
     "check:source": "node scripts/validation/check-source-files.mjs",
     "check:host-manifests": "node scripts/validation/check-host-manifests.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:dev-docs": "node skills/write-docs/scripts/docs-check.mjs --strict dev-docs",
     "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:eval-coverage": "node scripts/validation/check-eval-coverage.mjs",
+    "check:eval-coverage": "node scripts/validation/check-eval-coverage.mjs --strict",
+    "check:eval-definitions": "node scripts/validation/check-eval-definitions.mjs",
+    "check:coverage-matrix": "node .skill-eval/scripts/verify-coverage-matrix.mjs",
+    "check:skill-routing": "node scripts/validation/check-skill-routing-doc.mjs",
+    "check:incident-fixtures": "node .skill-eval/workflow/scripts/verify-incident-fixtures.mjs",
     "check:release-metadata": "scripts/validation/validate-release-metadata.sh --mode prepublish",
     "perf:request": "node scripts/perf/request-overhead.mjs",
+    "eval:gate": "node .skill-eval/scripts/gate.mjs",
+    "test": "npm run test:pi-extension && npm run test:host-manifests && npm run test:skill-author && npm run test:skill-eval && npm run test:track-work && npm run test:discuss-work && npm run test:execute-work && npm run test:deliver-work && npm run test:review-work && npm run test:verify-work && npm run test:write-docs && npm run test:freeflow-snapshot && npm run test:release-utils && npm run test:release-workflow && npm run test:changelog && npm run test:docs && npm run test:eval-coverage && npm run test:guards",
     "test:pi-extension": "npm run build && node --test $(find pi-extension/tests -name '*.test.js' | sort)",
     "test:host-manifests": "node --test scripts/validation/check-host-manifests.test.mjs hooks/tests/check-host-adapters.test.mjs",
     "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)",
+    "test:skill-eval": "node --test $(find .skill-eval/evaluate-behavior/tests -name '*.test.mjs' | sort)",
     "test:track-work": "node --test .skill-eval/track-work/tests/*.test.mjs",
+    "test:discuss-work": "node --test .skill-eval/discuss-work/tests/*.test.mjs",
+    "test:execute-work": "node --test .skill-eval/execute-work/tests/*.test.mjs",
+    "test:deliver-work": "node --test .skill-eval/deliver-work/tests/*.test.mjs",
+    "test:review-work": "node --test .skill-eval/review-work/tests/*.test.mjs",
+    "test:verify-work": "node --test .skill-eval/verify-work/tests/*.test.mjs",
+    "test:write-docs": "node --test .skill-eval/write-docs/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",
     "test:eval-coverage": "node --test scripts/validation/check-eval-coverage.test.mjs",
+    "test:guards": "node --test scripts/validation/guards.test.mjs",
     "release:prepare": "node scripts/release.mjs",
     "release:notes": "node scripts/release-notes.mjs",
     "snapshot:refresh": "node scripts/freeflow-snapshot.mjs"
@@ -82,7 +97,6 @@
     "image": "https://raw.githubusercontent.com/hassan-mohiddin/freeflow/main/assets/freeflow-plugin-icon-transparent.png"
   },
   "files": [
-    "plugin.json",
     "gemini-extension.json",
     ".agents/**",
     ".claude-plugin/**",
@@ -113,11 +127,14 @@
     "@earendil-works/pi-tui": ">=0.99.1"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "1.0.1",
-    "@earendil-works/pi-tui": "1.0.1",
+    "@earendil-works/pi-coding-agent": "1.4.0",
+    "@earendil-works/pi-tui": "1.4.0",
+    "@eslint/js": "10.0.1",
     "@types/node": "^22.15.30",
+    "eslint": "10.12.0",
     "prettier": "3.9.5",
-    "typescript": "^5.8.3"
+    "typescript": "^5.8.3",
+    "typescript-eslint": "8.71.1"
   },
   "dependencies": {}
 }

package/pi-extension/dist/ask-user/ask.js

@@ -0,0 +1,108 @@
+import { QuestionForm } from "./form.js";
+/*
+ * Putting questions to the user in whatever UI the session has:
+ * - the terminal: one QuestionForm (descriptions, own answer, notes, multi-select);
+ * - RPC clients: one `select` per question (option and description on one line) and an `input` for the user's own
+ *   answer; multi-select repeats `select` until the user picks Done;
+ * - no UI (print, JSON): unavailable, so the caller asks in its reply.
+ * Closing any dialog without answering dismisses the whole question.
+ */
+const OWN = "Type my own answer";
+const DONE = "Done";
+export async function askUser(ctx, questions, signal, form = {}) {
+  if (!ctx?.hasUI || !ctx.ui) return { status: "unavailable", reason: "No one can answer a dialog in this session." };
+  if (ctx.mode === "tui" && typeof ctx.ui.custom === "function") {
+    if (signal?.aborted) return { status: "dismissed" };
+    let timer;
+    let onAbort;
+    const outcome = await ctx.ui.custom((tui, theme, _keybindings, done) => {
+      const view = new QuestionForm(questions, theme, done, () => tui?.requestRender?.(), form);
+      // Pi's custom dialog takes no signal: an aborted call (the user pressed Escape on the turn) closes it here.
+      if (signal) {
+        onAbort = () => done({ status: "dismissed" });
+        signal.addEventListener("abort", onAbort, { once: true });
+      }
+      // A dialog with a deadline counts down and closes itself unanswered when it passes.
+      if (form.deadline !== undefined)
+        timer = setInterval(() => {
+          if (Date.now() >= form.deadline) done({ status: "dismissed" });
+          else {
+            view.invalidate();
+            tui?.requestRender?.();
+          }
+        }, 1000);
+      return view;
+    });
+    if (timer) clearInterval(timer);
+    if (onAbort) signal?.removeEventListener("abort", onAbort);
+    return outcome ?? { status: "dismissed" };
+  }
+  const answers = [];
+  for (const question of questions) {
+    const answer = await askOne(ctx, question, signal);
+    if (!answer) return { status: "dismissed" };
+    answers.push(answer);
+  }
+  return { status: "answered", answers };
+}
+async function askOne(ctx, question, signal) {
+  const title = `${question.header} · ${question.question}`;
+  const labels = question.options.map((option) =>
+    option.description ? `${option.label} — ${option.description}` : option.label,
+  );
+  const base = { header: question.header, question: question.question };
+  const own = async () => {
+    const text = (await ctx.ui.input(title, "Your answer", signal ? { signal } : undefined))?.trim();
+    return text ? { ...base, selected: [], text } : undefined;
+  };
+  if (!question.multiSelect) {
+    const choice = await ctx.ui.select(title, [...labels, OWN], signal ? { signal } : undefined);
+    if (choice === undefined) return undefined;
+    if (choice === OWN) return own();
+    return { ...base, selected: [question.options[labels.indexOf(choice)].label] };
+  }
+  const picked = new Set();
+  for (;;) {
+    const shown = labels.map((label, at) => `${picked.has(at) ? "[x]" : "[ ]"} ${label}`);
+    const choice = await ctx.ui.select(
+      `${title} (choose one or more, then ${DONE})`,
+      [...shown, OWN, ...(picked.size ? [DONE] : [])],
+      signal ? { signal } : undefined,
+    );
+    if (choice === undefined) return undefined;
+    if (choice === OWN) return own();
+    if (choice === DONE)
+      return { ...base, selected: [...picked].sort((a, b) => a - b).map((at) => question.options[at].label) };
+    const at = shown.indexOf(choice);
+    if (picked.has(at)) picked.delete(at);
+    else picked.add(at);
+  }
+}
+/**
+ * A yes-or-no question in the same dialog as ask_user, for Freeflow's own confirmations (task memory's proposals).
+ * Outside the terminal it is Pi's confirm, unchanged; without a UI it is false.
+ */
+export async function confirmWithUser(ctx, title, message, options = {}) {
+  if (!ctx?.hasUI || !ctx.ui) return false;
+  if (ctx.mode !== "tui" || typeof ctx.ui.custom !== "function")
+    return Boolean(
+      await ctx.ui.confirm(
+        title,
+        message,
+        ...(options.timeoutMs !== undefined ? [{ timeout: options.timeoutMs }] : []),
+      ),
+    );
+  const header = title.replace(/\?$/, "").slice(0, 40);
+  const yes = options.yes ?? "Yes";
+  const outcome = await askUser(
+    ctx,
+    [{ question: message, header, options: [{ label: yes }, { label: options.no ?? "No" }] }],
+    undefined,
+    {
+      ownAnswer: false,
+      notes: false,
+      ...(options.timeoutMs !== undefined ? { deadline: Date.now() + options.timeoutMs } : {}),
+    },
+  );
+  return outcome.status === "answered" && outcome.answers[0]?.selected[0] === yes;
+}