@hassangameryt/freeflow 0.7.3 → 0.8.0

package/pi-extension/dist/tool-execution/edit-messages.js

@@ -0,0 +1,120 @@
+// Messages Freeflow gives around Pi's edit and write. Every error ends in one literal next action; results carry no
+// reassurance. The wording was reviewed against the Beyond the Weights findings (Task 006 evidence).
+const MAX_SHOWN_LINES = 20;
+const MAX_LINE_CHARS = 300;
+const MIN_SIMILARITY = 0.5;
+/** Pi's edit fuzzy normalization (core/tools/edit-diff.ts normalizeForFuzzyMatch, not exported). */
+export function normalizeForMatch(text) {
+  return text
+    .normalize("NFKC")
+    .split("\n")
+    .map((line) => line.trimEnd())
+    .join("\n")
+    .replace(/[‘’‚‛]/g, "'")
+    .replace(/[“”„‟]/g, '"')
+    .replace(/[‐‑‒–—―−]/g, "-")
+    .replace(/[  -   　]/g, " ");
+}
+/** File text as Pi's edit matches it: without a BOM and with LF line endings. */
+export function editableText(raw) {
+  return raw.replace(/^/, "").replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+}
+function bigrams(text) {
+  const counts = new Map();
+  for (let i = 0; i < text.length - 1; i++) {
+    const pair = text.slice(i, i + 2);
+    counts.set(pair, (counts.get(pair) ?? 0) + 1);
+  }
+  return counts;
+}
+function lineSimilarity(a, b) {
+  const x = a.trim(),
+    y = b.trim();
+  if (x === y) return 1;
+  if (x.length < 2 || y.length < 2) return 0;
+  const left = bigrams(x),
+    right = bigrams(y);
+  let shared = 0;
+  for (const [pair, count] of left) shared += Math.min(count, right.get(pair) ?? 0);
+  return (2 * shared) / (x.length - 1 + (y.length - 1));
+}
+/** The window of the file most similar to the old text, as 1-based inclusive lines, or undefined when none is close. */
+export function closestMatch(fileText, oldText) {
+  const lines = fileText.split("\n");
+  const wanted = oldText.replace(/\n+$/, "").split("\n");
+  const size = Math.min(wanted.length, lines.length);
+  if (size === 0) return undefined;
+  let best;
+  for (let start = 0; start + size <= lines.length; start++) {
+    let total = 0;
+    for (let i = 0; i < size; i++) total += lineSimilarity(lines[start + i], wanted[i]);
+    const score = total / wanted.length;
+    if (!best || score > best.score) best = { start, score };
+  }
+  return best && best.score >= MIN_SIMILARITY ? { start: best.start + 1, end: best.start + size } : undefined;
+}
+/** 1-based start lines of every place the old text matches, compared as Pi's edit compares it. */
+export function matchingLines(fileText, oldText) {
+  const haystack = normalizeForMatch(fileText),
+    needle = normalizeForMatch(oldText);
+  const found = [];
+  if (!needle) return found;
+  for (let index = haystack.indexOf(needle); index >= 0; index = haystack.indexOf(needle, index + 1))
+    found.push(haystack.slice(0, index).split("\n").length);
+  return found;
+}
+function shownLines(fileText, start, end) {
+  return fileText
+    .split("\n")
+    .slice(start - 1, Math.min(end, start - 1 + MAX_SHOWN_LINES))
+    .map((line) => (line.length > MAX_LINE_CHARS ? `${line.slice(0, MAX_LINE_CHARS)}…` : line))
+    .join("\n");
+}
+const NOT_FOUND = /^Could not find (?:the exact text|edits\[(\d+)\]) in (.+?)\. The old ?[tT]ext must match exactly/;
+const NOT_UNIQUE = /^Found (\d+) occurrences of (?:the text|edits\[(\d+)\]) in (.+?)\. /;
+/**
+ * Replace Pi's not-found or not-unique edit error with one literal next action. Returns undefined when the error is
+ * another kind (overlap, empty, no change) or Pi worded it differently, so the result stays exactly as Pi wrote it.
+ */
+export function rewriteEditError(error, path, edits, fileText) {
+  const notFound = NOT_FOUND.exec(error);
+  if (notFound) {
+    const index = notFound[1] === undefined ? 0 : Number(notFound[1]);
+    const subject = notFound[1] === undefined ? path : `${path} edits[${index}]`;
+    const oldText = editableText(String(edits[index]?.oldText ?? ""));
+    const match = closestMatch(fileText, oldText);
+    if (!match)
+      return `${subject}: old text not found and no similar lines exist in the current file. Read the region you meant, then retry.`;
+    return [
+      `${subject}: old text not found. Closest match, lines ${match.start}–${match.end} (current file contents):`,
+      shownLines(fileText, match.start, match.end),
+      "If these are the lines you meant, retry with old text copied exactly from them. If not, read the region you meant, then retry.",
+    ].join("\n");
+  }
+  const notUnique = NOT_UNIQUE.exec(error);
+  if (notUnique) {
+    const index = notUnique[2] === undefined ? 0 : Number(notUnique[2]);
+    const subject = notUnique[2] === undefined ? path : `${path} edits[${index}]`;
+    const lines = matchingLines(fileText, editableText(String(edits[index]?.oldText ?? "")));
+    const places = lines.length > 0 ? lines.length : Number(notUnique[1]);
+    const where = lines.length > 0 ? ` (lines ${lines.join(", ")})` : "";
+    return `${subject}: old text matches ${places} places${where}. To change one place, add surrounding lines until it matches only that place. To change every place, give one edits[] entry per place, each with enough surrounding lines to match only that place.`;
+  }
+  return undefined;
+}
+export const writeRefusal = (path) =>
+  `${path} exists and has not been read in this session. Read ${path}, then retry the write.`;
+export const changedAfterEdit = (path) => `${path} changed since you read it; the edit applied to the current text.`;
+export const changedAfterWrite = (path) =>
+  `${path} changed since you read it; the write replaced the current contents.`;
+export const noNeedToReread = (path) => `No need to re-read ${path} to confirm this edit.`;
+/** Files the model read that changed or disappeared outside its own edits, as a fact and one next action. */
+export function changedFilesNotice(changed, deleted) {
+  const lines = [];
+  if (changed.length > 0)
+    lines.push(
+      `Files you read earlier changed since you read them: ${changed.join(", ")}. Read what you need from them again before editing them.`,
+    );
+  if (deleted.length > 0) lines.push(`Files you read earlier no longer exist: ${deleted.join(", ")}.`);
+  return lines.length > 0 ? lines.join("\n") : undefined;
+}

