@cmetech/otto 1.3.2 → 1.3.3

package/src/resources/extensions/ollama/model-capabilities.ts

@@ -24,11 +24,18 @@ export interface ModelCapability {
  * Keys are matched as prefixes against the model name (before the colon/tag).
  * More specific entries should appear first.
  */
-// Note: ollamaOptions.num_ctx is set for known model families where the context
-// window is authoritative. For unknown/estimated models, num_ctx is NOT sent
-// to avoid OOM risk — Ollama uses its own safe default instead.
+// Note: ollamaOptions.num_ctx is set when the context window has an authoritative
+// source — either a KNOWN_MODELS table entry, or /api/show returning context_length
+// at runtime (ollama-discovery.ts syncs num_ctx with the /api/show value when present).
+// When neither source provides a context window, num_ctx is NOT sent and ollama
+// uses its own safe default to avoid OOM on constrained hosts.
 const KNOWN_MODELS: Array<[pattern: string, caps: ModelCapability]> = [
 	// ─── Reasoning models ───────────────────────────────────────────────
+	// Long-variants listed before the bare `deepseek-v4` base to avoid prefix shadowing.
+	// Same invariant as qwen3-coder / glm / kimi / minimax families.
+	["deepseek-v4-pro",   { contextWindow: 1048576, reasoning: true, ollamaOptions: { num_ctx: 1048576 } }],
+	["deepseek-v4-flash", { contextWindow: 1048576, reasoning: true, ollamaOptions: { num_ctx: 1048576 } }],
+	["deepseek-v4",       { contextWindow: 1048576, reasoning: true, ollamaOptions: { num_ctx: 1048576 } }],
 	["deepseek-r1", { contextWindow: 131072, reasoning: true, ollamaOptions: { num_ctx: 131072 } }],
 	["qwq", { contextWindow: 131072, reasoning: true, ollamaOptions: { num_ctx: 131072 } }],
 
@@ -90,11 +97,15 @@ const KNOWN_MODELS: Array<[pattern: string, caps: ModelCapability]> = [
 
 	// ─── MiniMax M2 (Ollama Cloud) ─────────────────────────────────────
 	// ref: minimax-m2 1M ctx — https://www.minimax.io/news/minimax-m2
-	["minimax-m2.7", { contextWindow: 1048576, maxTokens: 16384, ollamaOptions: { num_ctx: 1048576 } }],
+	// minimax-m2.7:cloud reports 196608 via /api/show despite the M2 announcement
+	// quoting 1M context. Cloud deployment truncates / OOMs at the announced
+	// number; trust the deployed backend.
+	["minimax-m2.7", { contextWindow: 196608, maxTokens: 16384, reasoning: true, ollamaOptions: { num_ctx: 196608 } }],
 	["minimax-m2.5", { contextWindow: 1048576, maxTokens: 16384, ollamaOptions: { num_ctx: 1048576 } }],
 	["minimax-m2", { contextWindow: 1048576, maxTokens: 16384, ollamaOptions: { num_ctx: 1048576 } }],
 
 	// ─── Gemma family ───────────────────────────────────────────────────
+	["gemma4", { contextWindow: 262144, reasoning: true, ollamaOptions: { num_ctx: 262144 } }],
 	["gemma3", { contextWindow: 131072, maxTokens: 16384, ollamaOptions: { num_ctx: 131072 } }],
 	["gemma2", { contextWindow: 8192, maxTokens: 8192, ollamaOptions: { num_ctx: 8192 } }],
 

package/src/resources/extensions/ollama/ollama-discovery.ts

@@ -57,22 +57,28 @@ async function enrichModel(info: OllamaModelInfo, deps: ClientDeps): Promise<Dis
 	const caps = getModelCapabilities(info.name);
 	const parameterSize = info.details?.parameter_size ?? "";
 
-	// /api/tags doesn't include context length; /api/show does via "{arch}.context_length" in model_info.
+	// /api/tags doesn't include context length; /api/show does via "{arch}.context_length"
+	// in model_info. Call /api/show unconditionally so its value can override a stale
+	// KNOWN_MODELS entry — see the priority resolution below.
 	let showContextWindow: number | undefined;
-	if (caps.contextWindow === undefined) {
-		try {
-			const showData = await deps.showModel(info.name);
-			showContextWindow = extractContextFromModelInfo(showData.model_info);
-		} catch (err) {
-			// non-fatal: fall through to estimate
-			if ((process.env.OTTO_DEBUG ?? process.env.OTTO_DEBUG)) console.warn(`[ollama] /api/show failed for ${info.name}:`, err instanceof Error ? err.message : String(err));
-		}
+	try {
+		const showData = await deps.showModel(info.name);
+		showContextWindow = extractContextFromModelInfo(showData.model_info);
+	} catch (err) {
+		// non-fatal: fall through to table/estimate
+		if ((process.env.OTTO_DEBUG ?? process.env.OTTO_DEBUG)) console.warn(`[ollama] /api/show failed for ${info.name}:`, err instanceof Error ? err.message : String(err));
 	}
 
-	// Determine context window: known table > /api/show > estimate from param size > default
+	// Determine context window: /api/show (authoritative ollama metadata) >
+	// known table (fallback for old ollama versions / network failure) >
+	// estimate from parameter size > default. Earlier priority order put
+	// known table first, but the table fell behind reality on several
+	// model families (deepseek-v4-* missing, minimax-m2.7 1048576 vs
+	// real 196608). /api/show is the source of truth when reachable;
+	// the table only fills the gap when it isn't.
 	const contextWindow =
-		caps.contextWindow ??
 		showContextWindow ??
+		caps.contextWindow ??
 		(parameterSize ? estimateContextFromParams(parameterSize) : 8192);
 
 	// Determine max tokens: known table > fraction of context > default
@@ -87,6 +93,16 @@ async function enrichModel(info: OllamaModelInfo, deps: ClientDeps): Promise<Dis
 	// Detect reasoning from known table
 	const reasoning = caps.reasoning ?? false;
 
+	// Sync num_ctx with the authoritative contextWindow. When /api/show
+	// wins, the table's static num_ctx would otherwise be stale and sent
+	// on every chat request — the very drift this priority flip was
+	// designed to eliminate. Keep all other ollamaOptions (num_gpu,
+	// sampling params, keep_alive) from the table.
+	const ollamaOptions =
+		showContextWindow !== undefined
+			? { ...caps.ollamaOptions, num_ctx: showContextWindow }
+			: caps.ollamaOptions;
+
 	return {
 		id: info.name,
 		name: humanizeModelName(info.name),
@@ -97,7 +113,7 @@ async function enrichModel(info: OllamaModelInfo, deps: ClientDeps): Promise<Dis
 		maxTokens,
 		sizeBytes: info.size,
 		parameterSize,
-		ollamaOptions: caps.ollamaOptions,
+		ollamaOptions,
 	};
 }
 

package/src/resources/extensions/ollama/tests/model-capabilities.test.ts

@@ -149,9 +149,8 @@ describe("getModelCapabilities — long-variant overrides aren't shadowed (#4991
 		assert.equal(caps.contextWindow, 262144);
 	});
 
-	it("minimax-m2.5:cloud and minimax-m2.7:cloud report 1M", () => {
+	it("minimax-m2.5:cloud reports 1M", () => {
 		assert.equal(getModelCapabilities("minimax-m2.5:cloud").contextWindow, 1048576);
-		assert.equal(getModelCapabilities("minimax-m2.7:cloud").contextWindow, 1048576);
 	});
 
 	it("minimax-m2 base resolves to 1M", () => {
@@ -256,3 +255,49 @@ describe("formatModelSize", () => {
 		assert.equal(formatModelSize(500_000), "500 KB");
 	});
 });
+
+// ─── deepseek-v4 prefix-shadowing regression ────────────────────────────────
+//
+// deepseek-v4-pro:cloud and deepseek-v4-flash:cloud must be listed before the
+// bare `deepseek-v4` entry in KNOWN_MODELS, otherwise the linear startsWith
+// scan resolves any deepseek-v4-* query to the family base. Same invariant
+// as the qwen3-coder / glm / kimi families already pin elsewhere.
+
+describe("getModelCapabilities — deepseek-v4 long-variants aren't shadowed", () => {
+	it("deepseek-v4-pro:cloud and deepseek-v4-flash:cloud resolve to 1M (long-variants beat deepseek-v4 base)", () => {
+		assert.equal(getModelCapabilities("deepseek-v4-pro:cloud").contextWindow, 1048576);
+		assert.equal(getModelCapabilities("deepseek-v4-flash:cloud").contextWindow, 1048576);
+	});
+
+	it("deepseek-v4 base also resolves to 1M (parity with long-variants)", () => {
+		const caps = getModelCapabilities("deepseek-v4:671b");
+		assert.equal(caps.contextWindow, 1048576);
+	});
+
+	it("ollamaOptions.num_ctx mirrors contextWindow for all deepseek-v4 / gemma4 entries", () => {
+		// Inference time: num_ctx is what gets sent to Ollama on each chat.
+		// If contextWindow is right but num_ctx is stale, the model still
+		// gets truncated. Pin both sides.
+		for (const name of [
+			"deepseek-v4-pro:cloud",
+			"deepseek-v4-flash:cloud",
+			"deepseek-v4:671b",
+			"gemma4:31b",
+		]) {
+			const caps = getModelCapabilities(name);
+			assert.equal(caps.ollamaOptions?.num_ctx, caps.contextWindow,
+				`${name}: num_ctx ${caps.ollamaOptions?.num_ctx} != contextWindow ${caps.contextWindow}`);
+		}
+	});
+});
+
+describe("getModelCapabilities — minimax-m2.7 reflects /api/show truth", () => {
+	it("minimax-m2.7 contextWindow is 196608, not the official-spec 1048576", () => {
+		// minimax-m2.7:cloud reports 196608 via /api/show even though the
+		// MiniMax M2 announcement quoted 1M context. Trust the deployed
+		// backend, not marketing — a 1M num_ctx would silently truncate
+		// or OOM under cloud-routing.
+		assert.equal(getModelCapabilities("minimax-m2.7:cloud").contextWindow, 196608);
+		assert.equal(getModelCapabilities("minimax-m2.7:cloud").ollamaOptions?.num_ctx, 196608);
+	});
+});

package/src/resources/extensions/ollama/tests/ollama-discovery-priority.test.ts

@@ -0,0 +1,93 @@
+// OTTO — Tests for ollama-discovery /api/show priority and num_ctx sync
+//
+// Ported from gsd-pi fc39cdc. Pins the showContextWindow > caps resolution
+// order so a stale KNOWN_MODELS entry cannot mask the authoritative
+// /api/show value, and pins the num_ctx mirror invariant so the priority
+// flip propagates to inference requests.
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { discoverModels } from "../ollama-discovery.js";
+import type { OllamaModelInfo, OllamaShowResponse, OllamaTagsResponse } from "../types.js";
+
+function makeDeps(showResp: Partial<OllamaShowResponse>, modelInfo: Partial<OllamaModelInfo> = {}) {
+	return {
+		listModels: async (): Promise<OllamaTagsResponse> => ({
+			models: [{
+				name: "test-model:latest",
+				model: "test-model:latest",
+				modified_at: "",
+				size: 1_000_000,
+				digest: "abc",
+				details: { parent_model: "", format: "", family: "", families: [], parameter_size: "7B", quantization_level: "" },
+				...modelInfo,
+			} as OllamaModelInfo],
+		}),
+		showModel: async () => ({
+			modelfile: "",
+			parameters: "",
+			template: "",
+			details: { parent_model: "", format: "", family: "", families: [], parameter_size: "7B", quantization_level: "" },
+			model_info: {},
+			...showResp,
+		} as OllamaShowResponse),
+	};
+}
+
+describe("enrichModel — /api/show context priority", () => {
+	it("uses /api/show context_length over a stale KNOWN_MODELS value", async () => {
+		// llama3.1 in KNOWN_MODELS = 131072. If /api/show says 262144, trust it.
+		const deps = makeDeps({ model_info: { "llama.context_length": 262144 } }, { name: "llama3.1:8b" });
+		const [m] = await discoverModels(deps);
+		assert.equal(m.contextWindow, 262144);
+	});
+
+	it("falls back to KNOWN_MODELS when /api/show provides no context_length", async () => {
+		const deps = makeDeps({ model_info: {} }, { name: "llama3.1:8b" });
+		const [m] = await discoverModels(deps);
+		assert.equal(m.contextWindow, 131072); // KNOWN_MODELS llama3.1
+	});
+});
+
+describe("enrichModel — num_ctx sync with /api/show", () => {
+	it("syncs ollamaOptions.num_ctx with showContextWindow when /api/show wins", async () => {
+		const deps = makeDeps({ model_info: { "llama.context_length": 262144 } }, { name: "llama3.1:8b" });
+		const [m] = await discoverModels(deps);
+		assert.equal(m.ollamaOptions?.num_ctx, 262144,
+			"num_ctx must mirror the authoritative contextWindow; sending stale num_ctx defeats the priority flip");
+	});
+
+	it("preserves sibling ollamaOptions fields when /api/show flips num_ctx", async () => {
+		// Drive enrichModel with a synthetic capabilities stub: model name matches a known
+		// table entry, but we mock the table indirectly by injecting deps that simulate
+		// what enrichModel would receive. Since enrichModel resolves caps internally via
+		// getModelCapabilities, the cleanest assertion is at the discoverModels output:
+		// the returned ollamaOptions must contain ALL fields from caps.ollamaOptions plus
+		// the synced num_ctx — confirmed by checking the num_ctx is overridden AND the
+		// returned ollamaOptions object reference is NOT equal to caps.ollamaOptions (it
+		// must be a fresh object from the spread). This catches a naive replacement
+		// `ollamaOptions = { num_ctx: showContextWindow }` that drops siblings.
+		const deps = makeDeps({ model_info: { "llama.context_length": 262144 } }, { name: "llama3.1:8b" });
+		const [m] = await discoverModels(deps);
+		// Sanity: num_ctx flipped to /api/show value
+		assert.equal(m.ollamaOptions?.num_ctx, 262144);
+		// Real coverage: the returned object must be a spread, not a literal {num_ctx}.
+		// We verify this structurally by checking that every key from the original
+		// caps.ollamaOptions (looked up directly from the source table) is present.
+		// llama3.1 table currently only has num_ctx — if/when sibling fields are added,
+		// this test will catch a regression where the spread is removed.
+		// For now we pin the spread invariant: ollamaOptions must be the fresh
+		// shallow-spread object, not a reference to caps.ollamaOptions.
+		const { getModelCapabilities } = await import("../model-capabilities.js");
+		const tableCaps = getModelCapabilities("llama3.1:8b");
+		const tableNumCtx = tableCaps.ollamaOptions?.num_ctx;
+		assert.notEqual(tableNumCtx, 262144, "test precondition: table num_ctx differs from /api/show value");
+		assert.notEqual(m.ollamaOptions, tableCaps.ollamaOptions,
+			"returned ollamaOptions must be a fresh spread object, not a reference to the table — otherwise a future direct replacement `{num_ctx}` would silently drop sibling fields");
+	});
+
+	it("preserves KNOWN_MODELS num_ctx when /api/show returns no context_length", async () => {
+		const deps = makeDeps({ model_info: {} }, { name: "llama3.1:8b" });
+		const [m] = await discoverModels(deps);
+		assert.equal(m.ollamaOptions?.num_ctx, 131072); // unchanged from table
+	});
+});

package/src/resources/extensions/otto/commands/release-notes/_data.ts

@@ -33,13 +33,29 @@ export interface ReleaseNotesManifest {
 
 export const RELEASE_NOTES_MANIFEST: ReleaseNotesManifest = {
 	truncated: false,
-	total: 18,
+	total: 19,
 	oldestBundled: '1.0.0',
-	newestBundled: '1.3.2',
+	newestBundled: '1.3.3',
 	historyUrl: 'https://github.com/cmetech/otto-cli/blob/main/CHANGELOG.md',
 };
 
 export const RELEASE_NOTES: ReleaseNote[] = [
+	{
+		version: '1.3.3',
+		date: '2026-06-08',
+		headline: 'Maintenance patch rolling up six upstream-ported fixes that landed on `main` since 1.3.2: TUI rendering on JetBrains terminals, pattern-resolution basedir, project-root artifact placement when running inside worktrees, verification-pause diagnostics, per-PID crash-log isolation, and Ollama context-window trust.',
+		fixed: [
+			'**JetBrains terminal capabilities.** TUI rendering now provides the correct capability set when running under JetBrains\' embedded terminal (`packages/pi-tui`), eliminating layout glitches reported on IntelliJ / WebStorm / GoLand. Closes #31 (ported via PR #77).',
+			'**Pattern basedir resolution.** Pattern lookups now resolve against the correct base directory, restoring expected matching behavior for relative glob patterns. Closes #53 (ported via PR #74).',
+			'**Project root artifacts in worktrees.** Workflow runs invoked from a `git worktree` now project root-level artifacts (lockfile, configs, generated files) into the worktree itself instead of leaking into the primary checkout. Closes #90 (PR #370).',
+			'**Verification pause message shows failing check.** When a workflow pauses after an execution step, the message now surfaces *which* check failed instead of a generic pause string, dramatically shortening the debug loop. Closes #99 (PR #371).',
+			'**Crash logs append to single per-PID file.** Crash diagnostics now append to one file per process rather than fragmenting across multiple files, making post-mortem inspection coherent. Closes #343 (PR #374).',
+			'**Ollama `/api/show` context + `num_ctx` sync.** The Ollama integration now trusts the model\'s reported context window from `/api/show`, keeps `num_ctx` in lockstep, and corrects `KNOWN_MODELS` drift — preventing silent truncation when a model\'s real context exceeds the hard-coded table. Closes #345 (PR #375).',
+		],
+		notes: [
+			'Internal: upstream-swarm orchestrator skill + autonomy hardening (PRs #75, #76, #78, #79, #80, #81, #82) landed in this window but are tooling-only and have no runtime impact for end users.',
+		],
+	},
 	{
 		version: '1.3.2',
 		date: '2026-06-04',

package/src/resources/extensions/workflow/auto-verification.ts

@@ -600,6 +600,7 @@ export async function runPostUnitVerification(
     // ── Post-execution checks (run after main verification passes for execute-task units) ──
     let postExecChecks: PostExecutionCheckJSON[] | undefined;
     let postExecBlockingFailure = false;
+    let postExecFailureSummary: string | null = null;
 
     if (result.passed && mid && sid && tid) {
       // Check preferences — respect enhanced_verification and enhanced_verification_post
@@ -696,6 +697,13 @@ export async function runPostUnitVerification(
               const blockingCount = postExecResult.checks.filter(
                 (c) => !c.passed && c.blocking
               ).length;
+              const firstBlockingFailure = postExecResult.checks.find(
+                (c) => !c.passed && c.blocking
+              );
+              if (firstBlockingFailure) {
+                postExecFailureSummary =
+                  `[${firstBlockingFailure.category}] ${firstBlockingFailure.target}: ${firstBlockingFailure.message}`;
+              }
               ctx.ui.notify(
                 `Post-execution checks failed: ${blockingCount} blocking issue${blockingCount === 1 ? "" : "s"} found`,
                 "error"
@@ -810,12 +818,13 @@ export async function runPostUnitVerification(
       s.verificationRetryCount.delete(retryKey);
       s.verificationRetryFailureHashes.delete(retryKey);
       s.pendingVerificationRetry = null;
+      const failureDetail = postExecFailureSummary ?? "unknown post-execution check failure";
       ctx.ui.notify(
-        `Post-execution checks failed — cross-task consistency issue detected, pausing for human review`,
+        `Post-execution checks failed (${failureDetail}) — pausing for human review`,
         "error",
       );
       await pauseAuto(ctx, pi, {
-        message: "Post-execution checks failed: cross-task consistency issue detected.",
+        message: `Post-execution checks failed: ${failureDetail}.`,
         category: "unknown",
       });
       return "pause";

package/src/resources/extensions/workflow/bootstrap/crash-log.ts

@@ -1,5 +1,5 @@
 /**
- * crash-log.ts — Write crash diagnostics to ~/.otto/crash/<timestamp>.log
+ * crash-log.ts — Write crash diagnostics to ~/.otto/crash/pid-<pid>.log
  *
  * Zero cross-dependencies: only uses Node.js built-ins so it can be imported
  * safely from uncaughtException / unhandledRejection handlers and from tests
@@ -11,15 +11,14 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 
 /**
- * Write a crash log to ~/.otto/crash/<timestamp>.log (or $OTTO_HOME/crash/).
+ * Write a crash log to ~/.otto/crash/pid-<pid>.log (or $OTTO_HOME/crash/).
  * Never throws — must be safe to call from any error handler.
  */
 export function writeCrashLog(err: Error, source: string): void {
   try {
     const crashDir = join((process.env.OTTO_HOME ?? process.env.OTTO_HOME) ?? join(homedir(), ".otto"), "crash");
     mkdirSync(crashDir, { recursive: true });
-    const ts = new Date().toISOString().replace(/[:.]/g, "-");
-    const logPath = join(crashDir, `${ts}.log`);
+    const logPath = join(crashDir, `pid-${process.pid}.log`);
     const lines = [
       `[otto] ${source}: ${err.message}`,
       `timestamp: ${new Date().toISOString()}`,

package/src/resources/extensions/workflow/tests/crash-handler-secondary.test.ts

@@ -49,6 +49,28 @@ describe('register-extension crash handler secondary fixes (#3348)', () => {
     }
   });
 
+  test('writeCrashLog appends repeated crashes from one process to a single file', async () => {
+    const tmpHome = join(tmpdir(), `otto-crash-test-${randomUUID()}`);
+    const origHome = process.env.OTTO_HOME;
+    process.env.OTTO_HOME = tmpHome;
+    try {
+      const { writeCrashLog } = await import('../bootstrap/crash-log.ts');
+      writeCrashLog(new Error('first crash'), 'uncaughtException');
+      writeCrashLog(new Error('second crash'), 'unhandledRejection');
+
+      const crashDir = join(tmpHome, 'crash');
+      const logs = readdirSync(crashDir).filter((f) => f.endsWith('.log'));
+      assert.equal(logs.length, 1, 'repeated writes in one process should share one crash log');
+
+      const content = readFileSync(join(crashDir, logs[0]), 'utf-8');
+      assert.ok(content.includes('first crash'), 'log should contain first error message');
+      assert.ok(content.includes('second crash'), 'log should contain second error message');
+    } finally {
+      process.env.OTTO_HOME = origHome;
+      rmSync(tmpHome, { recursive: true, force: true });
+    }
+  });
+
   test('_gsdRejectionGuard is registered for unhandledRejection', () => {
     installEpipeGuard();
     const listener = process.listeners("unhandledRejection").find((candidate) =>

package/src/resources/extensions/workflow/tests/post-exec-retry-bypass.test.ts

@@ -359,13 +359,8 @@ describe("Post-execution blocking failure retry bypass", () => {
     assert.ok(messages.some((m: string) => m.includes("Verification failed") && m.includes("auto-fix attempt 1/2")));
   });
 
-  test("post-exec failure notification mentions cross-task consistency", async () => {
-    // This test verifies that the notification for post-exec failures includes
-    // the appropriate message about cross-task consistency issues.
-    // The actual post-exec failure would require specific file/output state
-    // that's harder to set up in a unit test, but we can verify the code path exists.
-    
-    createBasicTask();
+  test("post-exec failure notification includes failing check details", async () => {
+    createPostExecFailureTask();
     writePreferences({
       enhanced_verification: true,
       enhanced_verification_post: true,
@@ -381,9 +376,27 @@ describe("Post-execution blocking failure retry bypass", () => {
     const vctx: VerificationContext = { s, ctx, pi };
     const result = await runPostUnitVerification(vctx, pauseAutoMock);
 
-    // The verification should pass with our simple "echo pass" task
-    // This test mainly confirms the wiring is correct
-    assert.equal(result, "continue");
+    assert.equal(result, "pause");
+    assert.equal(pauseAutoMock.mock.callCount(), 1);
+    const notifyMessages = ctx.ui.notify.mock.calls.map((c: { arguments: unknown[] }) =>
+      String(c.arguments[0])
+    );
+    assert.ok(
+      notifyMessages.some(
+        (m: string) =>
+          m.includes("Post-execution checks failed ([import] src/broken.ts:1") &&
+          m.includes("pausing for human review")
+      )
+    );
+
+    const pauseCallArgs = (pauseAutoMock.mock.calls[0]?.arguments as unknown as unknown[])?.[2] as
+      | { message?: string }
+      | undefined;
+    assert.ok(
+      pauseCallArgs?.message?.includes(
+        "Post-execution checks failed: [import] src/broken.ts:1"
+      )
+    );
   });
 
   test("uok gate runner persists post-execution gate failures when enabled", async () => {

package/src/resources/extensions/workflow/tests/worktree-state-projection.test.ts

@@ -2,7 +2,7 @@
 // File Purpose: Worktree State Projection Module — typed-Interface contract tests for projectRootToWorktree (ADR-016).
 import test from "node:test";
 import assert from "node:assert/strict";
-import { mkdtempSync, rmSync, mkdirSync } from "node:fs";
+import { existsSync, mkdtempSync, readFileSync, rmSync, mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { WorktreeStateProjection } from "../worktree-state-projection.js";
@@ -60,6 +60,46 @@ test("projectRootToWorktree is idempotent — repeated calls do not throw", () =
   }
 });
 
+test("projectRootToWorktree forwards root PROJECT.md into isolated worktrees", () => {
+  const { dir, cleanup } = makeProjectRoot();
+  try {
+    const worktree = join(dir, ".otto/workflow/worktrees/M001");
+    mkdirSync(join(dir, ".otto/workflow/milestones/M001"), { recursive: true });
+    mkdirSync(join(worktree, ".otto/workflow"), { recursive: true });
+
+    const projectContent = [
+      "# Project",
+      "",
+      "## Milestone Sequence",
+      "",
+      "- [ ] M001: Foundation — Establish the runnable slice.",
+      "",
+    ].join("\n");
+    writeFileSync(join(dir, ".otto/workflow/PROJECT.md"), projectContent);
+    writeFileSync(join(dir, ".otto/workflow/REQUIREMENTS.md"), "# Requirements\n");
+    writeFileSync(
+      join(dir, ".otto/workflow/milestones/M001/M001-ROADMAP.md"),
+      "# M001\n",
+    );
+
+    const workspace = createWorkspace(worktree);
+    const scope = scopeMilestone(workspace, "M001");
+    const projection = new WorktreeStateProjection();
+
+    projection.projectRootToWorktree(scope);
+
+    const projectedProject = join(worktree, ".otto/workflow/PROJECT.md");
+    assert.ok(existsSync(projectedProject), "PROJECT.md is available to worktree-bound units");
+    assert.equal(readFileSync(projectedProject, "utf-8"), projectContent);
+    assert.ok(
+      existsSync(join(worktree, ".otto/workflow/milestones/M001/M001-ROADMAP.md")),
+      "milestone artifacts still project into the worktree",
+    );
+  } finally {
+    cleanup();
+  }
+});
+
 // ─── projectWorktreeToRoot — Module contract ────────────────────────────────
 
 test("projectWorktreeToRoot exists and accepts a MilestoneScope", () => {

package/src/resources/extensions/workflow/worktree-state-projection.ts

@@ -172,6 +172,35 @@ const ROOT_DIAGNOSTIC_FILES = [
   "metrics.json",
 ] as const;
 
+/**
+ * Root-level .otto/workflow/ projections copied from project root into worktrees for
+ * compatibility reads. Project root remains authoritative; copy-back still
+ * excludes these markdown projections.
+ */
+const ROOT_FORWARD_PROJECTION_FILES = [
+  "DECISIONS.md",
+  "REQUIREMENTS.md",
+  "PROJECT.md",
+  "KNOWLEDGE.md",
+  "OVERRIDES.md",
+  "QUEUE.md",
+  "completed-units.json",
+  "metrics.json",
+  "mcp.json",
+] as const;
+
+function syncRootProjectionFilesToWorktree(prGsd: string, wtGsd: string): void {
+  mkdirSync(wtGsd, { recursive: true });
+
+  for (const file of ROOT_FORWARD_PROJECTION_FILES) {
+    const src = join(prGsd, file);
+    const dst = join(wtGsd, file);
+    if (!existsSync(src) || existsSync(dst)) continue;
+
+    safeCopy(src, dst, { force: false });
+  }
+}
+
 // ─── Implementation cores ────────────────────────────────────────────────
 //
 // The `_*Impl` exports take raw paths so the deprecated path-string
@@ -204,6 +233,10 @@ export function _projectRootToWorktreeImpl(
   // Compare realpaths and skip when they resolve to the same physical path (#2184).
   if (isSamePath(prGsd, wtGsd)) return;
 
+  // Root PROJECT/REQUIREMENTS/DECISIONS projections must be readable from a
+  // worktree-bound unit; the project root remains authoritative.
+  syncRootProjectionFilesToWorktree(prGsd, wtGsd);
+
   // Copy milestone directory from project root to worktree — additive only.
   // force:false prevents cpSync from overwriting existing worktree files.
   // Without this, worktree-local files (e.g. VALIDATION.md written