u-foo 2.2.4 → 2.3.0

package/src/cli.js

@@ -1,4 +1,5 @@
 const path = require("path");
+const os = require("os");
 const { spawnSync } = require("child_process");
 const net = require("net");
 const fs = require("fs");
@@ -244,6 +245,179 @@ function projectSwitchV1Error() {
   return err;
 }
 
+function parseMemoryTags(value = "") {
+  return String(value || "")
+    .split(",")
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
+function readTextFile(filePath = "") {
+  const target = String(filePath || "").trim();
+  if (!target) return "";
+  return fs.readFileSync(path.resolve(target), "utf8");
+}
+
+function formatMemoryLine(entry = {}) {
+  const tags = Array.isArray(entry.tags) && entry.tags.length
+    ? `[${entry.tags.join(",")}]`
+    : "[]";
+  const status = entry.status && entry.status !== "active" ? ` (${entry.status})` : "";
+  return `${entry.id} ${tags} ${entry.title}${status}`;
+}
+
+function printMemoryEntry(entry = {}, write = (line) => console.log(line)) {
+  write(`${entry.id} ${entry.status || "active"}`);
+  write(`title: ${entry.title || ""}`);
+  write(`tags: ${(entry.tags || []).join(",")}`);
+  write(`source: ${entry.source || ""}`);
+  write(`created_at: ${entry.created_at || ""}`);
+  write(`updated_at: ${entry.updated_at || ""}`);
+  write("");
+  write(entry.body || "");
+}
+
+function runMemoryCommand({
+  subcommand = "list",
+  args = [],
+  opts = {},
+  cwd = process.cwd(),
+  write = (line) => console.log(line),
+  writeError = (line) => console.error(line),
+} = {}) {
+  const MemoryManager = require("./memory");
+  const manager = new MemoryManager(cwd);
+  const sub = String(subcommand || "list").trim().toLowerCase();
+  const outputJson = opts.json === true;
+
+  try {
+    if (sub === "add") {
+      const title = String(args[0] || opts.title || "").trim();
+      const body = opts.bodyFile ? readTextFile(opts.bodyFile) : String(opts.body || "").trim();
+      if (!body) throw new Error("memory add requires --body or --body-file");
+      const entry = manager.add({
+        title,
+        body,
+        tags: parseMemoryTags(opts.tags),
+        source: "user",
+      }, {
+        source: "cli",
+        actor: process.env.UFOO_SUBSCRIBER_ID || process.env.USER || "user",
+      });
+      if (outputJson) write(JSON.stringify(entry, null, 2));
+      else write(formatMemoryLine(entry));
+      return 0;
+    }
+
+    if (sub === "list" || sub === "ls") {
+      const entries = manager.list({
+        tag: opts.tag || "",
+        all: opts.all === true,
+        limit: parseInt(opts.limit, 10) || 0,
+      });
+      if (outputJson) {
+        write(JSON.stringify(entries, null, 2));
+        return 0;
+      }
+      if (entries.length === 0) {
+        write("No memory entries found.");
+        return 0;
+      }
+      entries.forEach((entry) => write(formatMemoryLine(entry)));
+      return 0;
+    }
+
+    if (sub === "show") {
+      const id = String(args[0] || "").trim();
+      if (!id) throw new Error("memory show requires <id>");
+      const entry = manager.get(id, { includeArchived: opts.all === true });
+      if (outputJson) write(JSON.stringify(entry, null, 2));
+      else printMemoryEntry(entry, write);
+      return 0;
+    }
+
+    if (sub === "edit") {
+      const id = String(args[0] || "").trim();
+      if (!id) throw new Error("memory edit requires <id>");
+      const patch = {};
+      if (opts.title) patch.title = opts.title;
+      if (opts.tags !== undefined) patch.tags = parseMemoryTags(opts.tags);
+      if (opts.bodyFile) patch.body = readTextFile(opts.bodyFile);
+      if (opts.body) patch.body = opts.body;
+      if (Object.keys(patch).length === 0) {
+        const entry = manager.get(id);
+        const editor = process.env.EDITOR || "vi";
+        const tmp = path.join(os.tmpdir(), `ufoo-memory-${entry.id}-${Date.now()}.md`);
+        fs.writeFileSync(tmp, `# ${entry.title}\n\n${entry.body || ""}\n`, "utf8");
+        const res = spawnSync(editor, [tmp], { stdio: "inherit" });
+        if (res.error) throw res.error;
+        if (typeof res.status === "number" && res.status !== 0) {
+          throw new Error(`${editor} exited with code ${res.status}`);
+        }
+        const parsed = String(fs.readFileSync(tmp, "utf8"));
+        fs.rmSync(tmp, { force: true });
+        const lines = parsed.replace(/\r\n/g, "\n").split("\n");
+        const first = lines.findIndex((line) => line.trim());
+        if (first !== -1 && /^#\s+/.test(lines[first])) {
+          patch.title = lines[first].replace(/^#\s+/, "").trim();
+          patch.body = lines.slice(first + 1).join("\n").trim();
+        } else {
+          patch.body = parsed.trim();
+        }
+        patch.expected_updated_at = entry.updated_at;
+      }
+      const updated = manager.update(id, patch, {
+        source: "cli",
+        actor: process.env.UFOO_SUBSCRIBER_ID || process.env.USER || "user",
+      });
+      if (outputJson) write(JSON.stringify(updated, null, 2));
+      else write(formatMemoryLine(updated));
+      return 0;
+    }
+
+    if (sub === "forget" || sub === "archive") {
+      const id = String(args[0] || "").trim();
+      if (!id) throw new Error("memory forget requires <id>");
+      const entry = manager.archive(id, {
+        source: "cli",
+        actor: process.env.UFOO_SUBSCRIBER_ID || process.env.USER || "user",
+      });
+      if (outputJson) write(JSON.stringify(entry, null, 2));
+      else write(formatMemoryLine(entry));
+      return 0;
+    }
+
+    if (sub === "rebuild-index") {
+      const entries = manager.rebuildIndex();
+      if (outputJson) write(JSON.stringify({ count: entries.length, index_file: manager.indexFile }, null, 2));
+      else write(`Rebuilt ${manager.indexFile} (${entries.length} active entries)`);
+      return 0;
+    }
+
+    if (sub === "audit") {
+      const rows = manager.readAudit(args[0] || "");
+      if (outputJson) {
+        write(JSON.stringify(rows, null, 2));
+        return 0;
+      }
+      if (rows.length === 0) {
+        write("No memory audit entries found.");
+        return 0;
+      }
+      rows.forEach((row) => {
+        write(`${row.ts || "-"} ${row.action || "-"} ${row.id || ""} ${row.title || ""}`.trim());
+      });
+      return 0;
+    }
+
+    writeError("memory requires add|list|show|edit|forget|rebuild-index|audit subcommand");
+    return 1;
+  } catch (err) {
+    writeError(err.message || String(err));
+    return err.exitCode || 1;
+  }
+}
+
 function runProjectCommand({
   subcommand = "list",
   outputJson = false,
@@ -409,6 +583,108 @@ async function runCli(argv) {
           cwd: process.cwd(),
         });
       });
+
+    const memory = program.command("memory").description("Project shared memory commands");
+    memory
+      .command("add")
+      .description("Add a project memory entry")
+      .argument("<title>", "Memory title")
+      .option("--body <text>", "Memory body")
+      .option("--body-file <path>", "Read memory body from file")
+      .option("--tags <tags>", "Comma-separated tags")
+      .option("--json", "Output as JSON")
+      .action((title, opts) => {
+        process.exitCode = runMemoryCommand({
+          subcommand: "add",
+          args: [title],
+          opts,
+          cwd: process.cwd(),
+        });
+      });
+    memory
+      .command("list")
+      .alias("ls")
+      .description("List project memory entries")
+      .option("--tag <tag>", "Filter by tag")
+      .option("--all", "Include archived entries")
+      .option("--limit <n>", "Limit result count")
+      .option("--json", "Output as JSON")
+      .action((opts) => {
+        process.exitCode = runMemoryCommand({
+          subcommand: "list",
+          opts,
+          cwd: process.cwd(),
+        });
+      });
+    memory
+      .command("show")
+      .description("Show one memory entry")
+      .argument("<id>", "Memory id")
+      .option("--all", "Allow archived entries")
+      .option("--json", "Output as JSON")
+      .action((id, opts) => {
+        process.exitCode = runMemoryCommand({
+          subcommand: "show",
+          args: [id],
+          opts,
+          cwd: process.cwd(),
+        });
+      });
+    memory
+      .command("edit")
+      .description("Edit one memory entry")
+      .argument("<id>", "Memory id")
+      .option("--title <title>", "Replace title")
+      .option("--body <text>", "Replace body")
+      .option("--body-file <path>", "Replace body from file")
+      .option("--tags <tags>", "Replace tags with comma-separated tags")
+      .option("--json", "Output as JSON")
+      .action((id, opts) => {
+        process.exitCode = runMemoryCommand({
+          subcommand: "edit",
+          args: [id],
+          opts,
+          cwd: process.cwd(),
+        });
+      });
+    memory
+      .command("forget")
+      .description("Archive one memory entry")
+      .argument("<id>", "Memory id")
+      .option("--json", "Output as JSON")
+      .action((id, opts) => {
+        process.exitCode = runMemoryCommand({
+          subcommand: "forget",
+          args: [id],
+          opts,
+          cwd: process.cwd(),
+        });
+      });
+    memory
+      .command("rebuild-index")
+      .description("Rebuild memory INDEX.md")
+      .option("--json", "Output as JSON")
+      .action((opts) => {
+        process.exitCode = runMemoryCommand({
+          subcommand: "rebuild-index",
+          opts,
+          cwd: process.cwd(),
+        });
+      });
+    memory
+      .command("audit")
+      .description("Show memory audit log")
+      .argument("[id]", "Optional memory id")
+      .option("--json", "Output as JSON")
+      .action((id, opts) => {
+        process.exitCode = runMemoryCommand({
+          subcommand: "audit",
+          args: id ? [id] : [],
+          opts,
+          cwd: process.cwd(),
+        });
+      });
+
     program
       .command("launch")
       .description("Launch an agent (ucode, uclaude, ucodex)")
@@ -1705,6 +1981,39 @@ async function runCli(argv) {
     }
     return;
   }
