@hassangameryt/freeflow 0.8.0 → 0.9.0

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

@@ -11,6 +11,7 @@ import {
   rewriteEditError,
   writeRefusal,
 } from "./edit-messages.js";
+import { SkillReads } from "./skill-reads.js";
 import { cachedBranch } from "../host/branch.js";
 function existingFile(path, cwd) {
   try {
@@ -33,7 +34,8 @@ function shown(path, cwd) {
   }
   return path;
 }
-function withLines(content, lines) {
+/** A tool result's content with lines appended to its text (before delivery: nothing already sent changes). */
+export 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") },
@@ -42,21 +44,29 @@ function withLines(content, lines) {
 }
 /**
  * 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.
+ * say when an edited file changed since it was read, turn edit errors into one next action, and answer a repeat
+ * read of a Freeflow instruction file the model already holds with one line. Nested calls (codemode) are handled like
+ * direct ones, except that a nested read is never answered for the model: the script consumes its text.
  */
 export class FileTracking {
   state = new FileState();
   changed = new Map();
+  skillReads = new SkillReads();
   built = false;
   reset() {
     this.state.reset();
     this.changed.clear();
+    this.skillReads.reset();
     this.built = false;
   }
   /** Forget the branch's files; they are rebuilt from the new branch before the next tool call. */
   invalidate() {
     this.built = false;
+    this.skillReads.invalidate();
+  }
+  /** After Pi's own compaction the files are unchanged, but the instruction files read before it are out of view. */
+  piCompacted() {
+    this.skillReads.clear();
   }
   clearPending() {
     this.changed.clear();
@@ -67,6 +77,12 @@ export class FileTracking {
     this.changed.clear();
     for (const path of carried) await this.state.observe(path, ctx.cwd, "read");
     this.built = true;
+    this.skillReads.clear();
+  }
+  /** Freeflow skills the model holds in this context, by name; reads are rebuilt from the branch when needed. */
+  loadedSkills(ctx) {
+    if (!this.skillReads.built) this.skillReads.rebuild(cachedBranch(ctx.sessionManager) ?? [], ctx.cwd);
+    return this.skillReads.skills();
   }
   /** The branch's file state for apply_patch, built when needed. */
   async forPatch(ctx) {
@@ -79,6 +95,7 @@ export class FileTracking {
     for (const path of paths) await this.state.observe(path, ctx.cwd, "apply_patch");
   }
   async ensureBuilt(ctx) {
+    if (!this.skillReads.built) this.skillReads.rebuild(cachedBranch(ctx.sessionManager) ?? [], ctx.cwd);
     if (this.built) return;
     await this.state.rebuild(cachedBranch(ctx.sessionManager) ?? [], ctx.cwd);
     this.built = true;
@@ -131,7 +148,10 @@ export class FileTracking {
       return rewritten === undefined ? undefined : { content: [{ type: "text", text: rewritten }] };
     }
     await this.state.observe(path, ctx.cwd, name);
-    if (name === "read") return undefined;
+    if (name === "read") {
+      this.skillReads.observe(event, ctx.cwd);
+      return undefined;
+    }
     const lines =
       name === "edit"
         ? [...(changed ? [changedAfterEdit(path)] : []), noNeedToReread(path)]

package/pi-extension/dist/tool-execution/guidance-notices.js

@@ -0,0 +1,124 @@
+import { execFile } from "node:child_process";
+import { join } from "node:path";
+import { freeflowNotice } from "../host/inbound.js";
+import { isFreeflowInstruction } from "./skill-reads.js";
+/**
+ * Guidance pushed at the moment it is needed (the push retriever, Task 004 D-003): a short Freeflow notice appended to
+ * the result of the tool call that makes it relevant, so it reaches the agent whether or not it read the skill that
+ * owns it.
+ *
+ * - A `git commit` result: Deliver Work's commit essentials, plus Write Skill's loss check when the commit staged
+ *   model-facing instruction text (read from Git at that result). Once per run.
+ * - The second failure of the same test command: diagnose's two key lines. Once per command until it passes.
+ * - A test command that passes after the run changed a file: run Execute Work's self-review before the final report.
+ *   Once per run, and not after self-review ran.
+ * - Any tool result while Execute Work's body is not in the model's context (never read, or dropped by a compaction):
+ *   read it before more tool calls. Once per run, and not on a read of Freeflow's own instruction files, so reading
+ *   Discuss Work first is not interrupted.
+ *
+ * Cache: a notice is part of a tool result that has not been delivered yet, the same path as Tool Execution's
+ * changed-files line; nothing already sent changes. Request path: none of this runs per request. State is in memory,
+ * O(1) per tool result, bounded (at most FAILURE_KEYS test commands), and reset per run where it says so.
+ */
+const FAILURE_KEYS = 32;
+const TEST_COMMAND =
+  /(^|[\s;&|(])((npm|pnpm|yarn|bun)\b[^;&|]*\btest(:[\w:-]+)?\b|node\s+(\S+\s+)*--test\b|(pytest|jest|vitest|mocha|rspec|phpunit|ctest|tox)\b|go\s+test\b|cargo\s+(test|nextest)\b|(mvn|gradle|\.\/gradlew)\b[^;&|]*\btest\b|make\s+(test|check)\b|dotnet\s+test\b|bundle\s+exec\s+rspec\b|python3?\s+-m\s+(pytest|unittest)\b)/;
+const GIT_COMMIT = /(^|[\s;&|(])git(\s+(-C|-c)\s+\S+)*\s+commit\b(?![^;&|]*--help)/;
+const CHANGES_FILES = new Set(["edit", "write", "apply_patch"]);
+// Model-facing instruction text, as Write Skill's loss check reads it: skill packages, capabilities, runtime prompts
+// and instruction files.
+const INSTRUCTION_TEXT =
+  /(^|\/)(SKILL\.md|AGENTS\.md|CLAUDE\.md)$|^(skills|capabilities)\/.+\.md$|(^|\/)prompts\/[^/]+\.md$/;
+export const COMMIT_NOTICE =
+  "Committing (Deliver Work): check what the commit holds with `git show --stat --oneline HEAD` and `git status --short --branch`: only the paths this claim needs, staged explicitly, since staged does not mean yours. Never commit Working Records (`.freeflow/tasks/`), secrets or local environment files. No --amend, --no-verify, --allow-empty or push unless the user asked for exactly that; after a failed commit or hook, inspect what changed before retrying.";
+export const INSTRUCTION_TEXT_NOTICE =
+  "This commit stages model-facing instruction text: for a substantial revision (a merge, split, move or rewrite), run Write Skill's `skill-author compare --all-units` and settle every unmatched unit before it goes further.";
+export const DIAGNOSE_NOTICE =
+  "This test command failed twice (Execute Work's Diagnose Before Fixing; its diagnose reference has the full loop): two failed fixes mean the diagnosis is wrong. Before the next change, find an observation that would come out differently if your explanation were wrong: change the question, change the kind of observation, or check the cheapest assumption (did it build; does the test import what you think?).";
+export const executeWorkNotice = (skill) =>
+  `Read Execute Work (${skill}) before more tool calls: it holds how to read the request, find what a change touches and diagnose a failure.`;
+/** Text without the guidance notices joined to it: moment guidance, not evidence, so it is not carried on. */
+export const withoutGuidanceNotices = (text) =>
+  text.replace(/\n?<freeflow-notice type="guidance">\n[\s\S]*?\n<\/freeflow-notice>/g, "");
+export const selfReviewNotice = (script) =>
+  `Before your final report (Execute Work's step before reporting; read Execute Work if its body is not in your context): run \`node ${script} --base <ref>\` and read its report: changed tests and fixtures with their hunks, new tests and whether they fail on the base, and whether each requirement's check ran after the last edit.`;
+const textOf = (content) => (content ?? []).map((part) => (part?.type === "text" ? part.text : "")).join("");
+/**
+ * The paths a commit command dealt with, read once at its result: what the new commit holds when it succeeded, what is
+ * still staged when it failed. Null when Git cannot tell.
+ */
+function committedPaths(cwd, failed) {
+  const args = failed
+    ? ["diff", "--cached", "--name-only"]
+    : ["diff-tree", "--no-commit-id", "--name-only", "-r", "--root", "HEAD"];
+  return new Promise((resolve) =>
+    execFile("git", args, { cwd, timeout: 2000, maxBuffer: 4 * 1024 * 1024 }, (error, stdout) =>
+      resolve(error ? null : stdout.split("\n").filter(Boolean)),
+    ),
+  );
+}
+export class GuidanceNotices {
+  run = { committed: false, changed: false, reviewed: false, reminded: false, executeWork: false };
+  failures = new Map();
+  selfReview;
+  executeWork;
+  constructor(packageRoot) {
+    this.selfReview = join(packageRoot, "skills", "execute-work", "scripts", "self-review.mjs");
+    this.executeWork = join(packageRoot, "skills", "execute-work", "SKILL.md");
+  }
+  /** A new agent run: per-run notices may come again. */
+  runStarted() {
+    this.run = { committed: false, changed: false, reviewed: false, reminded: false, executeWork: false };
+  }
+  /**
+   * The notice lines to append to a tool result; empty when none applies. `executeWorkUnread` says whether Execute
+   * Work is a skill this session lists and its body is not in the model's context; omitted, the notice never shows.
+   */
+  async toolResult(event, cwd, executeWorkUnread) {
+    if (event?.parentToolCallId) return [];
+    const name = event?.toolName;
+    const lines = [];
+    if (
+      !this.run.executeWork &&
+      executeWorkUnread !== undefined &&
+      !isFreeflowInstruction(name, event.input, cwd) &&
+      executeWorkUnread()
+    ) {
+      this.run.executeWork = true;
+      lines.push(freeflowNotice("guidance", executeWorkNotice(this.executeWork)));
+    }
+    if (CHANGES_FILES.has(name)) {
+      if (!event.isError) this.run.changed = true;
+      return lines;
+    }
+    if (name !== "bash") return lines;
+    const command = String(event.input?.command ?? "").trim();
+    if (command.includes("self-review.mjs")) this.run.reviewed = true;
+    if (GIT_COMMIT.test(command) && !this.run.committed) {
+      this.run.committed = true;
+      const paths = await committedPaths(cwd, event.isError === true);
+      const body = [COMMIT_NOTICE];
+      if (paths?.some((path) => INSTRUCTION_TEXT.test(path))) body.push(INSTRUCTION_TEXT_NOTICE);
+      lines.push(freeflowNotice("guidance", body.join("\n")));
+    }
+    if (TEST_COMMAND.test(command)) {
+      const key = command.replace(/\s+/g, " ");
+      // Pi's bash reports a nonzero exit as an error result ("Command exited with code N").
+      const failed = event.isError === true || /Command exited with code [1-9]\d*\s*$/.test(textOf(event.content));
+      if (failed) {
+        const count = (this.failures.get(key) ?? 0) + 1;
+        this.failures.delete(key);
+        this.failures.set(key, count);
+        while (this.failures.size > FAILURE_KEYS) this.failures.delete(this.failures.keys().next().value);
+        if (count === 2) lines.push(freeflowNotice("guidance", DIAGNOSE_NOTICE));
+      } else {
+        this.failures.delete(key);
+        if (this.run.changed && !this.run.reviewed && !this.run.reminded) {
+          this.run.reminded = true;
+          lines.push(freeflowNotice("guidance", selfReviewNotice(this.selfReview)));
+        }
+      }
+    }
+    return lines;
+  }
+}

package/pi-extension/dist/tool-execution/skill-reads.js

@@ -0,0 +1,143 @@
+import { realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+/** The Freeflow package root, as this module was loaded and through its real path. */
+const ROOT = fileURLToPath(new URL("../../../", import.meta.url));
+const ROOTS = [...new Set([resolve(ROOT), realOr(ROOT)])];
+const INSTRUCTION_DIRS = ["capabilities", "skills", "runtime"];
+function realOr(path) {
+  try {
+    return realpathSync(path);
+  } catch {
+    return resolve(path);
+  }
+}
+/**
+ * A Freeflow instruction file (a skill, a reference, a runtime prompt) by its path inside the package, such as
+ * `skills/track-work/SKILL.md`; undefined for any other path. No file system access: a path is matched as written,
+ * against the package root and its real path.
+ */
+export function instructionPath(path, cwd = process.cwd()) {
+  let candidate = path.startsWith("@") ? path.slice(1) : path;
+  if (candidate === "~" || candidate.startsWith("~/")) candidate = `${homedir()}${candidate.slice(1)}`;
+  const absolute = isAbsolute(candidate) ? resolve(candidate) : resolve(cwd, candidate);
+  for (const root of ROOTS) {
+    const inside = relative(root, absolute);
+    if (!inside || inside.startsWith("..") || isAbsolute(inside)) continue;
+    if (INSTRUCTION_DIRS.some((dir) => inside.startsWith(dir + sep))) return inside.split(sep).join("/");
+  }
+  return undefined;
+}
+/** Whether a tool call reads one of Freeflow's own instruction files. */
+export function isFreeflowInstruction(tool, input, cwd) {
+  return tool === "read" && typeof input?.path === "string" && instructionPath(input.path, cwd) !== undefined;
+}
+/** The skill a path's `SKILL.md` belongs to, by its directory name; undefined for any other file. */
+export function skillName(path, cwd) {
+  const inside = instructionPath(path, cwd);
+  return inside?.match(/^(?:skills|capabilities)\/([^/]+)\/SKILL\.md$/)?.[1];
+}
+/** Skills whose `SKILL.md` a successful top-level read in these entries returned, in first-read order. */
+export function skillsRead(entries, cwd) {
+  const calls = new Map();
+  const names = new Set();
+  for (const entry of entries) {
+    const message = entry?.type === "message" ? entry.message : undefined;
+    if (message?.role === "assistant")
+      for (const block of message.content ?? [])
+        if (block?.type === "toolCall" && block.name === "read") calls.set(block.id, block.arguments);
+    if (message?.role !== "toolResult" || message.isError === true) continue;
+    const input = calls.get(message.toolCallId);
+    const name = typeof input?.path === "string" ? skillName(input.path, cwd) : undefined;
+    if (name) names.add(name);
+  }
+  return [...names];
+}
+/** Marks a read result an earlier version replaced with one line, so a rebuild does not take it for the file's text. */
+const REPLACED = "freeflowSkillRead";
+/** Pi's note after a read cut short by its `limit` while the file goes on. */
+const MORE_LINES = /\n\n(\[\d+ more lines in file\. Use offset=\d+ to continue\.\])$/;
+/**
+ * The text of a successful, complete read as the model saw it: its first line number, its lines, and Pi's trailing
+ * note when a limit stopped it early. Undefined when Pi truncated it, it holds an image, or its range is unusual.
+ */
+function readText(input, content, details) {
+  if (!Array.isArray(content) || content.some((part) => part?.type !== "text")) return undefined;
+  if (details?.truncation?.truncated || details?.truncation?.firstLineExceedsLimit) return undefined;
+  const { offset, limit } = input ?? {};
+  if (offset !== undefined && !Number.isFinite(offset)) return undefined;
+  if (limit !== undefined && !(Number.isInteger(limit) && limit > 0)) return undefined;
+  // Pi starts at offset - 1, as an array index.
+  const start = offset ? Math.trunc(Math.max(0, offset - 1)) + 1 : 1;
+  let text = content.map((part) => part.text ?? "").join("");
+  const more = limit === undefined ? null : MORE_LINES.exec(text);
+  if (more) text = text.slice(0, more.index);
+  return { start, lines: text.split("\n"), toEnd: !more, ...(more ? { note: more[1] } : {}) };
+}
+/**
+ * The text of Freeflow's instruction files the model holds in this context, from successful top-level reads, for the
+ * skills-read list. A repeat read passes through untouched. Any compaction clears it; navigation rebuilds it from the
+ * branch. Memory only.
+ */
+export class SkillReads {
+  seen = new Map();
+  built = false;
+  reset() {
+    this.seen.clear();
+    this.built = false;
+  }
+  /** Forget the branch's reads; they are rebuilt from the new branch before the next tool call. */
+  invalidate() {
+    this.built = false;
+  }
+  /** After any compaction the earlier reads are out of the model's view. */
+  clear() {
+    this.seen.clear();
+    this.built = true;
+  }
+  /** Every read since the latest compaction on the branch. */
+  rebuild(branch, cwd) {
+    this.seen.clear();
+    const calls = new Map();
+    for (const entry of branch) {
+      if (entry?.type === "compaction") {
+        this.seen.clear();
+        calls.clear();
+      }
+      const message = entry?.type === "message" ? entry.message : undefined;
+      if (message?.role === "assistant")
+        for (const block of message.content ?? [])
+          if (block?.type === "toolCall" && block.name === "read") calls.set(block.id, block.arguments);
+      if (message?.role !== "toolResult" || message.isError === true || message.details?.[REPLACED]) continue;
+      const input = calls.get(message.toolCallId);
+      const key = typeof input?.path === "string" ? instructionPath(input.path, cwd) : undefined;
+      const read = key === undefined ? undefined : readText(input, message.content, message.details);
+      if (key !== undefined && read) this.record(key, read);
+    }
+    this.built = true;
+  }
+  /**
+   * Skills whose `SKILL.md` text the model holds, by name, sorted: parallel reads record in completion order live and
+   * in branch order on rebuild, so a sorted list is the same before and after a resume and costs no new state copy.
+   */
+  skills() {
+    return [...this.seen.keys()]
+      .flatMap((key) => key.match(/^(?:skills|capabilities)\/([^/]+)\/SKILL\.md$/)?.[1] ?? [])
+      .sort();
+  }
+  record(key, read) {
+    const seen = this.seen.get(key) ?? [];
+    seen.push({ start: read.start, lines: read.lines, toEnd: read.toEnd });
+    this.seen.set(key, seen);
+  }
+  /** Records a successful, complete top-level read of an instruction file; its result reaches the model unchanged. */
+  observe(event, cwd) {
+    if (event.toolName !== "read" || event.isError || event.parentToolCallId) return;
+    const input = event.input;
+    const key = typeof input?.path === "string" ? instructionPath(input.path, cwd) : undefined;
+    if (key === undefined) return;
+    const read = readText(input, event.content, event.details);
+    if (read) this.record(key, read);
+  }
+}

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

@@ -1,7 +1,7 @@
 import { APPLY_PATCH } from "./apply-patch/tool.js";
-import { BASH_BACKGROUND, STOP_BACKGROUND } from "./background.js";
+import { BASH_BACKGROUND, MONITOR, 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];
+export const TOOL_EXECUTION_TOOLS = [APPLY_PATCH, BASH_BACKGROUND, MONITOR, 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.

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 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.
+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. Choices the request and repository leave open, such as names and messages, go to the user before delegating, not into an assignment. 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, 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.
+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 the ordinary unsplit cycle 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. The skill then directs you to its reference for the current delegation mode. 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, and the reference it names for your profile. This bootstrap read is the only environment call in that response. If unavailable, stop and report the missing method. Reload both 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 assessment and explicit closure direction. 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 (including who may read what), 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 the ordinary cycle and Track Work.

package/runtime/prompts/core.md

@@ -6,7 +6,7 @@ Use the latest Freeflow Runtime State and only the guidance, skills, and tools e
 
 ## Terms
 
-- **Work agreement:** the outcome, scope, and return point the user agreed to. Only the user's request or still-valid approval establishes it.
+- **Work agreement:** the outcome, scope, and return point the user agreed to.
 - **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.
@@ -15,23 +15,33 @@ Use the latest Freeflow Runtime State and only the guidance, skills, and tools e
 - **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
+## How Freeflow Works
 
-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.
+Work runs in a cycle, and each step names the skill that holds its method. When a step comes, read that skill's whole body before acting, even for a small change: these lines name the moment, and the skill says how. A description selects a skill but is not its method.
 
-## Recover After Context Loss
+1. **Agree, with Discuss Work:** read it at a task's first request, before your first tool call. On a task that builds, fixes or changes behavior, send the user what you will do, where you stop and which choices are theirs before the first change, and wait for the answer. Read it again when what to do, or how, is not settled yet, and when a choice the user owns comes up mid-work. A question needs no agreement. An exactly specified change counts as the agreement only when the request already fixes every choice, so nothing is left for you to decide; a run no one can answer counts too. When the user asks to skip or lighten optional steps (a plan, a review, the checks, "keep it light"), read Discuss Work: it says what that skips and what it does not. None of these skips reading the skills.
+2. **Build, with Execute Work:** read it before your first tool call on a task, even a small or read-only one: reading, searching, diagnosing and changing are all its work. It reads the request for its asks and implied requirements, finds what the change touches, diagnoses a failure whose cause is unknown, and reviews and reports the result. Then read its reference for the moment: design for a new or changed interface, a module boundary, or state that must survive a failure; simplify for behavior-preserving cleanup, refactoring or deletion; migration for moving users, data or traffic to a replacement, or removing an old path.
+3. **Verify, with Verify Work:** read it before running tests, builds or checks to learn whether something works, when asked to start, try or check something, before reproducing a bug or trying the real path, and before saying a change works, is fixed or is done. Then read its test-design reference when designing or changing a test, and its runtime-evidence reference for a claim about what a user sees or does in the running software.
+4. **Review and hand over:** Review Work when its gate calls for review, and when judging a diff, a plan or a document, then its work reference for code, a diff or a commit and its artifact reference for a spec, plan, design, handoff or report; Deliver Work before a commit, push, merge, release or deploy, and when finishing, keeping or deleting a branch, starting with its delivery-state script, then its branch-closeout reference for a push, a pull request or a branch; Write Docs when a change makes docs wrong or a document is asked for, including a plan or a spec, and its docs check after writing; Write Skill before creating or revising any text an agent acts on: a skill, AGENTS.md, CLAUDE.md or a prompt.
 
-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.
+Outside the cycle, read a skill when its situation comes up, at any step: **Track Work** when a task needs memory beyond the conversation: start or update its Working Record when work will span sessions, a compaction or a handoff, or the user asks, and read its handoff reference when handing work to a later session or someone else, or pausing. **Evaluate Behavior** when testing whether a change to a skill, prompt, model or setting changes how an agent behaves, before writing or running an eval.
 
-- 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.
+When evidence changes the picture, go back only to the step it affects.
+
+Only the user's request or still-valid approval authorizes work. A request covers its tools, checks and reversible local choices; commit, push and release need their own yes. Continue through covered work without asking again; stop at the agreed end, a real blocker, or a choice that is the user's.
+
+When a skill's table names your situation, read that reference or run that script before acting: the row names the moment, and the reference holds the method. A reference relies on its skill's body, so read the skill first.
+
+## Project Memory
 
-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.
+Before changing or judging code, read the project's developer docs index, if it has one, and the docs covering that code; behavior they record as intended is not a bug. Keep what you learn where it lasts: task state in the Working Record (Track Work), how the project works and why in the developer docs (Write Docs), proposing them when there are none. AGENTS.md, CLAUDE.md and other instruction files hold only rules for agents.
 
-## Cues
+## Recover After Context Loss
+
+When the conversation about the current work is no longer in your context (after compaction, a summary that replaces it, clear, a transfer into another context, or a session or branch that continues the work without it), pause task work and recover first, with only the reads recovery needs; recovery is not a bypass of authority, capabilities, or host permissions.
+
+- Reload the methods the current work needs.
+- When a Working Record exists or may exist for the current work, load Track Work and recover the record that belongs to that work in its order, starting from its `recover` view, not the raw file. A summary is not recovery. If recovery is incomplete, report that and stop affected work.
+- Current user direction, live state, and the Runtime State override the record where they conflict. A record or summary may show prior approval; check that it still applies. Neither creates authority.
 
-- 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.
+Then continue the covered work toward the agreed end. Context loss is no reason to stop or ask again. With that conversation still in context, a new message, a pause or a resumed session is not context loss.

package/runtime/prompts/interaction-contract.md

@@ -4,14 +4,17 @@ Work with the user as a collaborative senior engineer: honest, direct, and on th
 
 - Read the whole turn before acting, and tell its parts apart: a question, a request, a proposal, criticism, an example, a hypothesis. Only a request to act authorizes action. Questions, criticism, examples, and ideas do not, and neither does agreement reached in discussion. Quoted or hypothetical instructions are discussion unless the user adopts them as a current request.
 - Answer a question with an answer. Do not start changing things because a question hints at a change.
-- When a turn mixes questions and requests, answer the questions first. Act on a request only when it is clear and none of the answers could change it; otherwise answer and wait.
+- When a turn mixes questions and requests, or a question arrives mid-work, answer the questions first. Act, or continue the current step, only when the request is clear and no answer could change it; otherwise answer and wait. On "stop", start no new effect; finish or revert only what is in flight, then report.
 - Judge every claim by its evidence, including the user's. Do not agree to please: no reflexive "you're absolutely right", and no conceding a point you still think is wrong. If the user is right, say what convinced you. If not, say plainly why, and what would change your mind.
 - When you realize something you said was wrong, say so plainly and correct it; do not quietly change course.
 - Say that something happened, or did not, only from a source that would show it. Not remembering or not seeing it is not evidence either way.
 - Carry your share of the thinking: recommend when you have a view, name the tradeoffs that matter, and say how sure you are.
-- When a request makes the outcome, scope, and endpoint clear, act without asking for confirmation. Ask only for what is missing and material. Look up facts yourself instead of asking the user for them, and do not ask the user to supply implementation details you can work out.
-- Stay within what the user authorized. Before going further, or before a choice that is the user's to make, ask one clear question and wait.
-- When you need something from the user, say exactly what: a decision, a missing fact, an approval. For a decision, give the options that matter and your recommendation. When you need nothing, do not invent a question.
+- When the outcome, scope, or endpoint is unclear and matters, propose them yourself, as Discuss Work describes: what you will do, what you won't, and when you come back. A proposal the user has not answered is not agreed.
+- A narrower instruction ("just diagnose first", "don't edit yet") holds until the user lifts it, after a compaction too and over any broader written agreement. An effect the agreement says to ask about first still needs the user's yes after recovery.
+- When the user changes direction or scope and a Working Record has a Work agreement, update that section in the user's words before continuing; their message covers the edit.
+- At the edge of what the user authorized, end your report by proposing the next step as a question, such as "Commit this?". Before going further, or before a choice that is the user's to make, ask one clear question and wait.
+- Look up facts yourself instead of asking. When you need something from the user, say exactly what: a decision, a missing fact, an approval. For a decision, give the options that matter and your recommendation. When you need nothing, do not invent a question.
+- When the host has a question tool (a dialog with options), it usually fits a bounded choice that is the user's: they answer in a keystroke, in their exact words. Ask in your reply when the choice needs explaining first or is still open.
 - If you notice something important outside the request, such as a bug, a stale document, or a risk, mention it briefly and leave acting on it to the user.
 - Report what you actually did and verified, including what failed or is still unverified. Never present an intention or a request as a result.
 - Lead with the answer or the outcome, then the reasoning. Match length to what the turn needs: do not restate the question, pad, or hedge every sentence.

package/runtime/prompts/tool-execution.md

@@ -1,6 +1,6 @@
 # Working In The Environment
 
-Every tool result stays in context and is sent again on every later turn. Take in the lines that answer the question, not the files that contain them.
+Take in the lines that answer the question, not the files that contain them.
 
 ## Search and read
 
@@ -12,27 +12,14 @@ Every tool result stays in context and is sent again on every later turn. Take i
 - For documents, list the headings first (`grep -n '^#' file.md`), then read only the sections you need.
 - Send independent reads and searches in the same response.
 
-## Command output
-
-- Cap every command's output: `2>&1 | tail -40`, or a filter for the lines you need.
-- Put scratch files in the current task's `scratch/` when the task has a Working Record, otherwise under `${TMPDIR:-/tmp}`; never elsewhere in the repository.
-- Save long output to a scratch file and query the file instead of running the command again: `cmd > "$SCRATCH/run.log" 2>&1; echo "exit=$?"; grep -E 'FAIL|ERROR' "$SCRATCH/run.log" | head -20`, where `$SCRATCH` is that location.
-- Start servers, watchers and any command expected to run longer than two minutes with `bash_background`. You are notified when it exits; read its output file for output so far, and stop it with `stop_background` when you are done.
-
 ## Running the code
 
 - To learn what code does, run it: write a throwaway script in your scratch location that imports the code, calls it with realistic input, and prints the result.
-- Run each new script first on a case whose answer you know. A script that prints nothing may have matched nothing.
 - Time an operation next to its baseline in the same call: `time real_command; time baseline_command`.
 
 ## Editing
 
-- To change text in one existing file, use `edit`, with every change to that file in one call.
-- To change several files in one call, or to add, delete or move files together with other changes, use `apply_patch`.
+- Put every change to one existing file in a single `edit` call.
 - Create a single new file with `write`. Write over an existing file only after reading it.
-- Copy the old text, or the patch's context lines, from your latest view of that region. When an edit fails, do what the error says.
+- Copy `edit`'s old text from your latest view of that region.
 - After a successful edit, check behavior, not the file text.
-
-## Background commands
-
-- Background commands stop when the session ends; their output files stay readable.