[codex] Fix workspace.yaml collision detection

.changeset/fuzzy-dagster-workspaces.md

@@ -0,0 +1,5 @@
+---
+"@fission-ai/openspec": patch
+---
+
+Move beta workspace view state to `.openspec-workspace/view.yaml` and ignore foreign root `workspace.yaml` files during workspace discovery so `openspec update` keeps working in Dagster projects.

docs/concepts.md

@@ -71,7 +71,8 @@ A workspace has a different shape from a repo-local project:
 
 ```text
 getGlobalDataDir()/workspaces/<workspace-name>/
-├── workspace.yaml                 # Private local view record
+├── .openspec-workspace/
+│   └── view.yaml                  # Private local view record
 ├── AGENTS.md                      # Generated runtime guidance
 └── <workspace-name>.code-workspace # Generated editor workspace file
 ```
@@ -90,7 +91,7 @@ That distinction matters. The workspace folder is a local coordination surface f
 Stable link names are how a workspace refers to repos and folders. The private workspace record keeps names such as `api`, `web`, or `checkout` and maps them to this runtime's local paths.
 
 ```yaml
-# workspace.yaml
+# .openspec-workspace/view.yaml
 version: 1
 name: platform
 context: null
@@ -99,7 +100,7 @@ links:
   web: /repos/web
 ```
 