+  if (cmd === "memory") {
+    const sub = rest[0] || "list";
+    const args = rest.slice(1).filter((token, index, array) => {
+      const prev = array[index - 1] || "";
+      if (prev === "--body" || prev === "--body-file" || prev === "--tags" || prev === "--tag" || prev === "--limit" || prev === "--title") {
+        return false;
+      }
+      return !token.startsWith("--");
+    });
+    const getOpt = (name, fallback = "") => {
+      const idx = rest.indexOf(name);
+      if (idx === -1 || idx + 1 >= rest.length) return fallback;
+      const value = rest[idx + 1];
+      if (!value || value.startsWith("--")) return fallback;
+      return value;
+    };
+    process.exitCode = runMemoryCommand({
+      subcommand: sub,
+      args,
+      opts: {
+        title: getOpt("--title", ""),
+        body: getOpt("--body", ""),
+        bodyFile: getOpt("--body-file", ""),
+        tags: getOpt("--tags", ""),
+        tag: getOpt("--tag", ""),
+        limit: getOpt("--limit", ""),
+        all: rest.includes("--all"),
+        json: rest.includes("--json"),
+      },
+      cwd: process.cwd(),
+    });
+    return;
+  }
   if (cmd === "init") {
     const UfooInit = require("./init");
     const init = new UfooInit(repoRoot);

package/src/code/UCODE_PROMPT.md

@@ -13,9 +13,10 @@ Operational constraints:
 
 ufoo integration requirements:
 - Participate in multi-agent coordination through ufoo bus/context.
-- Respect shared context decisions and append meaningful decisions when needed.
+- Respect shared context decisions. The default is no new decision; only append one for important, plan-level choices that constrain future work, and keep durable project facts out of decisions.
+- Use shared memory for durable project facts. Read existing memory before writing new memory; do not use it for transient task state.
 - Support launch/close/resume/inject flows managed by ufoo daemon.
-- Prefer canonical ufoo commands (`ufoo ctx`, `ufoo bus`, `ufoo report`) for coordination and status sync.
+- Prefer canonical ufoo commands (`ufoo ctx`, `ufoo bus`, `ufoo memory`, `ufoo report`) for coordination and status sync.
 
 Execution protocol:
 - On session start, check context quickly:

package/src/code/prompts/ufoo.js

@@ -4,9 +4,10 @@ function getUfooIntegrationSection() {
   return `# ufoo integration
 
 Participate in multi-agent coordination through the ufoo bus/context system:
-- Respect shared context decisions and append meaningful decisions when needed.
+- Respect shared context decisions. The default is no new decision; only append one for important, plan-level choices that constrain future work, and keep durable project facts out of decisions.
+- Use shared memory for durable project facts. Read existing memory before writing new memory; do not use it for transient task state.
 - Support launch/close/resume/inject flows managed by ufoo daemon.
-- Prefer canonical ufoo commands (\`ufoo ctx\`, \`ufoo bus\`, \`ufoo report\`) for coordination and status sync.
+- Prefer canonical ufoo commands (\`ufoo ctx\`, \`ufoo bus\`, \`ufoo memory\`, \`ufoo report\`) for coordination and status sync.
 
 Execution protocol:
 - On session start, check context quickly:

package/src/config.js

@@ -8,8 +8,9 @@ const DEFAULT_CONFIG = {
   launchMode: "auto",
   agentProvider: "codex-cli",
   controllerMode: "main",
-  codexInternalThreadMode: "legacy",
+  codexInternalThreadMode: "api",
   codexAuthPath: "",
+  codexOauthRefreshWindowSec: 300,
   claudeOauthProfile: "",
   claudeOauthTokenPath: "",
   claudeOauthRefreshWindowSec: 300,
@@ -50,7 +51,8 @@ function normalizeControllerMode(value) {
 
 function normalizeCodexInternalThreadMode(value) {
   const raw = String(value || "").trim().toLowerCase();
-  if (raw === "sdk") return "sdk";
+  if (raw === "api" || raw === "direct" || raw === "direct-api" || raw === "upstream") return "api";
+  if (raw === "sdk") return "api";
   return "legacy";
 }
 
@@ -58,6 +60,12 @@ function normalizeCodexAuthPath(value) {
   return typeof value === "string" ? value.trim() : "";
 }
 
+function normalizeCodexOauthRefreshWindowSec(value) {
+  const num = Number(value);
+  if (!Number.isFinite(num) || num < 0) return 300;
+  return Math.floor(num);
+}
+
 function normalizeClaudeOauthProfile(value) {
   return typeof value === "string" ? value.trim() : "";
 }
@@ -99,8 +107,11 @@ function loadConfig(projectRoot) {
       controllerMode: Object.prototype.hasOwnProperty.call(raw, "controllerMode")
         ? normalizeControllerMode(raw.controllerMode)
         : DEFAULT_CONFIG.controllerMode,
-      codexInternalThreadMode: normalizeCodexInternalThreadMode(raw.codexInternalThreadMode),
+      codexInternalThreadMode: Object.prototype.hasOwnProperty.call(raw, "codexInternalThreadMode")
+        ? normalizeCodexInternalThreadMode(raw.codexInternalThreadMode)
+        : DEFAULT_CONFIG.codexInternalThreadMode,
       codexAuthPath: normalizeCodexAuthPath(raw.codexAuthPath),
+      codexOauthRefreshWindowSec: normalizeCodexOauthRefreshWindowSec(raw.codexOauthRefreshWindowSec),
       claudeOauthProfile: normalizeClaudeOauthProfile(raw.claudeOauthProfile),
       claudeOauthTokenPath: normalizeClaudeOauthTokenPath(raw.claudeOauthTokenPath),
       claudeOauthRefreshWindowSec: normalizeClaudeOauthRefreshWindowSec(raw.claudeOauthRefreshWindowSec),
@@ -143,6 +154,7 @@ function saveConfig(projectRoot, config) {
   merged.controllerMode = normalizeControllerMode(merged.controllerMode);
   merged.codexInternalThreadMode = normalizeCodexInternalThreadMode(merged.codexInternalThreadMode);
   merged.codexAuthPath = normalizeCodexAuthPath(merged.codexAuthPath);
+  merged.codexOauthRefreshWindowSec = normalizeCodexOauthRefreshWindowSec(merged.codexOauthRefreshWindowSec);
   merged.claudeOauthProfile = normalizeClaudeOauthProfile(merged.claudeOauthProfile);
   merged.claudeOauthTokenPath = normalizeClaudeOauthTokenPath(merged.claudeOauthTokenPath);
   merged.claudeOauthRefreshWindowSec = normalizeClaudeOauthRefreshWindowSec(merged.claudeOauthRefreshWindowSec);
@@ -186,6 +198,7 @@ module.exports = {
   normalizeControllerMode,
   normalizeCodexInternalThreadMode,
   normalizeCodexAuthPath,
+  normalizeCodexOauthRefreshWindowSec,
   normalizeClaudeOauthProfile,
   normalizeClaudeOauthTokenPath,
   normalizeClaudeOauthRefreshWindowSec,

package/src/context/doctor.js

@@ -113,7 +113,7 @@ class ContextDoctor {
 
     console.log("=== context doctor ===");
     console.log(
-      "Reminder: If you provide evaluation/recommendation/plan, write a decision before replying."
+      "Reminder: default to no new decision; only record important, plan-level choices that constrain future work."
     );
     console.log("");
 

package/src/daemon/groupOrchestrator.js

@@ -73,6 +73,12 @@ function buildRuntimeNickname(projectPrefix, nickname) {
   return `${prefix}-${logicalName}`;
 }
 
+function resolveMemberScopedNickname(member = {}) {
+  return asTrimmedString(member.scoped_nickname)
+    || asTrimmedString(member.runtime_nickname)
+    || asTrimmedString(member.nickname);
+}
+
 function buildLaunchPlan(templateDoc = {}) {
   const agents = Array.isArray(templateDoc.agents) ? templateDoc.agents : [];
   const remaining = new Map();
@@ -325,7 +331,6 @@ function buildExecutionPlan({
     const runtimeNickname = buildRuntimeNickname(projectNicknamePrefix, item.nickname);
     return {
       nickname: item.nickname,
-      runtime_nickname: runtimeNickname,
       requested_type: item.requested_type || item.type,
       type: resolvedType,
       role: item.role,
@@ -401,7 +406,7 @@ function buildExecutionPlan({
       ...item,
       requested_type: item.requested_type || item.type,
       type: resolvedType,
-      runtime_nickname: runtimeNickname,
+      scoped_nickname: runtimeNickname,
       resolved_profile: profile ? profile.resolved_profile : "",
       display_name: profile ? profile.display_name : "",
       short_name: profile ? profile.short_name : "",
@@ -459,7 +464,7 @@ function buildDefaultRuntime({
       index: idx,
       template_agent_id: item.id || "",
       nickname: item.nickname,
-      runtime_nickname: item.runtime_nickname || "",
+      scoped_nickname: item.scoped_nickname || item.runtime_nickname || "",
       requested_type: item.requested_type || item.type,
       type: item.type,
       role: item.role || "",
@@ -795,7 +800,7 @@ function createGroupOrchestrator(options = {}) {
         roster_version: compiled.rosterVersion,
         members: compiled.executionPlan.map((item) => ({
           nickname: item.nickname,
-          runtime_nickname: item.runtime_nickname,
+          scoped_nickname: item.scoped_nickname,
           type: item.type,
           role: item.role,
           startup_order: item.startup_order,
@@ -915,7 +920,7 @@ function createGroupOrchestrator(options = {}) {
         action: "launch",
         agent: item.type,
         count: 1,
-        nickname: item.runtime_nickname,
+        nickname: item.scoped_nickname || item.runtime_nickname,
         require_activity_monitor: true,
         tmux_layout_context: tmuxLayoutContext,
         ...launchHostContext,
@@ -948,7 +953,7 @@ function createGroupOrchestrator(options = {}) {
       }
 
       const reused = Boolean(launchResult.skipped);
-      const subscriberId = pickLaunchSubscriber(projectRoot, launchResult, item.runtime_nickname);
+      const subscriberId = pickLaunchSubscriber(projectRoot, launchResult, item.scoped_nickname || item.runtime_nickname);
       member.status = reused ? "reused" : "active";
       member.managed = !reused;
       member.subscriber_id = subscriberId || "";
@@ -960,7 +965,7 @@ function createGroupOrchestrator(options = {}) {
       if (!reused) {
         rollbackTargets.push({
           memberIndex: i,
-          target: subscriberId || item.runtime_nickname,
+          target: subscriberId || item.scoped_nickname || item.runtime_nickname,
         });
       } else if (!canReuseBootstrappedMember(member, item, subscriberId)) {
         const priorBootstrap = findAppliedBootstrapRecord(
@@ -1124,8 +1129,7 @@ function createGroupOrchestrator(options = {}) {
       if (!member || member.managed === false) continue;
       if (member.status !== "active") continue;
       const target = asTrimmedString(member.subscriber_id)
-        || asTrimmedString(member.runtime_nickname)
-        || asTrimmedString(member.nickname);
+        || resolveMemberScopedNickname(member);
       if (!target) continue;
       activeMembers.push({ index: i, target });
     }

package/src/daemon/promptRequest.js

@@ -212,15 +212,16 @@ async function handlePromptRequest(options = {}) {
 
   const privateReports = listControllerInboxEntries(projectRoot, "ufoo-agent", { num: 100 });
   const useGlobalProjectRouter = isGlobalController;
-  const promptRunner = runPromptWithAssistant;
   const ufooAgentOptions = useGlobalProjectRouter ? { routingMode: "global-router" } : { controllerMode };
   let nextRequestMeta = requestMeta;
-  if (!Object.prototype.hasOwnProperty.call(nextRequestMeta, "agent_execution_path") && controllerMode !== CONTROLLER_MODES.LEGACY) {
+  const hasExplicitRequestMeta = Object.keys(nextRequestMeta).length > 0;
+  if (hasExplicitRequestMeta && !Object.prototype.hasOwnProperty.call(nextRequestMeta, "agent_execution_path") && controllerMode !== CONTROLLER_MODES.LEGACY) {
     nextRequestMeta = {
       ...nextRequestMeta,
       agent_execution_path: controllerMode,
     };
   }
+  let forceMainRouterFallback = false;
 
   const logGateRouterEvent = (event, details = {}) => {
     controllerObserver.emit(event, details);
@@ -275,6 +276,7 @@ async function handlePromptRequest(options = {}) {
       attachGateRouterMeta("provider_error", {
         error: routed && routed.error ? routed.error : "route_agent_failed",
       });
+      forceMainRouterFallback = true;
       logGateRouterEvent("controller.gate_router_upgraded", {
         reason: "provider_error",
         fallback_used: "main_router",
@@ -295,6 +297,7 @@ async function handlePromptRequest(options = {}) {
           confidence: Number(route.confidence || 0),
           route_reason: route.reason || "",
         });
+        forceMainRouterFallback = true;
         logGateRouterEvent("controller.gate_router_upgraded", {
           reason: upgradeReason,
           decision: route.decision || "",
@@ -339,6 +342,7 @@ async function handlePromptRequest(options = {}) {
             route_reason: route.reason || "",
             error: err && err.message ? err.message : String(err),
           });
+          forceMainRouterFallback = true;
           logGateRouterEvent("controller.gate_router_upgraded", {
             reason: "dispatch_failed",
             target: route.target,
@@ -351,6 +355,11 @@ async function handlePromptRequest(options = {}) {
   }
 
   const promptText = buildPromptWithPrivateReports(req.text || "", privateReports, nextRequestMeta);
+  const promptRunner = loopRuntime.enabled
+    && !forceMainRouterFallback
+    && typeof injectedLoopRunner === "function"
+    ? injectedLoopRunner
+    : runPromptWithAssistant;
 
   try {
     const handled = await promptRunner({

package/src/daemon/soloBootstrap.js

@@ -253,6 +253,8 @@ function findOwningGroup(projectRoot, subscriberId = "") {
         && (
           !liveNickname
           || asTrimmedString(member.nickname) === liveNickname
+          || asTrimmedString(member.scoped_nickname) === liveNickname
+          || asTrimmedString(member.scoped_nickname) === liveScopedNickname
           || asTrimmedString(member.runtime_nickname) === liveNickname
           || asTrimmedString(member.runtime_nickname) === liveScopedNickname
         )

package/src/group/bootstrap.js

@@ -5,7 +5,7 @@ const crypto = require("crypto");
 const SHARED_UFOO_PROTOCOL = [
   "ufoo protocol:",
   "- At session start, sync shared context with `ufoo ctx decisions -l` and `ufoo ctx decisions -n 1`.",
-  "- Record a decision ONLY for important, plan-level knowledge: architectural choices, multi-option trade-off analysis, cross-agent coordination decisions, or plans that affect other agents. Do NOT record routine findings, simple bug fixes, or trivial observations. Use `ufoo ctx decisions new \"Title\"` BEFORE acting.",
+  "- Default to no new decision. Record one ONLY for important, plan-level knowledge: architectural choices, multi-option trade-off analysis, cross-agent coordination decisions, or plans that affect other agents. Do NOT record routine findings, simple bug fixes, trivial observations, or generic plan/evaluation/recommendation requests. Durable project facts belong in shared memory, not decisions. Use `ufoo ctx decisions new \"Title\"` BEFORE acting only when that bar is met.",
   "- Use `ufoo bus send <target-nickname> \"<message>\"` for agent-to-agent handoffs.",
   "- If you receive pending bus work, execute it immediately, reply to the sender, then `ufoo bus ack \"$UFOO_SUBSCRIBER_ID\"`.",
   "- Use `ufoo report` for controller/runtime status updates, not as a substitute for direct handoffs.",