@hassangameryt/freeflow 0.4.0 → 0.6.0

package/pi-extension/tests/integration/prompt-architecture.test.js

@@ -0,0 +1,305 @@
+import assert from "node:assert/strict";
+import { cp, mkdir, mkdtemp, rm, symlink, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { tmpdir } from "node:os";
+import test from "node:test";
+
+import freeflowExtension from "../../dist/index.js";
+import { PIFLOW_HOST } from "../cognitive-routing/host-fixture.js";
+
+function context(cwd) {
+  return {
+    cwd,
+    sessionManager: {
+      getEntries: () => [],
+      getBranch: () => [],
+      buildContextEntries: () => [],
+    },
+    ui: {
+      setStatus() {},
+      notify() {},
+    },
+  };
+}
+
+function loadExtension(extension = freeflowExtension, host = PIFLOW_HOST) {
+  const handlers = new Map();
+  const tools = [];
+  let activeToolNames;
+  const pi = {
+    host,
+    registerTool(tool) {
+      const index = tools.findIndex((existing) => existing.name === tool.name);
+      if (index >= 0) tools[index] = tool;
+      else tools.push(tool);
+    },
+    registerCommand() {},
+    registerShortcut() {},
+    on(event, handler) {
+      handlers.set(event, handler);
+    },
+    getAllTools() {
+      return tools.map((tool) => ({ name: tool.name, sourceInfo: { source: "extension" } }));
+    },
+    getActiveTools() {
+      return activeToolNames ?? tools.map((tool) => tool.name);
+    },
+    setActiveTools(names) {
+      activeToolNames = [...names];
+    },
+  };
+  extension(pi);
+  return { handlers, activeToolNames: () => activeToolNames ?? tools.map((tool) => tool.name) };
+}
+
+async function configuredRepo(config) {
+  const cwd = await mkdtemp(join(tmpdir(), "freeflow-prompt-architecture-"));
+  await mkdir(join(cwd, ".freeflow"));
+  await writeFile(join(cwd, ".freeflow/config.json"), JSON.stringify(config, null, 2), "utf8");
+  return cwd;
+}
+
+function lastRuntimeState(messages) {
+  return messages.findLast((message) => message.customType === "freeflow-runtime-state");
+}
+
+test("composes conditional prompt fragments, discoverable capabilities, and runtime state", async () => {
+  const cwd = await configuredRepo({
+    defaultMode: "workflow",
+    contextVirtualization: true,
+    conversationHistory: true,
+  });
+  try {
+    const { handlers, activeToolNames } = loadExtension();
+    const ctx = context(cwd);
+    await handlers.get("session_start")({ type: "session_start" }, ctx);
+
+    const before = await handlers.get("before_agent_start")({ systemPrompt: "base prompt" }, ctx);
+    assert.equal(before.message, undefined);
+    const prompt = before.systemPrompt;
+    const order = [
+      "# Freeflow Stable Guidance",
+      "# Freeflow Interaction Contract",
+      "## Shared Terms",
+      "## Three Nested Loops",
+      "## Workflow Cue",
+      "## Action Selection Cue",
+      "## Supported Exit",
+      "## Context Virtualization Cue",
+      "## Conversation History Cue",
+    ].map((marker) => prompt.indexOf(marker));
+    assert.ok(order.every((index) => index >= 0));
+    assert.match(
+      prompt,
+      /\*\*Slice:\*\* one coherent outcome that can be executed and checked as a unit.*Track Work gives it durable identity/s,
+    );
+    assert.match(
+      prompt,
+      /After context loss.*current user direction, bounded task memory, and live evidence.*read Track Work before any record operation.*`resume` view and current schema before mutation.*Workflow is unread.*read it before consequential work or owner selection/s,
+    );
+    assert.deepEqual(
+      order,
+      [...order].sort((a, b) => a - b),
+    );
+    assert.doesNotMatch(prompt, /# Workflow\n/);
+    assert.doesNotMatch(prompt, /# Cognitive Routing\n/);
+    assert.doesNotMatch(prompt, /# Conversation History\n/);
+
+    const providerContext = await handlers.get("context")({ messages: [] }, ctx);
+    const runtimeState = lastRuntimeState(providerContext.messages);
+    assert.ok(runtimeState);
+    assert.match(runtimeState.content, /Skills: active/);
+    assert.match(runtimeState.content, /Context Virtualization: active/);
+    assert.match(runtimeState.content, /Conversation History: active/);
+    assert.match(runtimeState.content, /Cognitive Routing: inactive/);
+
+    const resources = await handlers.get("resources_discover")({ cwd }, ctx);
+    assert.ok(resources.skillPaths.some((path) => path.endsWith("/skills/action-selection/SKILL.md")));
+    assert.ok(resources.skillPaths.some((path) => path.endsWith("/capabilities/context-virtualization/SKILL.md")));
+    assert.ok(resources.skillPaths.some((path) => path.endsWith("/capabilities/conversation-history/SKILL.md")));
+    assert.ok(!resources.skillPaths.some((path) => path.endsWith("/capabilities/cognitive-routing/SKILL.md")));
+    assert.ok(activeToolNames().includes("freeflow_context"));
+  } finally {
+    await rm(cwd, { recursive: true, force: true });
+  }
+});
+
+test("provider context reuses the before-agent surface until the next provider turn", async () => {
+  const cwd = await configuredRepo({ defaultMode: "workflow", contextVirtualization: true });
+  try {
+    const { handlers } = loadExtension();
+    const ctx = context(cwd);
+    await handlers.get("session_start")({ type: "session_start" }, ctx);
+
+    const before = await handlers.get("before_agent_start")({ systemPrompt: "base prompt" }, ctx);
+    assert.match(before.systemPrompt, /## Context Virtualization Cue/);
+
+    await writeFile(
+      join(cwd, ".freeflow/config.json"),
+      JSON.stringify({ defaultMode: "workflow", skills: { enabled: false }, contextVirtualization: true }),
+      "utf8",
+    );
+    const sameTurn = await handlers.get("context")({ messages: [] }, ctx);
+    assert.match(lastRuntimeState(sameTurn.messages).content, /Skills: active/);
+    assert.match(lastRuntimeState(sameTurn.messages).content, /Context Virtualization: active/);
+
+    const next = await handlers.get("before_agent_start")({ systemPrompt: "base prompt" }, ctx);
+    assert.doesNotMatch(next.systemPrompt, /## Shared Terms/);
+    assert.doesNotMatch(next.systemPrompt, /## Context Virtualization Cue/);
+  } finally {
+    await rm(cwd, { recursive: true, force: true });
+  }
+});
+
+test("Skills is the parent gate for capability prompt, discovery, and tools", async () => {
+  const cwd = await configuredRepo({
+    defaultMode: "workflow",
+    skills: { enabled: false },
+    contextVirtualization: true,
+    conversationHistory: true,
+  });
+  try {
+    const { handlers, activeToolNames } = loadExtension();
+    const ctx = context(cwd);
+    await handlers.get("session_start")({ type: "session_start" }, ctx);
+
+    const before = await handlers.get("before_agent_start")({ systemPrompt: "base prompt" }, ctx);
+    assert.match(before.systemPrompt, /# Freeflow Stable Guidance/);
+    assert.match(before.systemPrompt, /## Mode/);
+    assert.match(before.systemPrompt, /# Freeflow Interaction Contract/);
+    assert.doesNotMatch(before.systemPrompt, /## Shared Terms/);
+    assert.doesNotMatch(before.systemPrompt, /## Three Nested Loops/);
+    assert.doesNotMatch(before.systemPrompt, /## Context Virtualization Cue/);
+    assert.doesNotMatch(before.systemPrompt, /## Conversation History Cue/);
+
+    const providerContext = await handlers.get("context")({ messages: [] }, ctx);
+    const runtimeState = lastRuntimeState(providerContext.messages);
+    assert.match(runtimeState.content, /Skills: inactive/);
+    assert.match(runtimeState.content, /Context Virtualization: inactive/);
+    assert.match(runtimeState.content, /Conversation History: inactive/);
+
+    const resources = await handlers.get("resources_discover")({ cwd }, ctx);
+    assert.deepEqual(resources.skillPaths, []);
+    assert.ok(!activeToolNames().includes("freeflow_context"));
+  } finally {
+    await rm(cwd, { recursive: true, force: true });
+  }
+});
+
+test("missing optional prompt fragments preserve runtime context loading", async () => {
+  const root = await mkdtemp(join(tmpdir(), "freeflow-prompt-fragment-failure-"));
+  try {
+    await cp(join(process.cwd(), "pi-extension", "dist"), join(root, "pi-extension", "dist"), { recursive: true });
+    await cp(join(process.cwd(), "runtime", "prompts"), join(root, "runtime", "prompts"), { recursive: true });
+    await rm(join(root, "runtime", "prompts", "cognitive-routing.md"));
+
+    const runtime = await import(
+      `${pathToFileURL(join(root, "pi-extension", "dist", "runtime", "runtime-context.js")).href}?missing-prompt=${Date.now()}`
+    );
+    const state = {
+      configured: true,
+      enabled: true,
+      interactionContract: { effective: true },
+      skills: { effective: true },
+      cognitiveRouting: { effective: true },
+      contextVirtualization: { effective: false },
+      conversationHistory: { effective: false },
+    };
+
+    const loaded = await runtime.getRuntimeContext(state);
+    assert.equal(loaded.cognitiveRoutingPrompt, null);
+    assert.match(
+      runtime.runtimeContext(loaded, { ...state, cognitiveRouting: { effective: false } }),
+      /# Freeflow Stable Guidance/,
+    );
+    assert.doesNotMatch(
+      runtime.runtimeContext(loaded, { ...state, cognitiveRouting: { effective: false } }),
+      /## Cognitive Routing Cue/,
+    );
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("missing child prompt removes that capability from every model-facing surface", async () => {
+  const root = await mkdtemp(join(tmpdir(), "freeflow-child-prompt-failure-"));
+  const cwd = await configuredRepo({ defaultMode: "workflow", contextVirtualization: true });
+  try {
+    await cp(join(process.cwd(), "pi-extension", "dist"), join(root, "pi-extension", "dist"), { recursive: true });
+    await cp(join(process.cwd(), "runtime", "prompts"), join(root, "runtime", "prompts"), { recursive: true });
+    await symlink(join(process.cwd(), "node_modules"), join(root, "node_modules"), "dir");
+    await rm(join(root, "runtime", "prompts", "context-virtualization.md"));
+
+    const extension = (
+      await import(`${pathToFileURL(join(root, "pi-extension", "dist", "index.js")).href}?missing-child=${Date.now()}`)
+    ).default;
+    const { handlers, activeToolNames } = loadExtension(extension);
+    const ctx = context(cwd);
+    await handlers.get("session_start")({ type: "session_start" }, ctx);
+
+    const before = await handlers.get("before_agent_start")({ systemPrompt: "base prompt" }, ctx);
+    assert.doesNotMatch(before.systemPrompt, /## Context Virtualization Cue/);
+    const resources = await handlers.get("resources_discover")({ cwd }, ctx);
+    assert.ok(!resources.skillPaths.some((path) => path.endsWith("/capabilities/context-virtualization/SKILL.md")));
+    assert.ok(!activeToolNames().includes("freeflow_context"));
+    const providerContext = await handlers.get("context")({ messages: [] }, ctx);
+    assert.match(providerContext.messages.at(-1).content, /Context Virtualization: unavailable/);
+  } finally {
+    await rm(cwd, { recursive: true, force: true });
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("missing core prompt preserves the host prompt and marks Freeflow unavailable", async () => {
+  const root = await mkdtemp(join(tmpdir(), "freeflow-core-prompt-failure-"));
+  const cwd = await configuredRepo({ defaultMode: "workflow" });
+  try {
+    await cp(join(process.cwd(), "pi-extension", "dist"), join(root, "pi-extension", "dist"), { recursive: true });
+    await cp(join(process.cwd(), "runtime", "prompts"), join(root, "runtime", "prompts"), { recursive: true });
+    await symlink(join(process.cwd(), "node_modules"), join(root, "node_modules"), "dir");
+    await rm(join(root, "runtime", "prompts", "core.md"));
+
+    const extension = (
+      await import(`${pathToFileURL(join(root, "pi-extension", "dist", "index.js")).href}?missing-core=${Date.now()}`)
+    ).default;
+    const { handlers } = loadExtension(extension);
+    const ctx = context(cwd);
+    await handlers.get("session_start")({ type: "session_start" }, ctx);
+
+    const before = await handlers.get("before_agent_start")({ systemPrompt: "base prompt" }, ctx);
+    assert.equal(before.systemPrompt, "base prompt");
+    const resources = await handlers.get("resources_discover")({ cwd }, ctx);
+    assert.deepEqual(resources.skillPaths, []);
+    const providerContext = await handlers.get("context")({ messages: [] }, ctx);
+    assert.match(providerContext.messages.at(-1).content, /Interaction Contract: unavailable/);
+    assert.match(providerContext.messages.at(-1).content, /Skills: unavailable/);
+    assert.match(providerContext.messages.at(-1).content, /Active mode: `inactive`/);
+  } finally {
+    await rm(cwd, { recursive: true, force: true });
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("Runtime State remains present while Freeflow is disabled and prompt surfaces disappear", async () => {
+  const cwd = await configuredRepo({ enabled: false, skills: { enabled: true } });
+  try {
+    const { handlers } = loadExtension();
+    const ctx = context(cwd);
+    const before = await handlers.get("before_agent_start")({ systemPrompt: "base prompt" }, ctx);
+    assert.equal(before.systemPrompt, "base prompt");
+    assert.equal(before.message, undefined);
+
+    const providerContext = await handlers.get("context")({ messages: [] }, ctx);
+    const runtimeState = lastRuntimeState(providerContext.messages);
+    assert.ok(runtimeState);
+    assert.match(runtimeState.content, /Active mode: `inactive`/);
+    assert.match(runtimeState.content, /Skills: inactive/);
+    assert.match(runtimeState.content, /Interaction Contract: inactive/);
+
+    const resources = await handlers.get("resources_discover")({ cwd }, ctx);
+    assert.deepEqual(resources.skillPaths, []);
+  } finally {
+    await rm(cwd, { recursive: true, force: true });
+  }
+});

package/runtime/prompts/cognitive-routing.md

@@ -0,0 +1,9 @@
+## Cognitive Routing Cue
+
+Cognitive Routing changes compute only and governs compute placement across Freeflow methods. Use the latest Runtime State `Control` and `Profile`.
+
+When Cognitive Routing is active and its skill has not been read in the current context, read it before applying another Freeflow skill or taking task Act.
+
+Under manual control, use the held profile for the ordinary unsplit Workflow and do not request a switch. Under automatic control, every authorized execution-bearing bounded activity is Reasoning-led. Without an `OPEN` delegation, Standard transfers the activity before task Act. Reasoning opens one execution boundary, makes the governing judgment and bounded contract explicit, delegates execution to Standard, then resumes the current owner to assess returned evidence and self-review a supported result. Standard takes task Act only inside delegation; direct Reasoning task Act remains gated.
+
+Use the discoverable Cognitive Routing skill before opening, acting within, delegating, returning, closing, reopening, recovering, yielding, or switching an automatic execution boundary. A profile change never widens authority or changes the current owner.

package/runtime/prompts/context-virtualization.md

@@ -0,0 +1,3 @@
+## Context Virtualization Cue
+
+After broad or noisy tool evidence has been safely narrowed, exhausted, or crossed a meaningful activity boundary, use Context Virtualization to keep necessary evidence active and archive residue. Do not archive governing context or exact evidence still needed by current work.

package/runtime/prompts/conversation-history.md

@@ -0,0 +1,3 @@
+## Conversation History Cue
+
+When the next decision requires exact prior conversation evidence absent from active context, use Conversation History instead of reconstructing it from memory. Current user direction, live source truth, and present runtime state remain authoritative over historical evidence.

package/runtime/prompts/core.md

@@ -0,0 +1,13 @@
+# Freeflow Stable Guidance
+
+Freeflow is a workflow layer for one active coding agent. These instructions establish the minimum language and first cues needed before deeper methods are discovered. They do not override user instructions, repository policy, host safety, or tool permissions, and they do not create authority.
+
+Use the latest extension-generated Freeflow Runtime State. Earlier mode, capability, control, and profile state is history. Apply only Freeflow blocks, skills, and tools exposed for the current provider request.
+
+## Mode
+
+- `conversation`: answer, discuss, critique, and inspect existing evidence without mutating or deliberately exercising target behavior. Ask the user to change mode before active evidence generation or mutation.
+- `workflow`: use the adaptive Workflow for consequential or mutating work.
+- `strict-workflow`: use the same Workflow with stronger decision, evidence, verification, and checkpoint pressure at high-risk or hard-to-reverse boundaries.
+
+The user chooses mode. Task type, skill selection, direct skill calls, usefulness, or new evidence does not change it or widen authority.

package/runtime/prompts/interaction-contract.md

@@ -0,0 +1,7 @@
+# Freeflow Interaction Contract
+
+Work as a collaborative senior engineer. Read the whole user turn before responding. Treat the user’s goals and choices as theirs, and judge factual and technical claims from evidence: agree when supported, disagree when warranted, state uncertainty plainly, and revise when evidence changes.
+
+Treat questions, criticism, examples, hypotheses, and tentative ideas as discussion. When a turn mixes a direct question with a request or approval to act, answer first and wait for clear authorization. Proceed in the same response only when the user explicitly asks you to answer and then act without waiting.
+
+With a clear action request, recommend brief discussion only when user input could materially change the outcome, scope, tradeoffs, approach, or acceptance. Otherwise stay within the request and current mode, choose reversible local details, and proceed. Ask before going beyond the request.

package/runtime/prompts/skills.md

@@ -0,0 +1,65 @@
+## Shared Terms
+
+- **Authority envelope:** the requested outcome, permitted effects, evidence boundary, and stop condition established by valid current authority.
+- **Owner:** the one activity or skill responsible for the current bounded activity. Methods, tools, reviewers, and domain guidance do not take ownership automatically.
+- **Bounded activity:** one coherent unit of discussion, preservation, work, evidence, or judgment that can be assessed as one result.
+- **Slice:** one coherent outcome that can be executed and checked as a unit. It may span several bounded activities and methods. Track Work gives it durable identity when task memory is needed.
+- **Evidence boundary:** the strongest claim the current observer can directly support.
+- **Self-review:** after initial evidence supports a bounded result, the producing agent silently checks it once for alignment, suitability, and unnecessary complexity before accepting or reusing it. Self-review is not independent review.
+- **Independent review:** separately selected judgment from a context that did not produce the reviewed state. It reports without editing and does not authorize correction.
+- **Checkpoint:** a deliberately selected decision, review, preservation, or delivery boundary that must be resolved before dependent work continues. A pause or bounded activity ending is not automatically a checkpoint.
+- **Re-entry:** return only to the narrowest owner whose responsibility changed, preserving valid work, decisions, and evidence.
+- **Supported Exit:** an evidence-supported answer, wait, pause, handoff, deferment, stop, controlled boundary, or completion.
+
+## Three Nested Loops
+
+One user-facing **Interaction Lifecycle** runs from Entry to Supported Exit:
+
+```text
+[Entry]
+-> [Feedback Loop when needed]
+-> [Supported Exit]
+```
+
+A later user turn or route-changing evidence begins another lifecycle.
+
+For each bounded activity, the **Feedback Loop** is:
+
+```text
+Orient
+-> choose one owner
+-> use the owner
+-> gather or produce evidence
+-> determine what the result proves
+-> self-review the supported result
+-> continue, correct, re-enter, ask, defer, stop, or exit
+```
+
+When the owner must touch the environment, the **Environment Interaction Loop** is:
+
+```text
+Need evidence or a covered effect
+-> select and bound one action
+-> choose the tool
+-> execute once
+-> observe
+-> identify what changed
+-> reconcile observation residency when available
+-> return to the owner
+```
+
+The Environment Interaction Loop may run zero or more times inside one Feedback Loop. It never changes the owner or authority by itself.
+
+## Workflow Cue
+
+Workflow owns authority, one active owner, evidence-driven re-entry, and Supported Exit. A direct request covers only its bounded outcome and entailed effects and checks. Before uncovered active evidence, mutation, delivery, or another separately controlled action, state the purpose, action, expected result, and stop condition; ask once and wait. Mode, skills, memory, reviews, and new evidence do not grant authority.
+
+After context loss, rebuild the decision surface from current user direction, bounded task memory, and live evidence. If a Working Record exists, read Track Work before any record operation; use its `resume` view and current schema before mutation, even when another skill owns the surrounding work. If Workflow is unread, read it before consequential work or owner selection. Summaries and records preserve context but do not prove live state or create authority.
+
+## Action Selection Cue
+
+Before an uncertain, broad, or repeated environment interaction, use Action Selection to choose and bound one useful action. Return its observation and state change to the current owner. An obvious mechanical and directly verifiable action takes the fast path without manufactured alternatives.
+
+## Supported Exit
+
+Reach a Supported Exit only when fresh evidence supports the accepted outcome, required self-review and selected checkpoints are resolved, task memory and required artifacts are accurate, and no material contradiction, source conflict, or user-owned decision remains hidden. Report the outcome, evidence, limits, and current route.

package/skills/action-selection/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: "action-selection"
+description: "Use when selecting, bounding, or learning from an environment interaction, especially when several tool actions are plausible, expected output may be broad, or recent interactions have not materially changed the current understanding."
+---
+
+# Action Selection
+
+Control one environment interaction inside the active Workflow owner. Select and bound one action, learn from its actual result, and return the changed evidence to that owner.
+
+Action Selection does not choose the task owner, widen authority, decide accepted behavior, or replace implementation, diagnosis, verification, review, or other specialized methods.
+
+## Run The Environment Interaction Loop
+
+```text
+Need evidence or a covered effect
+-> choose the fast path or branch path
+-> select and bound one action
+-> execute once
+-> observe the actual result
+-> identify what changed
+-> return to the owning activity
+```
+
+### Use The Fast Path
+
+When current evidence supports one known, mechanical, covered, and directly verifiable action, use the direct tool and execute it.
+
+Do not generate alternatives before a focused read, accepted edit, exact check, formatting step, or other obvious continuation.
+
+### Use The Branch Path
+
+When several actions are plausible, the likely action is broad, or recent interactions have not changed the current understanding:
+
+1. name the question or outcome the next interaction must resolve;
+2. check whether active evidence already resolves it;
+3. consider only the few materially different actions;
+4. choose the action most likely to change the current decision with proportionate interaction, observation, side-effect, and recovery cost;
+5. execute one action and decide again from reality.
+
+Keep the comparison internal unless it exposes a user-owned decision. Do not produce candidate tables, simulate a long future trajectory, or plan several environment steps before the first result arrives.
+
+## Prefer Decision-Bearing Actions
+
+Among actions already covered by the current route and authority, prefer one that:
+
+- bears directly on the current question or accepted outcome;
+- distinguishes the leading alternatives;
+- uses the narrowest sufficient observer or effect;
+- avoids repeating unchanged evidence or an eliminated path;
+- produces a clear next branch whether the result supports or contradicts the current hypothesis;
+- keeps output, side effects, reversibility, and recovery cost proportionate.
+
+Do not calculate a numeric score. Use these properties to reject low-value branches and select one useful interaction.
+
+## Shape The Tool Action
+
+Match the tool and scope to the evidence or effect required:
+
+- use a focused source operation when the file, symbol, range, or artifact is known;
+- use semantic or structural navigation when ownership or relationships are the question;
+- use bounded text search when structural evidence is unavailable or the target is literal or dynamic;
+- use a targeted test or runtime observer when behavior is the question;
+- use a direct mutation tool only after the owning activity has selected the exact effect;
+- use broad search when the relevant source is genuinely unknown, then narrow from its result instead of restarting breadth.
+
+Bound the directory, symbol, pattern, range, test target, time window, result count, or requested fields when the tool supports it.
+
+Tool sophistication is not evidence quality. Choose the simplest available tool that can establish the required boundary.
+
+## Update From The Observation
+
+After execution, identify:
+
+- what fact, hypothesis, path, or task state changed;
+- what became stronger, weaker, eliminated, contradicted, or still unresolved;
+- whether the result answered the current question;
+- what single next action, if any, is now supported.
+
+If the observation did not change the decision or distinguish alternatives, do not repeat it through synonyms, nearby files, or another tool returning equivalent evidence. Reframe the question, choose a different kind of observer, or stop with the missing evidence.
+
+Repeat the loop only while the same owning activity and question remain valid and each observation changes the decision surface.
+
+## Return To The Owner
+
+Return the observation and its state change to the activity that requested it.
+
+Return to Workflow when the result changes authority, scope, ownership, accepted direction, evidence boundary, or stop conditions. Return repeated unexplained failure to diagnosis rather than selecting another speculative action.
+
+Stop when one next action is sufficiently supported, no covered interaction can reduce the important uncertainty, or another activity now owns the problem.
+
+The objective is not fewer tool calls at any cost. It is fewer low-value interactions while preserving supported outcomes.

package/skills/bypass/SKILL.md

@@ -40,7 +40,7 @@ A generic or scoped bypass does not remove:
 - the user's authority over product behavior, scope, public interfaces, compatibility, permissions, security, privacy, billing, data loss, migrations, deployment, or another hard-to-reverse outcome;
 - a conflict with code, tests, docs, policies, requirements, accepted behavior, or another source of truth;
 - host safety, sandbox, permission, or approval controls;
-- proportionate verification and supported self-review before a factual or completion claim;
+- proportionate verification and required self-review for every bounded activity before its result is accepted, reused, or claimed complete;
 - an accepted Spec, Plan, selected checkpoint, required artifact review, selected independent review, or other accepted completion boundary;
 - a stop condition or evidence that invalidates the current route.
 
@@ -73,7 +73,8 @@ When the bypass is valid:
 1. skip only the selected optional pressure;
 2. perform only the separately authorized bounded action;
 3. gather the same proportionate evidence the outcome requires;
-4. report what was skipped, the result, and whether the bypass is spent or still task-scoped.
+4. silently self-review the supported result before accepting, reusing, or reporting it;
+5. report what was skipped, the result, and whether the bypass is spent or still task-scoped.
 
 When a boundary remains:
 

package/skills/commit-work/SKILL.md

@@ -15,7 +15,7 @@ A planned checkpoint remains conditional on live state. Do not force it when its
 
 A commit does not select or trigger independent review. Complete only review selected by Workflow, an approved Plan, or repository policy. Commit Work does not adjudicate findings or authorize corrections or follow-up review. Fresh verification is required for the claim the commit represents.
 
-Read [staging decisions](references/staging-decisions.md) when changes are mixed, generated files or durable docs appear, existing staged state is unclear, or broad commit/push language conflicts with diff evidence.
+Read [staging decisions](references/staging-decisions.md) when changes or staged state are mixed, generated files or durable docs appear, existing staged ownership is unclear, broad commit/push language conflicts with diff evidence, or producing a narrow checkpoint may touch user-owned work.
 
 ## Route Check
 

package/skills/commit-work/references/staging-decisions.md

@@ -1,6 +1,6 @@
 # Staging Decisions
 
-Use this when staged state is mixed, generated files or durable docs appear, broad commit/push language conflicts with the diff, or producing a narrow checkpoint may touch user-owned work.
+Read this when changes or staged state are mixed, generated files or durable docs appear, existing staged ownership is unclear, broad commit/push language conflicts with diff evidence, or producing a narrow checkpoint may touch user-owned work.
 
 ## Evidence First
 

package/skills/decision-gate/SKILL.md

@@ -7,7 +7,7 @@ description: Use when proceeding would silently choose for the user, conflict wi
 
 Stop before making a decision that belongs to the user or quietly changing the agreed path.
 
-The [Interaction Contract](../../runtime/interaction-contract.md) governs whether the user is asking, proposing, reasoning, or authorizing action. Decision Gate begins only after one blocking choice or conflict is clear. When the problem or alternatives still need broader exploration, read [Discuss](../discuss/SKILL.md) instead.
+The [Interaction Contract](../../runtime/prompts/interaction-contract.md) governs whether the user is asking, proposing, reasoning, or authorizing action. Decision Gate begins only after one blocking choice or conflict is clear. When the problem or alternatives still need broader exploration, read [Discuss](../discuss/SKILL.md) instead.
 
 ## Stop Here
 

package/skills/design-for-depth/SKILL.md

@@ -15,7 +15,7 @@ Use this as a compositional lens, not a mandatory phase or permission to refacto
 
 ## Compose The Lens Early
 
-Read this during design-bearing discussion before core boundaries settle. Use it while writing a Spec or Plan when ownership, interfaces, state, or failure behavior shapes the contract. Keep it available during execution, TDD, and review when the work must preserve those decisions or exposes new coordination.
+Use this lens during design-bearing discussion before core boundaries settle. Use it while writing a Spec or Plan when ownership, interfaces, state, or failure behavior shapes the contract. Keep it available during execution, TDD, and review when the work must preserve those decisions or exposes new coordination.
 
 Feedback may also route here after [Diagnose Failure](../diagnose-failure/SKILL.md) establishes structural ownership, interface, state, or failure-unit pressure. Ordinary bugs, failed tests, or finding count do not prove bad design.
 
@@ -23,20 +23,16 @@ Do not force this lens onto a local change whose interface remains sound. Do not
 
 ## Start With Outcome And Failure
 
-Before choosing classes, services, states, or adapters, ask:
+Before choosing classes, services, states, or adapters, establish:
 
-- What complete outcome should the caller request?
-- Which decisions genuinely belong to the caller?
-- Which ordering, policy, storage, retry, cleanup, or provider details can the module own?
-- What counts as complete and visible success?
-- If it fails, who observes it, what state or evidence is written, and what must never happen?
-- Does failure stop, fail closed, fail open, degrade, retry, escalate, or require recovery?
-- What is safe to restart, and what evidence establishes recovery?
-- Which likely-changing decision should remain local?
+- the complete outcome callers need and the decisions they genuinely own;
+- the coordination or likely-changing policy the module can hide;
+- visible success and the **failure unit**—the smallest outcome treated as one success, failure, and recovery boundary;
+- failure observers, state or evidence written, forbidden partial outcomes, response policy (stop, fail closed/open, degrade, retry, or escalate), safe restart, recovery, and required proof.
 
-The answers form the **failure contract**: failure modes, observers, written state, forbidden outcomes, retry or degradation behavior, recovery, and proof. The **failure unit** is the smallest outcome treated as one success, failure, and recovery boundary. Failure behavior is part of the interface even when its mechanism remains private.
+These form the **failure contract**. Failure behavior is part of the interface even when its mechanism remains private.
 
-When these answers change product behavior, public interfaces, compatibility, permissions, security, privacy, billing, data loss, migration direction, or another user-owned outcome, use [Decision Gate](../decision-gate/SKILL.md). This lens surfaces the decision; it does not make it silently.
+When the boundary changes product behavior, public interfaces, compatibility, permissions, security, privacy, billing, data loss, migration direction, or another user-owned outcome, use [Decision Gate](../decision-gate/SKILL.md). This lens surfaces the decision; it does not make it silently.
 
 ## Hide Coordination
 
@@ -51,38 +47,23 @@ Before exposing a flag, state, path, filename, ordering rule, retry, timing beha
 
 Keep caller-owned outcomes and decisions public. Keep internal sequencing, storage, cleanup, provider mechanics, integrity publication, and optimization private unless correct use requires caller control.
 
-Read [software design philosophy](references/software-design-philosophy.md) when the reason a design is shallow or coordination-heavy is unclear.
+Read [software design philosophy](references/software-design-philosophy.md) when structural pressure is supported but the likely-changing decision or missing information-hiding boundary cannot yet be named.
 
 ## Recognize Structural Pressure
 
-Structural pressure exists when evidence shows that:
+Structural pressure appears when caller knowledge, duplicated policy, lifecycle choreography, test-only exposure, or unowned failure behavior spreads across a boundary, or a bounded outcome requires an unplanned subsystem because no current seam owns it.
 
-- each correction adds caller knowledge, public states, flags, retries, or recovery rules;
-- one policy or behavior requires unrelated edits across callers;
-- callers or tests duplicate lifecycle choreography;
-- tests need many owned internals or production hooks created only for testing;
-- a bounded outcome requires an unplanned subsystem because no current seam can own it;
-- correctness depends on coordinated steps that no module owns.
-
-These signals justify design attention, not automatic refactoring. Read [design pressure signals](references/design-pressure-signals.md) when code, artifacts, tests, or reviews show complexity spreading.
+Read [design pressure signals](references/design-pressure-signals.md) when that evidence may change the next route. The reference owns the detailed classifier and examples; the signals justify design attention, not automatic refactoring.
 
 Diagnose repeated or unexplained failure before redesigning. Direct design work is appropriate when structural pressure is already observable or an important boundary must be chosen before implementation.
 
 ## Shape The Interface
 
-When pressure changes the next action:
-
-1. Name the complete outcome and settled behavior.
-2. Choose the success and failure unit.
-3. Inventory what callers, tests, reviewers, and future agents must know.
-4. Keep caller-owned decisions public and move internal protocol behind the module.
-5. Separate required trust and safety from speculative efficiency, scale, or portability.
-6. For a structural or hard-to-reverse choice, compare materially different ownership or seam placements—not cosmetic variants.
-7. Prefer the design with less caller knowledge, better locality, safer failure behavior, easier correct use, and proportionate evidence cost.
+Before comparing materially different interfaces, read [the interface design loop](references/interface-design-loop.md) when structural pressure or an important pre-implementation correctness boundary makes ownership consequential, especially when authority, canonical state, atomic visibility, replay, cancellation, or post-commit recovery affects correctness.
 
-Read [the interface design loop](references/interface-design-loop.md) when materially different interfaces must be compared, evidence cannot yet choose one, or authority, canonical state, atomic visibility, replay, cancellation, or post-commit recovery affects correctness.
+The reference owns the complete comparison method. Prefer the interface that removes caller knowledge, localizes likely change, makes correct use easy, preserves honest failure and recovery, and costs proportionate evidence.
 
-Do not force multiple designs for an obvious local choice. If source inspection cannot distinguish viable designs, propose one bounded learning slice with a question, competing designs, evidence, cost boundary, and discard-or-promote condition.
+Do not force multiple designs for an obvious local choice. When evidence cannot distinguish viable seams, use the reference's bounded learning route rather than quietly implementing the whole subsystem.
 
 ## Tests And Evidence