package/pi-extension/dist/tool-execution/file-state.js

@@ -0,0 +1,138 @@
+import { createHash } from "node:crypto";
+import { existsSync, realpathSync } from "node:fs";
+import { readFile, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { isAbsolute, resolve } from "node:path";
+// Files above this size are identified by size and modification time instead of a content hash.
+export const HASH_LIMIT_BYTES = 8 * 1024 * 1024;
+const UNICODE_SPACES = /[  -   　]/g;
+/** Resolve a tool path the way Pi's tools do: strip `@`, normalize odd spaces, expand `~`, resolve against cwd. */
+export function resolveToolPath(path, cwd) {
+  let candidate = path.replace(UNICODE_SPACES, " ");
+  if (candidate.startsWith("@")) candidate = candidate.slice(1);
+  if (candidate === "~") candidate = homedir();
+  else if (candidate.startsWith("~/")) candidate = `${homedir()}${candidate.slice(1)}`;
+  const resolved = isAbsolute(candidate) ? resolve(candidate) : resolve(cwd, candidate);
+  if (existsSync(resolved)) return resolved;
+  // Pi's read also finds macOS names typed differently: narrow space before AM/PM, NFD, curly apostrophe.
+  for (const variant of [
+    resolved.replace(/ (AM|PM)\./gi, " $1."),
+    resolved.normalize("NFD"),
+    resolved.replace(/'/g, "’"),
+  ])
+    if (variant !== resolved && existsSync(variant)) return variant;
+  return resolved;
+}
+function fileKey(path, cwd) {
+  const resolved = resolveToolPath(path, cwd);
+  try {
+    return realpathSync(resolved);
+  } catch {
+    return resolved;
+  }
+}
+async function fingerprint(file) {
+  let info;
+  try {
+    info = await stat(file);
+  } catch {
+    return "absent";
+  }
+  if (!info.isFile()) return "absent";
+  if (info.size > HASH_LIMIT_BYTES) return { size: info.size, mtimeMs: info.mtimeMs };
+  const bytes = await readFile(file);
+  return { sha256: createHash("sha256").update(bytes).digest("hex"), size: bytes.length };
+}
+async function statOf(file) {
+  try {
+    const info = await stat(file);
+    return info.isFile() ? { size: info.size, mtimeMs: info.mtimeMs } : "absent";
+  } catch {
+    return "absent";
+  }
+}
+const sameStat = (a, b) =>
+  a !== undefined && (a === "absent" || b === "absent" ? a === b : a.size === b.size && a.mtimeMs === b.mtimeMs);
+function sameFingerprint(a, b) {
+  if (a === "absent" || b === "absent") return a === b;
+  if ("sha256" in a && "sha256" in b) return a.sha256 === b.sha256;
+  if ("mtimeMs" in a && "mtimeMs" in b) return a.size === b.size && a.mtimeMs === b.mtimeMs;
+  return false;
+}
+/** The files a successful tool call read or changed, from a tool call's name and arguments. */
+export function touchedPaths(toolName, input) {
+  if (["read", "edit", "write"].includes(toolName)) return typeof input?.path === "string" ? [input.path] : [];
+  if (toolName === "apply_patch" && typeof input?.input === "string")
+    return [...input.input.matchAll(/^\s*\*\*\* (?:Add File|Update File|Delete File|Move to): (.+?)\s*$/gm)].map(
+      (match) => match[1],
+    );
+  return [];
+}
+/**
+ * Which files the model has read or written on the current branch, and their content at that moment. Held in memory
+ * and rebuilt from the branch after navigation or resume; never persisted and never consulted on the request path.
+ */
+export class FileState {
+  files = new Map();
+  async observe(path, cwd, via) {
+    const key = fileKey(path, cwd);
+    const at = await statOf(key);
+    this.files.set(key, { fingerprint: await fingerprint(key), via, stat: at });
+  }
+  wasRead(path, cwd) {
+    return this.files.has(fileKey(path, cwd));
+  }
+  /** Whether the file differs from its last observation; false when it was never observed. */
+  async changedSinceObserved(path, cwd) {
+    const key = fileKey(path, cwd);
+    const known = this.files.get(key);
+    if (!known) return false;
+    return !sameFingerprint(known.fingerprint, await fingerprint(key));
+  }
+  /**
+   * Observed files whose content changed since the model last read or wrote them, each reported once per change.
+   * Costs one stat per observed file; a file is hashed only when its size or modification time moved.
+   */
+  async changedSinceNoticed() {
+    const changed = [];
+    for (const [key, known] of this.files) {
+      const at = await statOf(key);
+      if (sameStat(known.stat, at)) continue;
+      known.stat = at;
+      const now = await fingerprint(key);
+      if (sameFingerprint(known.fingerprint, now)) continue;
+      if (known.noticed !== undefined && sameFingerprint(known.noticed, now)) continue;
+      known.noticed = now;
+      changed.push({ path: key, deleted: now === "absent" });
+    }
+    return changed;
+  }
+  /**
+   * Mark every file a successful read, edit, write or patch on the branch touched, with today's content. A Freeflow
+   * compaction starts over: the model then holds only the files it carried.
+   */
+  async rebuild(branch, cwd) {
+    this.files.clear();
+    const calls = new Map();
+    const touched = new Set();
+    for (const entry of branch) {
+      if (entry?.type === "compaction" && entry.details?.freeflow) {
+        touched.clear();
+        for (const item of entry.details.freeflow.carried ?? [])
+          if (item?.kind === "file" && typeof item.path === "string" && !item.error) touched.add(item.path);
+      }
+      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" && message.isError !== true) {
+        const call = calls.get(message.toolCallId);
+        if (call) for (const path of touchedPaths(call.name, call.input)) touched.add(path);
+      }
+    }
+    for (const path of touched) await this.observe(path, cwd, "rebuilt");
+  }
+  reset() {
+    this.files.clear();
+  }
+}

package/pi-extension/dist/tool-execution/file-tracking.js

@@ -0,0 +1,143 @@
+import { realpathSync, statSync } from "node:fs";
+import { isAbsolute, relative } from "node:path";
+import { readFile } from "node:fs/promises";
+import { FileState, resolveToolPath } from "./file-state.js";
+import {
+  changedAfterEdit,
+  changedAfterWrite,
+  changedFilesNotice,
+  editableText,
+  noNeedToReread,
+  rewriteEditError,
+  writeRefusal,
+} from "./edit-messages.js";
+import { cachedBranch } from "../host/branch.js";
+function existingFile(path, cwd) {
+  try {
+    return statSync(resolveToolPath(path, cwd)).isFile();
+  } catch {
+    return false;
+  }
+}
+// Tools whose own targets are observed after they run; any other tool may change files behind the model's back.
+const TRACKED_TOOLS = ["read", "edit", "write", "apply_patch"];
+/** A tracked file (keyed by real path) as the model would name it: relative to the working directory when inside. */
+function shown(path, cwd) {
+  let real = cwd;
+  try {
+    real = realpathSync(cwd);
+  } catch {}
+  for (const base of [real, cwd]) {
+    const inside = relative(base, path);
+    if (inside && !inside.startsWith("..") && !isAbsolute(inside)) return inside;
+  }
+  return path;
+}
+function withLines(content, lines) {
+  const text = content.map((part) => (part?.type === "text" ? part.text : "")).join("");
+  return [
+    { type: "text", text: [text, ...lines].filter(Boolean).join("\n") },
+    ...content.filter((part) => part?.type !== "text"),
+  ];
+}
+/**
+ * Claude Code's file awareness around Pi's read, edit and write: refuse a whole-file write over a file never read,
+ * say when an edited file changed since it was read, and turn edit errors into one next action. Nested calls
+ * (codemode) are handled like direct ones.
+ */
+export class FileTracking {
+  state = new FileState();
+  changed = new Map();
+  built = false;
+  reset() {
+    this.state.reset();
+    this.changed.clear();
+    this.built = false;
+  }
+  /** Forget the branch's files; they are rebuilt from the new branch before the next tool call. */
+  invalidate() {
+    this.built = false;
+  }
+  clearPending() {
+    this.changed.clear();
+  }
+  /** After a Freeflow compaction the model holds only the carried files, read at compaction time. */
+  async compacted(carried, ctx) {
+    this.state.reset();
+    this.changed.clear();
+    for (const path of carried) await this.state.observe(path, ctx.cwd, "read");
+    this.built = true;
+  }
+  /** The branch's file state for apply_patch, built when needed. */
+  async forPatch(ctx) {
+    await this.ensureBuilt(ctx);
+    return this.state;
+  }
+  /** Record files a successful apply_patch wrote or moved, as a successful write records them. */
+  async written(paths, ctx) {
+    await this.ensureBuilt(ctx);
+    for (const path of paths) await this.state.observe(path, ctx.cwd, "apply_patch");
+  }
+  async ensureBuilt(ctx) {
+    if (this.built) return;
+    await this.state.rebuild(cachedBranch(ctx.sessionManager) ?? [], ctx.cwd);
+    this.built = true;
+  }
+  async toolCall(event, ctx) {
+    const name = event.toolName;
+    const path = event.input?.path;
+    if (!["edit", "write"].includes(name) || typeof path !== "string") return undefined;
+    await this.ensureBuilt(ctx);
+    if (name === "write" && existingFile(path, ctx.cwd) && !this.state.wasRead(path, ctx.cwd))
+      return { block: true, reason: writeRefusal(path) };
+    if (await this.state.changedSinceObserved(path, ctx.cwd)) this.changed.set(event.toolCallId, path);
+    return undefined;
+  }
+  /** Files the model read that changed since, not yet reported; undefined when there are none. */
+  async changedNotice(ctx, build = true) {
+    // Before a prompt nothing is rebuilt: a branch not yet rebuilt has no baseline to compare against.
+    if (!build && !this.built) return undefined;
+    await this.ensureBuilt(ctx);
+    const found = await this.state.changedSinceNoticed();
+    return changedFilesNotice(
+      found.filter((file) => !file.deleted).map((file) => shown(file.path, ctx.cwd)),
+      found.filter((file) => file.deleted).map((file) => shown(file.path, ctx.cwd)),
+    );
+  }
+  async toolResult(event, ctx) {
+    const name = event.toolName;
+    // A command (or any other tool) may have changed files the model read. Nested calls are reported on the
+    // result of the script that made them, which is what the model sees.
+    if (!TRACKED_TOOLS.includes(name)) {
+      if (event.parentToolCallId) return undefined;
+      const notice = await this.changedNotice(ctx);
+      return notice === undefined ? undefined : { content: withLines(event.content ?? [], [notice]) };
+    }
+    const path = event.input?.path;
+    if (!["read", "edit", "write"].includes(name) || typeof path !== "string") return undefined;
+    await this.ensureBuilt(ctx);
+    const changed = this.changed.get(event.toolCallId);
+    this.changed.delete(event.toolCallId);
+    if (event.isError) {
+      if (name !== "edit") return undefined;
+      let fileText;
+      try {
+        fileText = editableText(await readFile(resolveToolPath(path, ctx.cwd), "utf8"));
+      } catch {
+        return undefined;
+      }
+      const error = (event.content ?? []).map((part) => (part?.type === "text" ? part.text : "")).join("");
+      const rewritten = rewriteEditError(error, path, event.input?.edits ?? [], fileText);
+      return rewritten === undefined ? undefined : { content: [{ type: "text", text: rewritten }] };
+    }
+    await this.state.observe(path, ctx.cwd, name);
+    if (name === "read") return undefined;
+    const lines =
+      name === "edit"
+        ? [...(changed ? [changedAfterEdit(path)] : []), noNeedToReread(path)]
+        : changed
+          ? [changedAfterWrite(path)]
+          : [];
+    return lines.length > 0 ? { content: withLines(event.content ?? [], lines) } : undefined;
+  }
+}

package/pi-extension/dist/tool-execution/prompt.js

@@ -0,0 +1,54 @@
+import { homedir, platform, release } from "node:os";
+import { getShellConfig } from "@earendil-works/pi-coding-agent";
+// Pi's generic rule lines that contradict the taught bash-first working style or repeat Freeflow's interaction
+// contract. Every other rule, including each tool's and extension's guidelines, stays as Pi renders it.
+const REMOVED_RULES = new Set([
+  "- Use read to examine files instead of cat or sed.",
+  "- Be concise in your responses",
+  "- Show file paths clearly when working with files",
+]);
+function renderedSection(systemPrompt, name) {
+  const match = new RegExp(`<${name}>\\n([\\s\\S]*?)\\n</${name}>`).exec(systemPrompt);
+  return match?.[1];
+}
+function rules(systemPrompt) {
+  const rendered = renderedSection(systemPrompt, "rules");
+  if (rendered === undefined) return undefined;
+  const lines = rendered.split("\n");
+  const kept = lines.filter((line) => !REMOVED_RULES.has(line));
+  return kept.length === lines.length || kept.length === 0 ? undefined : kept.join("\n");
+}
+function docs(systemPrompt) {
+  const rendered = renderedSection(systemPrompt, "docs");
+  if (rendered === undefined) return undefined;
+  const path = (label) => new RegExp(`^- ${label}: (.+?)(?: \\(|$)`, "m").exec(rendered)?.[1];
+  const [readme, docsPath, examples] = [path("Main documentation"), path("Additional docs"), path("Examples")];
+  if (!readme || !docsPath || !examples) return undefined;
+  return `Pi documentation (read only when the user asks about pi itself): ${readme}, ${docsPath}, ${examples}.`;
+}
+function environment(shellPath) {
+  let shell;
+  try {
+    shell = getShellConfig(shellPath?.startsWith("~/") ? `${homedir()}${shellPath.slice(1)}` : shellPath).shell;
+  } catch {
+    shell = "unavailable";
+  }
+  return `Platform: ${platform()} ${release()}. Shell for bash: ${shell}.`;
+}
+/**
+ * Pi prompt sections Freeflow owns while Tool Execution is effective. Every value derives from inputs fixed for the
+ * configuration and machine, so the system prompt stays identical across requests and sessions. Pi's preamble is
+ * never touched: the Claude subscription plugin shapes it only when Pi's own preamble is present.
+ */
+export function toolExecutionSections(systemPrompt, shellPath) {
+  const sections = {};
+  const ownRules = rules(systemPrompt);
+  if (ownRules !== undefined) sections.rules = ownRules;
+  const ownDocs = docs(systemPrompt);
+  if (ownDocs !== undefined) sections.docs = ownDocs;
+  return sections;
+}
+/** Sections Tool Execution adds after Freeflow's guidance: the environment facts, then its guidance when available. */
+export function toolExecutionTail(shellPath, guidance) {
+  return { environment: environment(shellPath), ...(guidance ? { tool_execution: guidance } : {}) };
+}

package/pi-extension/dist/tool-execution/tools.js

@@ -0,0 +1,16 @@
+import { APPLY_PATCH } from "./apply-patch/tool.js";
+import { BASH_BACKGROUND, STOP_BACKGROUND } from "./background.js";
+/** Freeflow's own Tool Execution tools; registered once and declared exactly while Tool Execution is effective. */
+export const TOOL_EXECUTION_TOOLS = [APPLY_PATCH, BASH_BACKGROUND, STOP_BACKGROUND];
+/**
+ * Declare or withdraw Freeflow's tools when Tool Execution's effective state changes. Missing tools are appended and
+ * existing ones keep their place, so repeated calls leave the tool list unchanged within a configuration.
+ */
+export function applyToolExecutionTools(pi, effective) {
+  if (typeof pi.getActiveTools !== "function" || typeof pi.setActiveTools !== "function") return;
+  const current = pi.getActiveTools();
+  const next = effective
+    ? [...current, ...TOOL_EXECUTION_TOOLS.filter((name) => !current.includes(name))]
+    : current.filter((name) => !TOOL_EXECUTION_TOOLS.includes(name));
+  if (next.length !== current.length) pi.setActiveTools(next);
+}

package/pi-extension/freeflow/README.md

@@ -0,0 +1,9 @@
+# Extension entry point
+
+`index.js` is the file Pi loads: the root `package.json` lists it under `pi.extensions`. It only re-exports the compiled extension:
+
+```js
+export { default } from "../dist/index.js";
+```
+
+Keeping this stable path separate from `dist/` lets the build delete and recreate `dist/` without changing what the package manifest points to. Do not add logic here; the extension starts in [`src/index.ts`](../src/index.ts).

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "freeflow",
-  "version": "0.7.3",
+  "version": "0.8.0",
   "description": "Feedback-based control system for coding agents.",
   "author": {
     "name": "Hassan Mohiddin"

package/runtime/prompts/cognitive-routing.md

@@ -1,9 +1,9 @@
 ## Cognitive Routing Cue
 
-Cognitive Routing places work across configured profiles in one agent/session to improve quality, continuity, responsiveness, and total cost together. Coordinator owns user interaction, governing direction, delegation, and acceptance. When enabled, Helper is the normal delegate for supporting work; Executor is commissioned for substantive or consequential results, including implementation and artifacts. Helper and Executor share ordinary active history; only Coordinator delegates and only one profile executes at a time.
+Cognitive Routing places work across configured profiles in one agent/session to improve quality and total cost together. Coordinator owns user interaction, planning, governing decisions, delegation, assessment, and acceptance. Helper and Executor are workers: only Coordinator delegates, only one profile executes at a time, and the workers share ordinary active history.
 
-Use the latest Runtime State for control, profile, delegation mode, and current responsibility. In Automatic control, follow the selected mode: helper-only permits Coordinator substantive production with Helper support; executor-only delegates environment work to Executor; both uses Helper by default for support and Executor for substantive work. A mode change does not retarget an accepted assignment or its recovery. Under Manual control, the held Coordinator, Helper, or Executor follows ordinary unsplit Workflow without Automatic role restrictions. Do not release the user's hold. When routing is inactive, stop applying this split.
+Use the latest Runtime State for control, profile, delegation mode, and current responsibility. In Automatic control, the delegation mode sets who implements: `helper` has Coordinator implement while Helper takes everything that does not need Coordinator-level reasoning; `executor` has Executor do the environment work from Coordinator's contracts; `both` has Executor do consequential work, including code, and Helper do support. A mode change does not retarget an accepted assignment or its recovery. Completed or superseded contracts and reports are historical context and grant no new permission; follow the current assignment and the user's current restrictions. Under Manual control, the held Coordinator, Helper, or Executor follows ordinary unsplit Workflow without Automatic role restrictions. Do not release the user's hold. When routing is inactive, stop applying this split.
 
-Before relying on Automatic routing, read the complete cognitive-routing skill if its body is absent. This bootstrap read is the only environment call in that response. If unavailable, stop and report the missing method. Reload it after context loss before applying remembered routing rules.
+Before relying on Automatic routing, read the complete cognitive-routing skill if its body is absent. This bootstrap read is the only environment call in that response. If unavailable, stop and report the missing method. The skill then directs you to its reference for the current delegation mode. Reload it after context loss before applying remembered routing rules.
 
-When projection is on, the active worker must project every completed skill and instructional-reference read, including this bootstrap read. Follow the skill for work placement, environment access, evidence, handoffs, and recorded-worker recovery. Under Automatic routing, a worker return or passing check is not Coordinator acceptance; completed Slice closure requires Coordinator's supported judgment and explicit closure instruction. Manual control follows ordinary Workflow and Track Work instead.
+When projection is on, the active worker must project every completed skill and instructional-reference read, including this bootstrap read. Follow the skill for work placement, environment access, evidence, handoffs, and recorded-worker recovery. Under Automatic routing, a worker return or passing check is not Coordinator acceptance; completed Slice closure requires Coordinator's assessment and explicit closure direction. Manual control follows ordinary Workflow and Track Work instead.

package/runtime/prompts/core.md

@@ -1,90 +1,37 @@
 # Freeflow Stable Guidance
 
-Freeflow is a workflow layer for one active coding agent. It does not override user instructions, repository policy, host safety, or tool permissions, and it creates no authority. Core guidance and the separately editable Interaction Contract are delivered together whenever Freeflow is enabled.
+Freeflow is a workflow layer for one coding agent. It never overrides user instructions, repository instructions, host safety, or tool permissions, and it grants no authority of its own.
 
-Use the latest Freeflow Runtime State and only the guidance, skills, and tools exposed for this request. State refreshes at session start, after context loss, or when displayed facts change; an unchanged snapshot may remain visible. Earlier snapshots are history.
+Use the latest Freeflow Runtime State and only the guidance, skills, and tools exposed for this request. The state refreshes at session start, after context loss, and when its facts change; earlier snapshots are history.
 
-## Shared Terms
+## Terms
 
-- **Authority envelope:** the requested outcome, permitted effects, covered active evidence generation, and stop condition established by a direct request or still-valid approval.
-- **Work agreement:** the user-established outcome, scope, and user-facing return condition. It may include figuring out the approach; it is not a mandatory artifact or another authority source.
-- **Passive observation:** inspecting existing sources or evidence without exercising target behavior or intentionally changing task state.
-- **Active evidence generation:** exercising behavior to produce evidence, including tests, reproductions, benchmarks, prototypes, instrumentation, and runtime probes.
-- **Mutation or delivery:** changing repository, durable task/session, or external state.
-- **Bounded activity:** coherent discussion, preservation, execution, evidence, or judgment ending in one assessable result.
-- **Current owner:** the one activity responsible for that result. Supporting methods, lenses, tools, references, and reviewers do not automatically take ownership.
-- **Slice:** one coherent outcome that may span several bounded activities. Track Work gives it durable identity when task memory is needed.
-- **Evidence boundary:** the strongest claim directly supported by the observing mechanism—not by intent, authority, or confidence.
-- **Self-review:** the producer silently checks an initially supported result for alignment, correctness, suitability, and unnecessary complexity before accepting or reusing it. Corrected work receives only the affected recheck.
-- **Independent review:** separately selected judgment from a context that did not produce the reviewed state. It reports without editing or authorizing correction.
-- **Checkpoint:** a deliberately selected boundary that dependent work must not cross unresolved. An activity ending or pausing does not create one automatically.
-- **Re-entry:** return only to the owner whose responsibility changed, preserving unaffected work, decisions, and evidence.
-- **Supported Exit:** an answer, wait, pause, handoff, deferment, controlled boundary, stop, or completion justified by current evidence and authority.
+- **Work agreement:** the outcome, scope, and return point the user agreed to. Only the user's request or still-valid approval establishes it.
+- **Active evidence generation:** exercising behavior to produce evidence, such as tests, reproductions, experiments, or probes. Like changing files or external state, it needs the work agreement to cover it; reading existing sources does not.
+- **Current owner:** the one skill responsible for the current question or result.
+- **Working Record:** the task's durable memory file, maintained through Track Work.
+- **Slice:** one coherent unit of work in a Working Record.
+- **Checkpoint:** a boundary on the task's route, such as a commit, publication, review, user decision, or planned handoff. Once selected, dependent work must not cross it unresolved.
+- **Evidence boundary:** the strongest claim an observation directly supports.
+- **Self-review:** the producer's own check of a supported result before accepting it. **Independent review:** a separately selected judgment from a context that did not produce the work.
 
 ## Load The Selected Method
 
-Before applying a selected skill, read its current body when its exact method is absent from context. Descriptions select methods; they do not replace them. Reuse still-visible guidance instead of rereading each turn.
-
-Read dependencies at their declared conditions, not the whole catalogue. Loading guidance neither changes ownership nor authorizes effects. Required reads still follow active capability bootstrap and routing rules.
+Before applying a selected skill, read its current body when it is not already in context; a description selects a skill but is not its method. Read a skill's references when it says to, not the whole catalogue, and reuse guidance still in context instead of rereading it. Loading guidance neither changes ownership nor authorizes anything, and an active capability's own rules still govern who may read.
 
 ## Recover After Context Loss
 
-After compaction, context-replacing summarization, clear, session resume/navigation, transfer into another context, or uncertain continuity, pause task work. Use only necessary recovery reads until state is coherent; recovery is not a bypass of authority, capabilities, or host permissions.
-
-- Require the latest Freeflow Runtime State; do not infer missing or contradictory state.
-- Reload relevant active capability methods before relying on them.
-- When a Working Record exists or may exist, load Track Work and read the complete `full` record. A summary or `resume` projection is not full recovery. Stop affected work if recovery is incomplete or unavailable.
-- Identify the current owner and reload its method if absent. Use Workflow when authority, ownership, or continuation is unclear.
-- Reconcile the agreement, current work, dependencies, evidence limits, partial effects, and stop conditions with current user direction and relevant live sources.
-
-Summaries and records may preserve evidence of prior approval; check that the approval still applies. They do not create authority, prove live state, or keep an absent method active. Current user direction, live source truth, and current Runtime State take precedence over conflicting memory. With intact context, use bounded record reads only when needed; another turn or ordinary pause is not context loss.
-
-## Three Nested Loops
-
-The **Interaction Lifecycle** runs from Entry through the Feedback Loop when needed to a Supported Exit. A later user turn or new evidence begins another lifecycle. One lifecycle may contain several bounded activities.
-
-For each bounded activity, the **Feedback Loop** is:
-
-```text
-Orient or reconstruct state
--> choose or retain the current owner
--> establish the required result and a supported approach
--> apply its method and gather or produce evidence
--> determine what the evidence supports
--> self-review the supported result
--> continue, correct, re-enter, ask, defer, stop, or exit
-```
-
-Reuse settled understanding. For concrete work, resolve what is required and how to produce the next result before production changes; these need not be separate investigations or user turns. A learning action answers its bounded question, not an expanding production ambition.
-
-When the owner needs the environment, the **Environment Interaction Loop** is:
-
-```text
-Need evidence or a covered effect
--> reuse adequate context or identify what is missing
--> select and bound the action and tool
--> execute once
--> observe what changed
--> apply active capability guidance where relevant
--> return to the current owner
-```
-
-This inner loop may run zero or more times per activity. It does not change authority or ownership.
-
-## Evidence And Judgment
-
-Verification establishes what direct evidence proves at the observed boundary. Review judges whether work or an artifact is aligned, correct, suitable, and sufficiently evidenced; judgment does not replace verification. A passing check may leave a broader claim unsupported. Preserve missing, contradictory, and inconclusive evidence rather than converting it into success.
-
-## Workflow Cue
-
-Use Workflow when authority, readiness, ownership, re-entry, checkpoints, continuity, or Supported Exit needs coordination. Continue covered work to the agreed return boundary; internal method returns do not end the user agreement.
-
-Before an uncovered effect or separately controlled action, explain its purpose, action, expected result, and stop condition; ask once and wait. Skills, artifacts, reviews, memory, and useful new evidence do not grant authority.
+After compaction, a summary that replaces earlier context, clear, session resume or navigation, transfer into another context, or uncertain continuity, pause task work and recover first. Use only the reads recovery needs; recovery is not a bypass of authority, capabilities, or host permissions.
 
-## Action Selection Cue
+- Use the latest Freeflow Runtime State; do not infer missing or contradictory state.
+- Reload the methods the current work needs.
+- When a Working Record exists or may exist for the current work, load Track Work, confirm the record belongs to that work, and read the complete `full` record, then the artifacts listed under its `What defines this task` and its `Recovery sources`. A summary or `resume` view is not full recovery. If recovery is incomplete, report that and stop affected work.
+- Reconcile the record with current user direction, live state, and the current Runtime State, which override it where they conflict. A summary or record may preserve evidence of prior approval; check that the approval still applies. Neither creates authority.
 
-Use Action Selection before an uncertain, broad, or repeated environment interaction. Seek the smallest sufficient observation or effect for the current question, bound its output, and return what changed to the owner. Use the fast path for an obvious covered mechanical action; do not manufacture alternatives or collect context after the question is settled.
+Then continue the covered work toward the agreed end. Context loss is not a reason to stop or to ask for permission again; stop only at the agreed end, a real blocker, or a decision the user owns. With intact context, another turn or an ordinary pause is not context loss.
 
-## Supported Exit
+## Cues
 
-Exit only when evidence and authority support it, applicable self-review and selected checkpoints are resolved, and required task memory and artifacts are accurate. Make material gaps, contradictions, deferrals, and user-owned decisions explicit. Report the outcome, evidence, limits, and current route.
+- Use Workflow when the work agreement, the current owner, readiness to act, a changed route, continuity, or the end of the work needs coordinating.
+- Use Action Selection before an uncertain, broad, or repeated environment interaction. Take the direct action when it is obvious.
+- Use Decision Gate when proceeding would make a choice the user owns.