-When a workspace opens an initiative, `context` records the selected context-store binding and initiative id. Registry-selected stores stay portable by id; path-selected stores intentionally preserve the runtime-local path because `workspace.yaml` is private local state.
+When a workspace opens an initiative, `context` records the selected context-store binding and initiative id. Registry-selected stores stay portable by id; path-selected stores intentionally preserve the runtime-local path because `.openspec-workspace/view.yaml` is private local state.
 
 ```yaml
 context:
@@ -133,7 +134,7 @@ getGlobalDataDir()/workspaces
 
 That means `$XDG_DATA_HOME/openspec/workspaces` when `XDG_DATA_HOME` is set, `~/.local/share/openspec/workspaces` on Unix-style fallback, and `%LOCALAPPDATA%\openspec\workspaces` on native Windows fallback. Native Windows shells, PowerShell, and WSL2 each keep the path strings for the runtime running OpenSpec. This foundation does not translate between `D:\repo`, `/mnt/d/repo`, and UNC WSL paths.
 
-OpenSpec can still read older beta workspace roots as compatibility inputs, but managed workspaces now use the root `workspace.yaml` record above. The workspace folder remains authoritative for its own private local view.
+Managed workspaces use the namespaced private view record above. The workspace folder remains authoritative for its own private local view.
 
 Workspace visibility is not change commitment. Set up a workspace when OpenSpec should know which repos or folders are relevant; create a change later when you are ready to plan a feature, fix, project, or other piece of work.
 

docs/workspaces-beta/user-guide.md

@@ -30,7 +30,7 @@ which local repos or folders to include.
 
 The opened editor view shows linked repos and folders first, initiative context
 when attached, and a small `OpenSpec workspace` folder last with `AGENTS.md`,
-`workspace.yaml`, and the generated `.code-workspace` file.
+`.openspec-workspace/view.yaml`, and the generated `.code-workspace` file.
 
 Use `openspec workspace open --initiative team-context/billing-launch --editor`
 when you want to skip the picker. Use `--agent codex-cli`, `--agent claude`, or

openspec/specs/workspace-foundation/spec.md

@@ -30,7 +30,7 @@ OpenSpec SHALL use one kebab-case workspace name across workspace identity, mana
 
 #### Scenario: Using one workspace name
 - **WHEN** OpenSpec creates or records a managed workspace
-- **THEN** the workspace name SHALL be stored in `.openspec-workspace/workspace.yaml`
+- **THEN** the workspace name SHALL be stored in `.openspec-workspace/view.yaml`
 - **AND** the same name SHALL be used as the default managed workspace folder name
 - **AND** the same name SHALL be used as the local registry name
 
@@ -78,7 +78,7 @@ OpenSpec SHALL keep shared workspace information separate from local machine pat
 
 #### Scenario: Keeping managed workspace view state local
 - **WHEN** OpenSpec creates a managed workspace
-- **THEN** it SHALL write `workspace.yaml` in the workspace root as private local view state
+- **THEN** it SHALL write `.openspec-workspace/view.yaml` as private local view state
 - **AND** the file SHALL preserve stable link names and local path values for the current machine
 
 ### Requirement: Standard Workspace Location
@@ -130,7 +130,7 @@ OpenSpec SHALL keep a lightweight local registry of known workspaces on the curr
 
 #### Scenario: Keeping workspace folders authoritative
 - **WHEN** OpenSpec reads workspace details
-- **THEN** each workspace folder's `.openspec-workspace/workspace.yaml` SHALL remain the source of truth for that workspace
+- **THEN** each workspace folder's `.openspec-workspace/view.yaml` SHALL remain the source of truth for that workspace
 - **AND** the local registry SHALL act only as an index of known workspace locations
 
 #### Scenario: Finding workspaces from anywhere
@@ -210,7 +210,7 @@ OpenSpec SHALL store a workspace's preferred opener in machine-local workspace s
 
 #### Scenario: Recording an interactive setup opener choice
 - **WHEN** an interactive user chooses a preferred opener during `openspec workspace setup`
-- **THEN** OpenSpec SHALL record the opener in `.openspec-workspace/local.yaml`
+- **THEN** OpenSpec SHALL record the opener in `.openspec-workspace/view.yaml`
 - **AND** the stored value SHALL use a structured `preferred_opener` object with `kind` and `id`
 
 #### Scenario: Recording a non-interactive setup opener choice

src/commands/workspace/context-status.ts

@@ -46,7 +46,7 @@ export async function collectWorkspaceContextStatuses(
           target: 'workspace.context.store',
           fix: context.store.selector.kind === 'registry'
             ? 'openspec context-store doctor'
-            : `Check the path in workspace.yaml or run openspec initiative show ${initiativeId} ${selector}`,
+            : `Check the path in .openspec-workspace/view.yaml or run openspec initiative show ${initiativeId} ${selector}`,
         }
       ),
     ];

src/commands/workspace/open-view.ts

@@ -211,7 +211,7 @@ async function resolveStoredWorkspaceInitiative(
         target: 'workspace.context.store',
         fix: context.store.selector.kind === 'registry'
           ? 'openspec context-store doctor'
-          : 'Check the path in workspace.yaml.',
+          : 'Check the path in .openspec-workspace/view.yaml.',
       }
     );
   }

src/commands/workspace/operations.ts

@@ -205,7 +205,7 @@ function localStateInvalidStatus(error: unknown): WorkspaceStatus {
     `Machine-local paths could not be read: ${asErrorMessage(error)}`,
     {
       target: 'workspace.local_state',
-      fix: 'Repair workspace.yaml, then run openspec workspace relink <name> <path> for affected links.',
+      fix: 'Repair .openspec-workspace/view.yaml, then run openspec workspace relink <name> <path> for affected links.',
     }
   );
 }
@@ -433,7 +433,7 @@ export async function loadWorkspaceForDoctor(
             `Workspace state could not be read: ${asErrorMessage(error)}`,
             {
               target: 'workspace.root',
-              fix: 'Repair .openspec-workspace/workspace.yaml before using this workspace.',
+              fix: 'Repair .openspec-workspace/view.yaml before using this workspace.',
             }
           ),
         ],
@@ -523,7 +523,7 @@ async function readWorkspaceViewForMutation(selected: SelectedWorkspace): Promis
       'workspace_state_invalid',
       {
         target: 'workspace.state',
-        fix: 'Repair workspace.yaml before using this workspace.',
+        fix: 'Repair .openspec-workspace/view.yaml before using this workspace.',
       }
     );
   }

src/core/workspace/foundation.ts

@@ -9,7 +9,7 @@ import {
 import { FileSystemUtils } from '../../utils/file-system.js';
 
 export const WORKSPACE_METADATA_DIR_NAME = '.openspec-workspace';
-export const WORKSPACE_VIEW_STATE_FILE_NAME = 'workspace.yaml';
+export const WORKSPACE_VIEW_STATE_FILE_NAME = 'view.yaml';
 export const WORKSPACE_CHANGES_DIR_NAME = 'changes';
 export const WORKSPACE_CODE_WORKSPACE_EXTENSION = '.code-workspace';
 
@@ -77,7 +77,7 @@ export function getWorkspaceMetadataDir(workspaceRoot: string): string {
 }
 
 export function getWorkspaceViewStatePath(workspaceRoot: string): string {
-  return joinWorkspacePath(workspaceRoot, WORKSPACE_VIEW_STATE_FILE_NAME);
+  return joinWorkspacePath(getWorkspaceMetadataDir(workspaceRoot), WORKSPACE_VIEW_STATE_FILE_NAME);
 }
 
 export function getWorkspaceChangesDir(workspaceRoot: string): string {

src/core/workspace/legacy-state.ts

@@ -3,7 +3,6 @@ import { z } from 'zod';
 
 import {
   WORKSPACE_METADATA_DIR_NAME,
-  WORKSPACE_VIEW_STATE_FILE_NAME,
   getWorkspaceMetadataDir,
   parseWorkspaceViewState,
   validateWorkspaceLinkName,
@@ -16,7 +15,7 @@ import {
 } from './foundation.js';
 import { FileSystemUtils } from '../../utils/file-system.js';
 
-export const WORKSPACE_LEGACY_SHARED_STATE_FILE_NAME = WORKSPACE_VIEW_STATE_FILE_NAME;
+export const WORKSPACE_LEGACY_SHARED_STATE_FILE_NAME = 'workspace.yaml';
 export const WORKSPACE_LEGACY_LOCAL_STATE_FILE_NAME = 'local.yaml';
 export const WORKSPACE_LEGACY_LOCAL_STATE_IGNORE_PATTERN =
   `${WORKSPACE_METADATA_DIR_NAME}/${WORKSPACE_LEGACY_LOCAL_STATE_FILE_NAME}`;

src/core/workspace/open-surface.ts

@@ -25,7 +25,7 @@ This directory is an OpenSpec workspace: a local working view over context store
 - Use repo-local OpenSpec changes for implementation plans owned by a repo or team.
 - Use linked repos and folders to inspect context, understand ownership, and make edits in the place that owns the work.
 - Keep workspace-local files focused on local paths, opener state, agent setup, and other machine-specific view state.
-- Use OpenSpec workspace commands instead of hand-editing \`workspace.yaml\`.
+- Use OpenSpec workspace commands instead of hand-editing \`.openspec-workspace/view.yaml\`.
 - If this workspace contains legacy or beta workspace-level planning files, treat them as compatibility context unless the user explicitly asks to use that beta flow.`;
 
 export interface WorkspaceOpenResolvedContext {

src/core/workspace/state-io.ts

@@ -4,6 +4,7 @@ import * as path from 'node:path';
 import { FileSystemUtils } from '../../utils/file-system.js';
 import {
   getWorkspaceChangesDir,
+  getWorkspaceMetadataDir,
   getWorkspaceViewStatePath,
   parseWorkspaceViewState,
   serializeWorkspaceViewState,
@@ -162,10 +163,10 @@ export async function writeWorkspaceViewState(
   workspaceRoot: string,
   state: WorkspaceViewState
 ): Promise<void> {
-  await FileSystemUtils.writeFile(
-    getWorkspaceViewStatePath(workspaceRoot),
-    serializeWorkspaceViewState(state)
-  );
+  const content = serializeWorkspaceViewState(state);
+
+  await FileSystemUtils.createDirectory(getWorkspaceMetadataDir(workspaceRoot));
+  await FileSystemUtils.writeFile(getWorkspaceViewStatePath(workspaceRoot), content);
 }
 
 export async function workspaceChangesDirExists(workspaceRoot: string): Promise<boolean> {

test/commands/workspace-initiative-open.test.ts

@@ -231,7 +231,7 @@ describe('workspace open initiative views', () => {
         },
       })
     );
-    expect(fs.existsSync(path.join(workspaceRoot, '.openspec-workspace'))).toBe(false);
+    expect(fs.existsSync(path.join(workspaceRoot, '.openspec-workspace'))).toBe(true);
     expect(fs.existsSync(path.join(globalDataDir, 'workspaces', 'registry.yaml'))).toBe(false);
     expect(fs.readFileSync(path.join(workspaceRoot, 'AGENTS.md'), 'utf-8')).toContain(
       'Initiative title: Billing Launch'

test/commands/workspace.test.ts

@@ -475,6 +475,32 @@ describe('workspace command', () => {
     expect(fs.existsSync(path.join(api, '.codex'))).toBe(false);
   });
 
+  it('does not redirect openspec update for repo-local projects with foreign workspace.yaml', async () => {
+    const repoRoot = mkdir('repos/dagster');
+    fs.mkdirSync(path.join(repoRoot, 'openspec'), { recursive: true });
+    const foreignWorkspaceYaml = `load_from:
+  - grpc_server:
+      host: dagster-code
+      port: 4000
+      location_name: example
+`;
+    fs.writeFileSync(path.join(repoRoot, 'workspace.yaml'), foreignWorkspaceYaml);
+
+    const update = await runCLI(['update'], {
+      cwd: repoRoot,
+      env,
+    });
+
+    expect(update.exitCode).toBe(0);
+    expect(update.stdout).not.toContain('Workspace update complete');
+    expect(update.stderr).not.toContain('Invalid workspace state');
+    expect(update.stdout).toContain('No configured tools found');
+    expect(fs.readFileSync(path.join(repoRoot, 'workspace.yaml'), 'utf-8')).toBe(
+      foreignWorkspaceYaml
+    );
+    expect(fs.existsSync(path.join(repoRoot, WORKSPACE_METADATA_DIR_NAME))).toBe(false);
+  });
+
   it('updates the workspace passed to openspec update even when another workspace is known', async () => {
     const firstApi = mkdir('repos/first-api');
     const secondApi = mkdir('repos/second-api');

test/core/planning-home.test.ts

@@ -48,8 +48,8 @@ describe('planning home paths', () => {
 
     fs.mkdirSync(path.join(realWorkspaceRoot, '.openspec-workspace'), { recursive: true });
     fs.writeFileSync(
-      path.join(realWorkspaceRoot, '.openspec-workspace', 'workspace.yaml'),
-      'version: 1\nname: platform\nlinks: {}\n',
+      path.join(realWorkspaceRoot, '.openspec-workspace', 'view.yaml'),
+      'version: 1\nname: platform\ncontext: null\nlinks: {}\n',
       'utf-8'
     );
     fs.symlinkSync(
@@ -74,7 +74,7 @@ describe('planning home paths', () => {
 
     fs.mkdirSync(path.join(workspaceRoot, '.openspec-workspace'), { recursive: true });
     fs.writeFileSync(
-      path.join(workspaceRoot, 'workspace.yaml'),
+      path.join(workspaceRoot, '.openspec-workspace', 'view.yaml'),
       'version: 1\nname: bad/name\ncontext: null\nlinks: {}\n',
       'utf-8'
     );
@@ -91,4 +91,30 @@ describe('planning home paths', () => {
       })
     ).toThrow(/Workspace name/u);
   });
+
+  it('resolves repo-local projects with foreign workspace.yaml as repo planning homes', () => {
+    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'openspec-planning-home-'));
+    tempDirs.push(tempDir);
+    const repoRoot = path.join(tempDir, 'dagster-repo');
+    const changesDir = path.join(repoRoot, 'openspec', 'changes');
+
+    fs.mkdirSync(changesDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(repoRoot, 'workspace.yaml'),
+      `load_from:
+  - python_file:
+      relative_path: repository.py
+      location_name: dagster_repo
+`,
+      'utf-8'
+    );
+
+    const planningHome = resolveCurrentPlanningHomeSync({
+      startPath: changesDir,
+      allowImplicitRepoRoot: false,
+    });
+
+    expect(planningHome.kind).toBe('repo');
+    expect(planningHome.root).toBe(fs.realpathSync.native(repoRoot));
+  });
 });

test/core/workspace/foundation.test.ts

@@ -58,7 +58,7 @@ describe('workspace foundation', () => {
 
   function createWorkspaceRoot(name = 'platform'): string {
     const workspaceRoot = path.join(tempDir, name);
-    fs.mkdirSync(workspaceRoot, { recursive: true });
+    fs.mkdirSync(getWorkspaceMetadataDir(workspaceRoot), { recursive: true });
     fs.writeFileSync(
       getWorkspaceViewStatePath(workspaceRoot),
       `version: 1
@@ -83,7 +83,7 @@ links: {}
   describe('path helpers', () => {
     it('exposes the workspace constants', () => {
       expect(WORKSPACE_METADATA_DIR_NAME).toBe('.openspec-workspace');
-      expect(WORKSPACE_VIEW_STATE_FILE_NAME).toBe('workspace.yaml');
+      expect(WORKSPACE_VIEW_STATE_FILE_NAME).toBe('view.yaml');
       expect(WORKSPACE_CHANGES_DIR_NAME).toBe('changes');
       expect(MANAGED_WORKSPACES_DIR_NAME).toBe('workspaces');
       expect(WORKSPACE_REGISTRY_FILE_NAME).toBe('registry.yaml');
@@ -96,7 +96,7 @@ links: {}
         path.join(workspaceRoot, '.openspec-workspace')
       );
       expect(getWorkspaceViewStatePath(workspaceRoot)).toBe(
-        path.join(workspaceRoot, 'workspace.yaml')
+        path.join(workspaceRoot, '.openspec-workspace', 'view.yaml')
       );
       expect(getWorkspaceChangesDir(workspaceRoot)).toBe(path.join(workspaceRoot, 'changes'));
       expect(getWorkspaceCodeWorkspaceFileName('platform')).toBe('platform.code-workspace');
@@ -109,7 +109,7 @@ links: {}
       const workspaceRoot = 'D:\\repos\\platform-workspace';
 
       expect(getWorkspaceViewStatePath(workspaceRoot)).toBe(
-        'D:\\repos\\platform-workspace\\workspace.yaml'
+        'D:\\repos\\platform-workspace\\.openspec-workspace\\view.yaml'
       );
     });
 
@@ -220,6 +220,57 @@ links: {}
       );
     });
 
+    it('ignores foreign root workspace.yaml files in repo-local projects', async () => {
+      const repoRoot = path.join(tempDir, 'dagster-repo');
+      const nestedDir = path.join(repoRoot, 'openspec', 'changes', 'add-feature');
+      fs.mkdirSync(nestedDir, { recursive: true });
+      fs.writeFileSync(
+        path.join(repoRoot, 'workspace.yaml'),
+        `load_from:
+  - grpc_server:
+      host: dagster-code
+      port: 4000
+      location_name: example
+`
+      );
+
+      await expect(isWorkspaceRoot(repoRoot)).resolves.toBe(false);
+      await expect(findWorkspaceRoot(nestedDir)).resolves.toBe(null);
+    });
+
+    it('ignores unmarked root view state even when it is OpenSpec-shaped', async () => {
+      const workspaceRoot = path.join(tempDir, 'unmarked-beta-workspace');
+      fs.mkdirSync(workspaceRoot, { recursive: true });
+      fs.writeFileSync(
+        path.join(workspaceRoot, 'workspace.yaml'),
+        `version: 1
+name: unmarked-beta-workspace
+context: null
+links: {}
+`
+      );
+
+      await expect(isWorkspaceRoot(workspaceRoot)).resolves.toBe(false);
+      await expect(findWorkspaceRoot(workspaceRoot)).resolves.toBe(null);
+    });
+
+    it('writes canonical view state inside the OpenSpec metadata directory', async () => {
+      const workspaceRoot = path.join(tempDir, 'written-workspace');
+
+      await writeWorkspaceViewState(workspaceRoot, {
+        version: 1,
+        name: 'written-workspace',
+        context: null,
+        links: {},
+      });
+
+      expect(fs.existsSync(getWorkspaceMetadataDir(workspaceRoot))).toBe(true);
+      expect(fs.existsSync(getWorkspaceViewStatePath(workspaceRoot))).toBe(true);
+      expect(fs.existsSync(path.join(workspaceRoot, 'workspace.yaml'))).toBe(false);
+      await expect(isWorkspaceRoot(workspaceRoot)).resolves.toBe(true);
+      expectSameExistingPath(await findWorkspaceRoot(workspaceRoot), workspaceRoot);
+    });
+
     it('detects a workspace even when a linked path has no repo-local openspec state', async () => {
       const workspaceRoot = createWorkspaceRoot();
       const linkedPath = path.join(workspaceRoot, 'external-folder');