jeo-code 0.6.11 → 0.6.13

package/CHANGELOG.md

@@ -6,6 +6,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 The README mirrors the latest 5 entries — regenerate with `bun run changelog:sync`.
 
+## [0.6.13] - 2026-06-16
+_`team` engine: concrete uncommitted-work reporting and stricter empty-run handling._
+
+### Changed
+- **`team` re-runs report concrete uncommitted work.** Instead of a speculative warning, the engine now probes the working tree with `git status --porcelain` and reports the actual uncommitted-file count, so you know whether real partial work is present before re-running on it.
+- **`--strict-mutations` fails a no-op mutating run.** A mutating role that performed no write/edit/bash is now a hard failure (`stream:error`) rather than silently passing; a bash-only run stays an advisory `stream:warn` (new tone) so a passing advisory doesn't masquerade as an error.
+
+## [0.6.12] - 2026-06-16
+_OKF-backed memory distillation — session learnings become structured concept files._
+
+### Added
+- **OKF-backed memory distillation (OKF Sprint 02).** Session distillation now emits structured OKF v0.1 concept files — each with `type` / `title` / `description` / `body` / `tags` / `confidence` / `links` — filed into typed directories (unknown types fall back to `facts/`), deduped by title, merged with the existing concept bundle, then indexed and logged. The distiller prompts the model for a `{ concepts: [...] }` payload and parses it leniently (`tryExtractJsonObject`) so text-only providers still land. Builds on the 0.6.10 OKF format layer.
+
 ## [0.6.11] - 2026-06-16
 _Larger reasoning budgets, and terminal capability-response sequences kept out of the prompt._
 

package/README.ja.md

@@ -158,11 +158,11 @@ CI は `.github/workflows/npm-publish.yml` で公開します — GitHub リリ
 ## 変更履歴 (Changelog)
 
 <!-- CHANGELOG:START (auto-generated from CHANGELOG.md — run `bun run changelog:sync`) -->
+- **[0.6.13]** (2026-06-16) — `team` engine: concrete uncommitted-work reporting and stricter empty-run handling.
+- **[0.6.12]** (2026-06-16) — OKF-backed memory distillation — session learnings become structured concept files.
 - **[0.6.11]** (2026-06-16) — Larger reasoning budgets, and terminal capability-response sequences kept out of the prompt.
 - **[0.6.10]** (2026-06-16) — OKF memory-format foundation and a hardened bashTool subprocess drain.
 - **[0.6.9]** (2026-06-16) — Live streaming blocks size to their content and the viewport instead of a fixed rectangle.
-- **[0.6.8]** (2026-06-16) — OAuth loopback callback host pinned to `localhost` to match provider-registered redirect URIs.
-- **[0.6.7]** (2026-06-16) — Mouse-report input corruption fixed under `jeo --tmux`, and a full-width TUI at one consistent width.
 
 See [CHANGELOG.md](CHANGELOG.md) for the full history.
 <!-- CHANGELOG:END -->

package/README.ko.md

@@ -158,11 +158,11 @@ CI는 `.github/workflows/npm-publish.yml`로 배포합니다 — GitHub 릴리
 ## 변경 이력 (Changelog)
 
 <!-- CHANGELOG:START (auto-generated from CHANGELOG.md — run `bun run changelog:sync`) -->
+- **[0.6.13]** (2026-06-16) — `team` engine: concrete uncommitted-work reporting and stricter empty-run handling.
+- **[0.6.12]** (2026-06-16) — OKF-backed memory distillation — session learnings become structured concept files.
 - **[0.6.11]** (2026-06-16) — Larger reasoning budgets, and terminal capability-response sequences kept out of the prompt.
 - **[0.6.10]** (2026-06-16) — OKF memory-format foundation and a hardened bashTool subprocess drain.
 - **[0.6.9]** (2026-06-16) — Live streaming blocks size to their content and the viewport instead of a fixed rectangle.
-- **[0.6.8]** (2026-06-16) — OAuth loopback callback host pinned to `localhost` to match provider-registered redirect URIs.
-- **[0.6.7]** (2026-06-16) — Mouse-report input corruption fixed under `jeo --tmux`, and a full-width TUI at one consistent width.
 
 See [CHANGELOG.md](CHANGELOG.md) for the full history.
 <!-- CHANGELOG:END -->

package/README.md

@@ -158,11 +158,11 @@ Required npm token permissions (repository secret `NPM_TOKEN`):
 ## Changelog
 
 <!-- CHANGELOG:START (auto-generated from CHANGELOG.md — run `bun run changelog:sync`) -->
+- **[0.6.13]** (2026-06-16) — `team` engine: concrete uncommitted-work reporting and stricter empty-run handling.
+- **[0.6.12]** (2026-06-16) — OKF-backed memory distillation — session learnings become structured concept files.
 - **[0.6.11]** (2026-06-16) — Larger reasoning budgets, and terminal capability-response sequences kept out of the prompt.
 - **[0.6.10]** (2026-06-16) — OKF memory-format foundation and a hardened bashTool subprocess drain.
 - **[0.6.9]** (2026-06-16) — Live streaming blocks size to their content and the viewport instead of a fixed rectangle.
-- **[0.6.8]** (2026-06-16) — OAuth loopback callback host pinned to `localhost` to match provider-registered redirect URIs.
-- **[0.6.7]** (2026-06-16) — Mouse-report input corruption fixed under `jeo --tmux`, and a full-width TUI at one consistent width.
 
 See [CHANGELOG.md](CHANGELOG.md) for the full history.
 <!-- CHANGELOG:END -->

package/README.zh.md

@@ -158,11 +158,11 @@ CI 通过 `.github/workflows/npm-publish.yml` 发布 — GitHub 发布 release
 ## 更新日志 (Changelog)
 
 <!-- CHANGELOG:START (auto-generated from CHANGELOG.md — run `bun run changelog:sync`) -->
+- **[0.6.13]** (2026-06-16) — `team` engine: concrete uncommitted-work reporting and stricter empty-run handling.
+- **[0.6.12]** (2026-06-16) — OKF-backed memory distillation — session learnings become structured concept files.
 - **[0.6.11]** (2026-06-16) — Larger reasoning budgets, and terminal capability-response sequences kept out of the prompt.
 - **[0.6.10]** (2026-06-16) — OKF memory-format foundation and a hardened bashTool subprocess drain.
 - **[0.6.9]** (2026-06-16) — Live streaming blocks size to their content and the viewport instead of a fixed rectangle.
-- **[0.6.8]** (2026-06-16) — OAuth loopback callback host pinned to `localhost` to match provider-registered redirect URIs.
-- **[0.6.7]** (2026-06-16) — Mouse-report input corruption fixed under `jeo --tmux`, and a full-width TUI at one consistent width.
 
 See [CHANGELOG.md](CHANGELOG.md) for the full history.
 <!-- CHANGELOG:END -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jeo-code",
-  "version": "0.6.11",
+  "version": "0.6.13",
   "description": "Clean, highly optimized AI coding agent using spec-first loop",
   "type": "module",
   "main": "src/cli.ts",

package/src/agent/memory.ts

@@ -13,6 +13,8 @@ import { spawn as nodeSpawn } from "node:child_process";
 import * as path from "node:path";
 import { callLlm, type Message } from "./loop";
 import { jeoEnv } from "../util/env";
+import { parseConcept, serializeConcept, slugify, isReservedFile } from "./memory-okf";
+import { tryExtractJsonObject } from "./json";
 
 /** On-disk document cap — the distill prompt instructs the model to stay under it. */
 export const MEMORY_MAX_CHARS = 6_000;
@@ -22,6 +24,16 @@ export const MEMORY_INJECT_MAX_CHARS = 3_000;
 const TRANSCRIPT_MAX_CHARS = 12_000;
 /** A session shorter than this has nothing durable to learn. */
 const MIN_HISTORY_MESSAGES = 4;
+/** Single source of truth for the four jeo concept types the distiller files:
+ *  type → on-disk subdir → index.md section header, in display order. Add a
+ *  row here (one place) to introduce a new filed/rendered type. */
+const TYPE_LAYOUT = [
+  { type: "RepoFact", dir: "facts", header: "Repo Facts" },
+  { type: "Command", dir: "commands", header: "Commands" },
+  { type: "Gotcha", dir: "gotchas", header: "Gotchas" },
+  { type: "UserPreference", dir: "preferences", header: "User Preferences" },
+] as const;
+const DIR_BY_TYPE: Record<string, string> = Object.fromEntries(TYPE_LAYOUT.map(t => [t.type, t.dir]));
 
 export function memoryFilePath(cwd: string): string {
   return path.join(cwd, ".jeo", "memory", "MEMORY.md");
@@ -83,6 +95,135 @@ export interface DistillResult {
  * Best-effort by design: any failure is reported in the result, never thrown —
  * a memory write must not be able to break session exit.
  */
+
+async function findMarkdownFiles(dir: string): Promise<string[]> {
+  const files: string[] = [];
+  async function recurse(currentDir: string) {
+    let entries;
+    try {
+      entries = await fs.readdir(currentDir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const fullPath = path.join(currentDir, entry.name);
+      if (entry.isDirectory()) {
+        if (entry.name === "raw") continue;
+        await recurse(fullPath);
+      } else if (entry.isFile() && entry.name.endsWith(".md")) {
+        files.push(fullPath);
+      }
+    }
+  }
+  await recurse(dir);
+  return files;
+}
+
+async function rebuildIndex(bundleDir: string): Promise<void> {
+  const files = await findMarkdownFiles(bundleDir);
+  const concepts: { type: string; title: string; relPath: string }[] = [];
+  for (const file of files) {
+    const relPath = path.relative(bundleDir, file);
+    if (isReservedFile(relPath)) continue;
+    try {
+      const content = await fs.readFile(file, "utf-8");
+      const parsed = parseConcept(content);
+      concepts.push({
+        type: (parsed.frontmatter.type as string) || "RepoFact",
+        title: (parsed.frontmatter.title as string) || path.basename(file, ".md"),
+        relPath,
+      });
+    } catch {
+      // ignore
+    }
+  }
+
+  let body = "# Index\n\n";
+  for (const { type, header } of TYPE_LAYOUT) {
+    const list = concepts.filter(c => c.type === type);
+    if (list.length === 0) continue;
+    body += `## ${header}\n`;
+    for (const c of list) {
+      body += `- [${c.title}](/${c.relPath.replace(/\\/g, "/")})\n`;
+    }
+    body += "\n";
+  }
+
+  const indexContent = serializeConcept({ okf_version: "0.1" }, body.trim());
+  const indexPath = path.join(bundleDir, "index.md");
+  const tmpPath = `${indexPath}.tmp-${process.pid}`;
+  await fs.writeFile(tmpPath, indexContent, "utf-8");
+  await fs.rename(tmpPath, indexPath);
+}
+
+async function updateLog(bundleDir: string, updatedConcepts: { title: string; type: string }[]): Promise<void> {
+  const logPath = path.join(bundleDir, "log.md");
+  let existingContent = "";
+  try {
+    existingContent = await fs.readFile(logPath, "utf-8");
+  } catch {
+    existingContent = "# Directory Update Log\n";
+  }
+
+  const today = new Date().toISOString().split("T")[0];
+  const heading = `## ${today}`;
+
+  let entry = "";
+  for (const c of updatedConcepts) {
+    entry += `* **${c.type}**: ${c.title}\n`;
+  }
+  if (!entry) return;
+
+  let newContent = "";
+  if (existingContent.includes(heading)) {
+    const lines = existingContent.split("\n");
+    const idx = lines.findIndex(l => l.trim() === heading);
+    lines.splice(idx + 1, 0, entry.trim());
+    newContent = lines.join("\n");
+  } else {
+    const lines = existingContent.split("\n");
+    let insertIdx = 0;
+    if (lines[0]?.startsWith("# ")) {
+      insertIdx = 1;
+      while (insertIdx < lines.length && lines[insertIdx].trim() === "") {
+        insertIdx++;
+      }
+    }
+    lines.splice(insertIdx, 0, `${heading}\n${entry}`);
+    newContent = lines.join("\n");
+  }
+
+  const tmpPath = `${logPath}.tmp-${process.pid}`;
+  await fs.writeFile(tmpPath, newContent, "utf-8");
+  await fs.rename(tmpPath, logPath);
+}
+
+export async function saveRawPayload(bundleDir: string, payload: any): Promise<void> {
+  const rawDir = path.join(bundleDir, "raw");
+  await fs.mkdir(rawDir, { recursive: true });
+  const filename = `session-${Date.now()}-${process.pid}.json`;
+  const filePath = path.join(rawDir, filename);
+  await fs.writeFile(filePath, JSON.stringify(payload, null, 2), "utf-8");
+}
+
+async function cleanupStalePendingFiles(dir: string): Promise<void> {
+  try {
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    const now = Date.now();
+    for (const entry of entries) {
+      if (entry.isFile() && entry.name.startsWith("pending-distill-") && entry.name.endsWith(".json")) {
+        const filePath = path.join(dir, entry.name);
+        const stat = await fs.stat(filePath);
+        if (now - stat.mtimeMs > 24 * 60 * 60 * 1000) {
+          await fs.unlink(filePath).catch(() => {});
+        }
+      }
+    }
+  } catch {
+    // ignore
+  }
+}
+
 export async function distillSessionMemory(
   history: Message[],
   cwd: string,
@@ -92,44 +233,154 @@ export async function distillSessionMemory(
   const body = history.filter(m => m.role !== "system");
   if (body.length < MIN_HISTORY_MESSAGES) return { updated: false, skipped: "session too short" };
   try {
-    const existing = await loadMemory(cwd);
+    const bundleDir = path.join(cwd, ".jeo", "memory");
+    const existingConcepts: any[] = [];
+    try {
+      const files = await findMarkdownFiles(bundleDir);
+      for (const file of files) {
+        const relPath = path.relative(bundleDir, file);
+        if (isReservedFile(relPath)) continue;
+        try {
+          const content = await fs.readFile(file, "utf-8");
+          const parsed = parseConcept(content);
+          existingConcepts.push({
+            type: parsed.frontmatter.type,
+            title: parsed.frontmatter.title || "",
+            description: parsed.frontmatter.description,
+            body: parsed.body,
+            tags: parsed.frontmatter.tags,
+            confidence: parsed.frontmatter.confidence,
+            links: parsed.frontmatter.links,
+            path: relPath,
+          });
+        } catch {}
+      }
+    } catch {}
+
     const prompt: Message[] = [
       {
         role: "system",
         content:
-          "You maintain a compact project memory document for a coding agent. " +
-          "Merge durable learnings from the session transcript into the existing memory. " +
+          "You maintain a compact project memory bundle for a coding agent. " +
+          "Extract durable learnings from the session transcript and merge them with the existing concepts. " +
           "Keep ONLY what helps future sessions in THIS repository: repo facts (structure, conventions, key files), " +
           "commands that work (build/test/run), gotchas (failures and their fixes), and user preferences. " +
           "Drop session-specific noise (one-off tasks, transient errors, conversational detail). " +
-          `Output the FULL updated document as markdown bullets under those four headings, max ${MEMORY_MAX_CHARS} characters. ` +
-          "Output ONLY the document — no preamble, no fences.",
+          "You must output a JSON object with a single key \"concepts\", which is an array of concept objects. " +
+          "Each concept object must have the following fields:\n" +
+          "  - \"type\": one of \"RepoFact\", \"Command\", \"Gotcha\", \"UserPreference\"\n" +
+          "  - \"title\": a short, descriptive title (e.g., \"Bun test runner\")\n" +
+          "  - \"description\": a brief one-line summary of the concept\n" +
+          "  - \"body\": the detailed markdown content/body of the concept\n" +
+          "  - \"tags\": an array of string tags (optional)\n" +
+          "  - \"confidence\": one of \"high\", \"medium\", \"low\" (optional)\n" +
+          "  - \"links\": an array of other concept paths/IDs this concept links to (optional)\n\n" +
+          "Output ONLY the JSON object. Do not include any markdown formatting, preamble, or explanation."
       },
       {
         role: "user",
         content:
-          `Existing memory document:\n${existing || "(empty)"}\n\n` +
-          `Session transcript (tail):\n${transcriptTail(history)}`,
-      },
+          `Existing concepts:\n${JSON.stringify(existingConcepts, null, 2)}\n\n` +
+          `Session transcript (tail):\n${transcriptTail(history)}`
+      }
     ];
+
     const timeoutMs = opts.timeoutMs ?? 20_000;
     const distilled = await Promise.race([
-      callLlm(prompt, { model: opts.model, jsonMode: false, maxTokens: 2_000 }),
+      callLlm(prompt, { model: opts.model, jsonMode: true, maxTokens: 2_000 }),
       new Promise<never>((_, reject) => setTimeout(() => reject(new Error(`memory distill timed out after ${timeoutMs}ms`)), timeoutMs)),
     ]);
-    const doc = distilled.trim().slice(0, MEMORY_MAX_CHARS);
-    if (!doc) return { updated: false, skipped: "model returned an empty document" };
-    const file = memoryFilePath(cwd);
-    await fs.mkdir(path.dirname(file), { recursive: true });
-    const tmp = `${file}.tmp-${process.pid}`;
-    await fs.writeFile(tmp, doc + "\n", "utf-8");
-    await fs.rename(tmp, file); // atomic: a crash mid-write never corrupts the doc
-    return { updated: true };
+
+    // Robust extraction: the distill prompt requests JSON, but text-only providers
+    // (the default antigravity backend) routinely wrap it in prose or  fences.
+    // tryExtractJsonObject recovers the first balanced {...}, tolerating that noise;
+    // a null result means the model gave plain text → old MEMORY.md fallback below.
+    const parsedJson = tryExtractJsonObject<{ concepts?: unknown }>(distilled);
+
+
+    if (parsedJson && Array.isArray(parsedJson.concepts)) {
+      await fs.mkdir(bundleDir, { recursive: true });
+      const updatedConcepts: { title: string; type: string }[] = [];
+
+      for (const concept of parsedJson.concepts) {
+        if (!concept.type || !concept.title) continue;
+        // Unknown types fall back to facts/ (lenient — OKF tolerates extra types).
+        const dir = DIR_BY_TYPE[concept.type] ?? "facts";
+
+        const targetDir = path.join(bundleDir, dir);
+        await fs.mkdir(targetDir, { recursive: true });
+
+        let slug = slugify(concept.title);
+        let relPath = `${dir}/${slug}.md`;
+        let fullPath = path.join(bundleDir, relPath);
+
+        let suffix = 1;
+        while (true) {
+          try {
+            const existingContent = await fs.readFile(fullPath, "utf-8");
+            const parsed = parseConcept(existingContent);
+            const existingTitle = parsed.frontmatter.title || "";
+            if (existingTitle === concept.title) {
+              break;
+            }
+            slug = `${slugify(concept.title)}-${suffix}`;
+            relPath = `${dir}/${slug}.md`;
+            fullPath = path.join(bundleDir, relPath);
+            suffix++;
+          } catch {
+            break;
+          }
+        }
+
+        let existingFm = {};
+        try {
+          const existingContent = await fs.readFile(fullPath, "utf-8");
+          existingFm = parseConcept(existingContent).frontmatter;
+        } catch {}
+
+        const frontmatter = {
+          ...existingFm,
+          type: concept.type,
+          title: concept.title,
+          description: concept.description || "",
+          tags: concept.tags || [],
+          timestamp: new Date().toISOString(),
+          confidence: concept.confidence || "high",
+          last_verified: new Date().toISOString().split("T")[0],
+          links: concept.links || [],
+        };
+
+        const serialized = serializeConcept(frontmatter, concept.body || "");
+        const tmpPath = `${fullPath}.tmp-${process.pid}`;
+        await fs.writeFile(tmpPath, serialized, "utf-8");
+        await fs.rename(tmpPath, fullPath);
+
+        updatedConcepts.push({ title: concept.title, type: concept.type });
+      }
+
+      await rebuildIndex(bundleDir);
+      if (updatedConcepts.length > 0) {
+        await updateLog(bundleDir, updatedConcepts);
+      }
+      await cleanupStalePendingFiles(bundleDir);
+      return { updated: true };
+    } else {
+      const doc = distilled.trim().slice(0, MEMORY_MAX_CHARS);
+      if (!doc) return { updated: false, skipped: "model returned an empty document" };
+      const file = memoryFilePath(cwd);
+      await fs.mkdir(path.dirname(file), { recursive: true });
+      const tmp = `${file}.tmp-${process.pid}`;
+      await fs.writeFile(tmp, doc + "\n", "utf-8");
+      await fs.rename(tmp, file);
+      return { updated: true };
+    }
   } catch (err: any) {
     return { updated: false, skipped: `distill failed: ${err?.message ?? String(err)}` };
   }
 }
 
+
+
 // ── Detached background distillation (round-16) ──
 // The exit-path `await distillSessionMemory(...)` blocked /exit and ^C^C for up
 // to 20s on a final LLM call. Quitting must be INSTANT: the parent now writes a
@@ -189,7 +440,10 @@ export async function runMemoryDistillCommand(args: string[]): Promise<void> {
   const payloadPath = (args[0] ?? "").trim();
   if (!payloadPath) return;
   try {
-    const payload = JSON.parse(await fs.readFile(payloadPath, "utf-8")) as { model?: string; messages?: Message[] };
+    const payloadContent = await fs.readFile(payloadPath, "utf-8");
+    const payload = JSON.parse(payloadContent) as { model?: string; messages?: Message[] };
+    const bundleDir = path.join(process.cwd(), ".jeo", "memory");
+    await saveRawPayload(bundleDir, payload);
     if (Array.isArray(payload.messages)) {
       await distillSessionMemory(payload.messages, process.cwd(), { model: payload.model });
     }
@@ -199,3 +453,4 @@ export async function runMemoryDistillCommand(args: string[]): Promise<void> {
     await fs.unlink(payloadPath).catch(() => {});
   }
 }
+

package/src/cli/runner.ts

@@ -70,9 +70,10 @@ export const COMMANDS: readonly CommandSpec[] = [
   {
     name: "team",
     summary: "Execute the planning blueprint (Executor subagent tools).",
+    usage: "team [--strict-mutations]",
     loader: async () => {
       const m = await import("../commands/team");
-      return async () => m.runTeamCommand();
+      return args => m.runTeamCommand(args);
     },
   },
   {

package/src/commands/team.ts

@@ -11,6 +11,7 @@ import {
 import { runAgentLoop } from "../agent/engine";
 import { maybeCompact } from "../agent/compaction";
 import { catalogMetadata } from "../ai";
+import { gitDirtyCount } from "./launch/tmux";
 import { readGlobalConfig } from "../agent/state";
 import {
   defaultSubagentRole,
@@ -26,7 +27,7 @@ import type { Message } from "../agent/loop";
 import { loadProjectContext, withProjectContext } from "../agent/context-files";
 import { categoryBadge } from "../tui/components/category-index";
 
-export type RalphStreamKind = "step" | "complete" | "error";
+export type RalphStreamKind = "step" | "complete" | "error" | "warn";
 
 export interface RalphRenderOptions {
   color?: boolean;
@@ -55,19 +56,20 @@ export function formatRalphTodoGuide(
   return lines;
 }
 
+const STREAM_TINTS = {
+  complete: chalk.green.bold,
+  error: chalk.red.bold,
+  warn: chalk.yellow.bold,
+  step: chalk.cyan.bold,
+} satisfies Record<RalphStreamKind, (s: string) => string>;
+
 export function formatRalphStreamEvent(kind: RalphStreamKind, message: string, opts: RalphRenderOptions = {}): string {
-  const label = kind === "complete" ? "complete" : kind === "error" ? "error" : "step";
-  if (!opts.color && !opts.indexed) return `  └─ stream:${label} ${message}`;
+  // ponytail: the label is always the kind itself — no mapping table needed.
+  if (!opts.color && !opts.indexed) return `  └─ stream:${kind} ${message}`;
   const color = opts.color === true;
   const badge = `${categoryBadge("subagent", { color })} `;
-  const tint = color
-    ? kind === "complete"
-      ? chalk.green.bold
-      : kind === "error"
-        ? chalk.red.bold
-        : chalk.cyan.bold
-    : (s: string) => s;
-  return `  ${badge}${tint(`stream:${label}`)} ${message}`;
+  const tint = color ? STREAM_TINTS[kind] : (s: string) => s;
+  return `  ${badge}${tint(`stream:${kind}`)} ${message}`;
 }
 
 export interface RalphSubagentPromptContext {
@@ -163,6 +165,9 @@ export interface TeamEngineOptions {
   io?: {
     output?: (line: string) => void;
   };
+  /** When true, a mutating role that finishes WITHOUT any successful
+   *  write/edit/bash fails the task instead of merely warning (round-11). */
+  strictMutations?: boolean;
 }
 
 export async function runTeamEngine(opts: TeamEngineOptions = {}): Promise<{ ok: boolean; reason?: string }> {
@@ -301,12 +306,17 @@ export async function runTeamEngine(opts: TeamEngineOptions = {}): Promise<{ ok:
     }
 
     // Round-8: a previous run halted on a task — its partial edits may still be
-    // on disk. Warn loudly before re-running on top of them, then clear the marker.
+    // on disk. Round-12: instead of a speculative warning, probe the working tree
+    // with `git status --porcelain` and report the CONCRETE uncommitted count so
+    // the user knows whether real partial work is present before re-running on it.
     if (teamState.current_phase === "failed" && teamState.failed_task) {
-      log(
-        `[WARN] The previous run FAILED on "${teamState.failed_task}" and may have left partial edits on disk. ` +
-        `Review the working tree before trusting this re-run — executing the task again on top of partial work can duplicate changes.`,
-      );
+      const dirty = gitDirtyCount(cwd);
+      const treeNote = dirty === undefined
+        ? `The working tree could not be inspected (not a git repo or git unavailable) — review it manually before trusting this re-run.`
+        : dirty > 0
+          ? `git reports ${dirty} uncommitted change(s) — these may include partial edits from the halted task; review (e.g. 'git status', 'git diff') before re-running, as executing the task again on top of partial work can duplicate changes.`
+          : `git reports a clean working tree — no partial edits from the halted task remain on disk, so this re-run starts from a known state.`;
+      log(`[WARN] The previous run FAILED on "${teamState.failed_task}". ${treeNote}`);
       teamState.current_phase = "executing";
       delete teamState.failed_task;
     }
@@ -336,6 +346,7 @@ export async function runTeamEngine(opts: TeamEngineOptions = {}): Promise<{ ok:
         completed: teamState.completed_tasks ?? [],
         cwd,
         roleId: roleByIndex[activeIndex],
+        strictMutations: opts.strictMutations ?? false,
       });
 
       if (opts.signal?.aborted) {
@@ -374,14 +385,15 @@ export async function runTeamEngine(opts: TeamEngineOptions = {}): Promise<{ ok:
   }
 }
 
-export async function runTeamCommand(): Promise<void> {
-  const res = await runTeamEngine();
+export async function runTeamCommand(args: string[] = []): Promise<void> {
+  const strictMutations = args.includes("--strict-mutations") || args.includes("--strict");
+  const res = await runTeamEngine({ strictMutations });
   if (!res.ok) {
     process.exitCode = 1;
   }
 }
 
-async function executeTaskWithAgent(ctx: RalphSubagentPromptContext & { cwd: string; roleId?: string }): Promise<boolean> {
+async function executeTaskWithAgent(ctx: RalphSubagentPromptContext & { cwd: string; roleId?: string; strictMutations?: boolean }): Promise<boolean> {
   const config = await readGlobalConfig();
   const role = getSubagentRole(ctx.roleId, config) ?? defaultSubagentRole();
   const renderOpts: RalphRenderOptions = { color: !!process.stdout.isTTY, indexed: true };
@@ -465,7 +477,16 @@ async function executeTaskWithAgent(ctx: RalphSubagentPromptContext & { cwd: str
     const msg = bashRuns === 0
       ? `${role.title} completed WITHOUT any successful write/edit/bash — treat its changed-files claim as unverified.`
       : `${role.title} completed with only bash (no write/edit) — verify its changed-files claim independently.`;
-    console.log(formatRalphStreamEvent("error", msg, renderOpts));
+    // Round-11: under --strict-mutations, a mutating role that took NO action at
+    // all (no write/edit/bash) is a hard failure — an empty run must not pass as
+    // a completed task. bash-only stays advisory to avoid penalizing shell edits.
+    const hardFail = ctx.strictMutations && bashRuns === 0;
+    // Round-12: separate the tones so a passing advisory run doesn't masquerade
+    // as a stream:error — only a real hard-fail is red; an advisory note is warn.
+    console.log(formatRalphStreamEvent(hardFail ? "error" : "warn", msg, renderOpts));
+    if (hardFail) {
+      return false;
+    }
   }
   console.log(formatRalphStreamEvent("complete", `${role.title} finished task`, renderOpts));
   return true;