gmc-openspec 1.1.0 → 1.4.1

package/dist/core/workspace/open-surface.d.ts

@@ -1,7 +1,22 @@
-import { WorkspaceLocalState, WorkspaceSharedState } from './foundation.js';
+import { WorkspaceViewState } from './foundation.js';
 export declare const WORKSPACE_GUIDANCE_START_MARKER = "<!-- OPENSPEC:WORKSPACE-GUIDANCE:START -->";
 export declare const WORKSPACE_GUIDANCE_END_MARKER = "<!-- OPENSPEC:WORKSPACE-GUIDANCE:END -->";
-export declare const WORKSPACE_GUIDANCE_BODY = "# OpenSpec Workspace Guidance\n\nThis directory is an OpenSpec workspace for planning across linked repos or folders.\n\n- Use `changes/` for workspace-level planning.\n- Linked repos and folders are available for exploration and planning.\n- Repo or folder visibility supports exploration and planning.\n- Make implementation edits after the user explicitly asks for implementation work.\n- Treat linked repos and folders as the implementation homes for their owned code.\n- Use OpenSpec workspace commands instead of hand-editing `.openspec-workspace/*.yaml`.";
+export declare const WORKSPACE_OPEN_ROOT_FOLDER_LABEL = "OpenSpec workspace";
+export declare const WORKSPACE_OPEN_INITIATIVE_FOLDER_LABEL = "Initiative context";
+export declare const WORKSPACE_GUIDANCE_BODY = "# OpenSpec Workspace Guidance\n\nThis directory is an OpenSpec workspace: a local working view over context stores, initiatives, repos, and folders.\n\n- Use this workspace to open the local view of coordinated work.\n- Use initiatives for durable cross-team or cross-repo intent, decisions, requirements, and coordination context.\n- Use repo-local OpenSpec changes for implementation plans owned by a repo or team.\n- Use linked repos and folders to inspect context, understand ownership, and make edits in the place that owns the work.\n- Keep workspace-local files focused on local paths, opener state, agent setup, and other machine-specific view state.\n- Use OpenSpec workspace commands instead of hand-editing `workspace.yaml`.\n- 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 {
+    contextStore: {
+        id: string;
+        root: string;
+    };
+    initiative: {
+        id: string;
+        title: string;
+        root: string;
+        metadataPath: string;
+        storePath: string;
+    };
+}
 export interface WorkspaceOpenLink {
     name: string;
     path: string;
@@ -15,10 +30,16 @@ export interface WorkspaceOpenSurfaceLinks {
     links: WorkspaceOpenLink[];
     skipped: WorkspaceSkippedOpenLink[];
 }
-export declare function buildWorkspaceGuidanceBlock(): string;
-export declare function applyWorkspaceGuidanceBlock(existingContent: string): string;
-export declare function buildWorkspaceCodeWorkspaceContent(links: WorkspaceOpenLink[]): string;
-export declare function writeWorkspaceCodeWorkspaceFile(codeWorkspacePath: string, links: WorkspaceOpenLink[]): Promise<void>;
-export declare function resolveWorkspaceOpenLinks(sharedState: WorkspaceSharedState, localState: WorkspaceLocalState): Promise<WorkspaceOpenSurfaceLinks>;
-export declare function syncWorkspaceOpenSurface(workspaceRoot: string, sharedState: WorkspaceSharedState, localState: WorkspaceLocalState): Promise<WorkspaceOpenSurfaceLinks>;
+export interface WorkspaceOpenSurfaceGeneration {
+    agentsPath: string;
+    codeWorkspacePath: string;
+}
+export declare function buildWorkspaceGuidanceBlock(viewState?: WorkspaceViewState, resolvedContext?: WorkspaceOpenResolvedContext | null): string;
+export declare function applyWorkspaceGuidanceBlock(existingContent: string, viewState?: WorkspaceViewState, resolvedContext?: WorkspaceOpenResolvedContext | null): string;
+export declare function buildWorkspaceCodeWorkspaceContent(links: WorkspaceOpenLink[], resolvedContext?: WorkspaceOpenResolvedContext | null): string;
+export declare function writeWorkspaceCodeWorkspaceFile(codeWorkspacePath: string, links: WorkspaceOpenLink[], resolvedContext?: WorkspaceOpenResolvedContext | null): Promise<void>;
+export declare function resolveWorkspaceOpenLinks(viewState: WorkspaceViewState): Promise<WorkspaceOpenSurfaceLinks>;
+export declare function syncWorkspaceOpenSurface(workspaceRoot: string, viewState: WorkspaceViewState, resolvedContext?: WorkspaceOpenResolvedContext | null): Promise<WorkspaceOpenSurfaceLinks & {
+    generated: WorkspaceOpenSurfaceGeneration;
+}>;
 //# sourceMappingURL=open-surface.d.ts.map

package/dist/core/workspace/open-surface.js

@@ -1,20 +1,23 @@
 import * as nodeFs from 'node:fs';
 import * as path from 'node:path';
 import { FileSystemUtils } from '../../utils/file-system.js';
-import { getWorkspaceCodeWorkspacePath, getWorkspacePortableIgnorePatterns, } from './foundation.js';
+import { getWorkspaceContextInitiativeId, getWorkspaceCodeWorkspacePath, getWorkspaceCodeWorkspaceFileName, } from './foundation.js';
 const fs = nodeFs.promises;
 export const WORKSPACE_GUIDANCE_START_MARKER = '<!-- OPENSPEC:WORKSPACE-GUIDANCE:START -->';
 export const WORKSPACE_GUIDANCE_END_MARKER = '<!-- OPENSPEC:WORKSPACE-GUIDANCE:END -->';
+export const WORKSPACE_OPEN_ROOT_FOLDER_LABEL = 'OpenSpec workspace';
+export const WORKSPACE_OPEN_INITIATIVE_FOLDER_LABEL = 'Initiative context';
 export const WORKSPACE_GUIDANCE_BODY = `# OpenSpec Workspace Guidance
 
-This directory is an OpenSpec workspace for planning across linked repos or folders.
+This directory is an OpenSpec workspace: a local working view over context stores, initiatives, repos, and folders.
 
-- Use \`changes/\` for workspace-level planning.
-- Linked repos and folders are available for exploration and planning.
-- Repo or folder visibility supports exploration and planning.
-- Make implementation edits after the user explicitly asks for implementation work.
-- Treat linked repos and folders as the implementation homes for their owned code.
-- Use OpenSpec workspace commands instead of hand-editing \`.openspec-workspace/*.yaml\`.`;
+- Use this workspace to open the local view of coordinated work.
+- Use initiatives for durable cross-team or cross-repo intent, decisions, requirements, and coordination context.
+- 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\`.
+- 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.`;
 async function fileExists(filePath) {
     try {
         return (await fs.stat(filePath)).isFile();
@@ -31,13 +34,72 @@ async function directoryExists(dirPath) {
         return false;
     }
 }
-export function buildWorkspaceGuidanceBlock() {
+function formatGuidancePathList(items) {
+    if (items.length === 0) {
+        return '- None selected yet.';
+    }
+    return items.map((item) => `- ${item.label}: ${item.path}`).join('\n');
+}
+function buildWorkspaceContextGuidance(viewState, resolvedContext) {
+    const linkedRoots = Object.entries(viewState.links)
+        .filter((entry) => typeof entry[1] === 'string')
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([name, linkPath]) => ({ label: name, path: linkPath }));
+    if (!viewState.context) {
+        return `## Local View
+
+This workspace is not bound to an initiative. It is still a first-class local view over selected repos or folders.
+
+## Linked Implementation Context
+
+${formatGuidancePathList(linkedRoots)}`;
+    }
+    const storedContextSelector = viewState.context.store.selector;
+    const storedContextStore = viewState.context
+        ? storedContextSelector?.kind === 'path'
+            ? `${viewState.context.store.id} via ${storedContextSelector.path}`
+            : viewState.context.store.id
+        : null;
+    const storedInitiativeId = viewState.context
+        ? getWorkspaceContextInitiativeId(viewState.context)
+        : null;
+    const contextLines = resolvedContext
+        ? [
+            `- Context store: ${resolvedContext.contextStore.id} (${resolvedContext.contextStore.root})`,
+            `- Initiative: ${resolvedContext.initiative.id} (${resolvedContext.initiative.root})`,
+            `- Initiative title: ${resolvedContext.initiative.title}`,
+            `- Initiative metadata: ${resolvedContext.initiative.metadataPath}`,
+            '- Broader context may exist in the context store, but this workspace opens the selected initiative by default.',
+        ].join('\n')
+        : [
+            `- Context store: ${storedContextStore}`,
+            `- Initiative: ${storedInitiativeId}`,
+            '- Run `openspec workspace open --json` to refresh resolved local paths for this view.',
+        ].join('\n');
+    return `## Selected Initiative Context
+
+${contextLines}
+
+## Advisory Edit Boundaries
+
+- Treat initiative and context-store files as shared coordination context.
+- Treat linked repos and folders as local implementation context when the user has selected them.
+- These boundaries are advisory in this OpenSpec version; use judgment and repo ownership when editing.
+
+## Linked Implementation Context
+
+${formatGuidancePathList(linkedRoots)}`;
+}
+export function buildWorkspaceGuidanceBlock(viewState, resolvedContext) {
+    const contextGuidance = viewState
+        ? `\n\n${buildWorkspaceContextGuidance(viewState, resolvedContext)}`
+        : '';
     return `${WORKSPACE_GUIDANCE_START_MARKER}
-${WORKSPACE_GUIDANCE_BODY}
+${WORKSPACE_GUIDANCE_BODY}${contextGuidance}
 ${WORKSPACE_GUIDANCE_END_MARKER}`;
 }
-export function applyWorkspaceGuidanceBlock(existingContent) {
-    const block = buildWorkspaceGuidanceBlock();
+export function applyWorkspaceGuidanceBlock(existingContent, viewState, resolvedContext) {
+    const block = buildWorkspaceGuidanceBlock(viewState, resolvedContext);
     const startIndex = existingContent.indexOf(WORKSPACE_GUIDANCE_START_MARKER);
     const endIndex = existingContent.indexOf(WORKSPACE_GUIDANCE_END_MARKER);
     if (startIndex !== -1 || endIndex !== -1) {
@@ -57,26 +119,35 @@ export function applyWorkspaceGuidanceBlock(existingContent) {
     }
     return `${existingContent.trimEnd()}\n\n${block}\n`;
 }
-export function buildWorkspaceCodeWorkspaceContent(links) {
+export function buildWorkspaceCodeWorkspaceContent(links, resolvedContext) {
     const folders = [
-        {
-            path: '.',
-        },
         ...links.map((link) => ({
             name: link.name,
             path: link.path,
         })),
+        ...(resolvedContext
+            ? [
+                {
+                    name: WORKSPACE_OPEN_INITIATIVE_FOLDER_LABEL,
+                    path: resolvedContext.initiative.root,
+                },
+            ]
+            : []),
+        {
+            name: WORKSPACE_OPEN_ROOT_FOLDER_LABEL,
+            path: '.',
+        },
     ];
     return `${JSON.stringify({ folders }, null, 2)}\n`;
 }
-export async function writeWorkspaceCodeWorkspaceFile(codeWorkspacePath, links) {
-    await FileSystemUtils.writeFile(codeWorkspacePath, buildWorkspaceCodeWorkspaceContent(links));
+export async function writeWorkspaceCodeWorkspaceFile(codeWorkspacePath, links, resolvedContext) {
+    await FileSystemUtils.writeFile(codeWorkspacePath, buildWorkspaceCodeWorkspaceContent(links, resolvedContext));
 }
-export async function resolveWorkspaceOpenLinks(sharedState, localState) {
+export async function resolveWorkspaceOpenLinks(viewState) {
     const links = [];
     const skipped = [];
-    for (const linkName of Object.keys(sharedState.links).sort((a, b) => a.localeCompare(b))) {
-        const localPath = localState.paths[linkName] ?? null;
+    for (const linkName of Object.keys(viewState.links).sort((a, b) => a.localeCompare(b))) {
+        const localPath = viewState.links[linkName] ?? null;
         if (!localPath) {
             skipped.push({
                 name: linkName,
@@ -100,38 +171,45 @@ export async function resolveWorkspaceOpenLinks(sharedState, localState) {
     }
     return { links, skipped };
 }
-async function syncWorkspaceGuidance(workspaceRoot) {
+async function syncWorkspaceGuidance(workspaceRoot, viewState, resolvedContext) {
     const agentsPath = path.join(workspaceRoot, 'AGENTS.md');
     const existingContent = (await fileExists(agentsPath))
         ? await fs.readFile(agentsPath, 'utf-8')
         : '';
-    await FileSystemUtils.writeFile(agentsPath, applyWorkspaceGuidanceBlock(existingContent));
+    await FileSystemUtils.writeFile(agentsPath, applyWorkspaceGuidanceBlock(existingContent, viewState, resolvedContext));
+    return agentsPath;
 }
-async function syncWorkspaceCodeWorkspace(workspaceRoot, sharedState, links) {
-    await writeWorkspaceCodeWorkspaceFile(getWorkspaceCodeWorkspacePath(workspaceRoot, sharedState.name), links);
+async function syncWorkspaceCodeWorkspace(workspaceRoot, viewState, links, resolvedContext) {
+    const codeWorkspacePath = getWorkspaceCodeWorkspacePath(workspaceRoot, viewState.name);
+    await writeWorkspaceCodeWorkspaceFile(codeWorkspacePath, links, resolvedContext);
+    return codeWorkspacePath;
 }
-async function syncWorkspaceIgnoreRules(workspaceRoot, workspaceName) {
+async function cleanupLegacyWorkspaceIgnoreRules(workspaceRoot, workspaceName) {
     const gitignorePath = path.join(workspaceRoot, '.gitignore');
-    const patterns = getWorkspacePortableIgnorePatterns(workspaceName);
-    const existingContent = (await fileExists(gitignorePath))
-        ? await fs.readFile(gitignorePath, 'utf-8')
-        : '';
-    const existingLines = new Set(existingContent
-        .split(/\r?\n/u)
-        .map((line) => line.trim())
-        .filter((line) => line.length > 0));
-    const missingPatterns = patterns.filter((pattern) => !existingLines.has(pattern));
-    if (missingPatterns.length === 0) {
+    if (!(await fileExists(gitignorePath))) {
         return;
     }
-    const prefix = existingContent.length > 0 && !existingContent.endsWith('\n') ? '\n' : '';
-    await FileSystemUtils.writeFile(gitignorePath, `${existingContent}${prefix}${missingPatterns.join('\n')}\n`);
+    const legacyGeneratedPattern = getWorkspaceCodeWorkspaceFileName(workspaceName);
+    const existingContent = await fs.readFile(gitignorePath, 'utf-8');
+    const existingLines = existingContent.split(/\r?\n/u);
+    const nonEmptyLines = existingLines.filter((line) => line.trim().length > 0);
+    const isPureLegacyGeneratedFile = nonEmptyLines.length === 1 && nonEmptyLines[0]?.trim() === legacyGeneratedPattern;
+    if (!isPureLegacyGeneratedFile) {
+        return;
+    }
+    await fs.rm(gitignorePath, { force: true });
 }
-export async function syncWorkspaceOpenSurface(workspaceRoot, sharedState, localState) {
-    const openLinks = await resolveWorkspaceOpenLinks(sharedState, localState);
-    await syncWorkspaceGuidance(workspaceRoot);
-    await syncWorkspaceCodeWorkspace(workspaceRoot, sharedState, openLinks.links);
-    await syncWorkspaceIgnoreRules(workspaceRoot, sharedState.name);
-    return openLinks;
+export async function syncWorkspaceOpenSurface(workspaceRoot, viewState, resolvedContext) {
+    const openLinks = await resolveWorkspaceOpenLinks(viewState);
+    const agentsPath = await syncWorkspaceGuidance(workspaceRoot, viewState, resolvedContext);
+    const codeWorkspacePath = await syncWorkspaceCodeWorkspace(workspaceRoot, viewState, openLinks.links, resolvedContext);
+    await cleanupLegacyWorkspaceIgnoreRules(workspaceRoot, viewState.name);
+    return {
+        ...openLinks,
+        generated: {
+            agentsPath,
+            codeWorkspacePath,
+        },
+    };
 }
 //# sourceMappingURL=open-surface.js.map

package/dist/core/workspace/openers.js

@@ -9,8 +9,8 @@ const WORKSPACE_OPENER_CHOICE_DEFINITIONS = [
         executable: 'code',
     },
     {
-        value: 'codex',
-        label: 'Codex',
+        value: 'codex-cli',
+        label: 'codex-cli',
         executable: 'codex',
     },
     {
@@ -74,23 +74,28 @@ export function isWorkspaceExecutableAvailable(executable, options = {}) {
     return false;
 }
 export function getWorkspaceOpenerExecutable(opener) {
+    const openerId = opener.id;
     if (opener.kind === 'editor') {
         return 'code';
     }
-    if (opener.id === 'github-copilot') {
+    if (openerId === 'github-copilot') {
         return 'code';
     }
+    if (openerId === 'codex-cli' || openerId === 'codex') {
+        return 'codex';
+    }
     return opener.id;
 }
 export function getWorkspaceOpenerLabel(opener) {
+    const openerId = opener.id;
     if (opener.kind === 'editor') {
         return 'VS Code editor';
     }
-    if (opener.id === 'github-copilot') {
+    if (openerId === 'github-copilot') {
         return 'GitHub Copilot in VS Code';
     }
-    if (opener.id === 'codex') {
-        return 'Codex';
+    if (openerId === 'codex-cli' || openerId === 'codex') {
+        return 'codex-cli';
     }
     return 'Claude';
 }

package/dist/core/workspace/registry.d.ts

@@ -0,0 +1,24 @@
+export declare const MANAGED_WORKSPACES_DIR_NAME = "workspaces";
+export declare const WORKSPACE_REGISTRY_FILE_NAME = "registry.yaml";
+export interface WorkspaceRegistryState {
+    version: 1;
+    workspaces: Record<string, string>;
+}
+export interface WorkspaceRegistryEntry {
+    name: string;
+    workspaceRoot: string;
+}
+export interface WorkspacePathOptions {
+    globalDataDir?: string;
+}
+export declare function getManagedWorkspacesDir(options?: WorkspacePathOptions): string;
+export declare function getManagedWorkspaceRoot(workspaceName: string, options?: WorkspacePathOptions): string;
+export declare function getWorkspaceRegistryPath(options?: WorkspacePathOptions): string;
+export declare function parseWorkspaceRegistryState(content: string): WorkspaceRegistryState;
+export declare function serializeWorkspaceRegistryState(state: WorkspaceRegistryState): string;
+export declare function listWorkspaceRegistryEntries(registry: WorkspaceRegistryState): WorkspaceRegistryEntry[];
+export declare function listKnownWorkspaceEntries(options?: WorkspacePathOptions): Promise<WorkspaceRegistryEntry[]>;
+export declare function listManagedWorkspaceEntries(options?: WorkspacePathOptions): Promise<WorkspaceRegistryEntry[]>;
+export declare function readWorkspaceRegistryState(options?: WorkspacePathOptions): Promise<WorkspaceRegistryState | null>;
+export declare function writeWorkspaceRegistryState(state: WorkspaceRegistryState, options?: WorkspacePathOptions): Promise<void>;
+//# sourceMappingURL=registry.d.ts.map

package/dist/core/workspace/registry.js

@@ -0,0 +1,146 @@
+import * as nodeFs from 'node:fs';
+import { z } from 'zod';
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+import { getGlobalDataDir } from '../global-config.js';
+import { FileSystemUtils } from '../../utils/file-system.js';
+import { validateWorkspaceName } from './foundation.js';
+import { isWorkspaceRoot, readWorkspaceViewState } from './state-io.js';
+const fs = nodeFs.promises;
+export const MANAGED_WORKSPACES_DIR_NAME = 'workspaces';
+export const WORKSPACE_REGISTRY_FILE_NAME = 'registry.yaml';
+function joinWorkspacePath(basePath, ...segments) {
+    return FileSystemUtils.joinPath(basePath, ...segments);
+}
+async function pathIsFile(filePath) {
+    try {
+        return (await fs.stat(filePath)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+async function pathIsDirectory(dirPath) {
+    try {
+        return (await fs.stat(dirPath)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function formatZodIssues(error) {
+    return error.issues
+        .map((issue) => {
+        const location = issue.path.length > 0 ? issue.path.join('.') : 'root';
+        return `${location}: ${issue.message}`;
+    })
+        .join('; ');
+}
+function parseYamlObject(content, label) {
+    try {
+        return parseYaml(content);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Invalid ${label}: ${message}`);
+    }
+}
+function assertValidMapKeys(keys, validator, label) {
+    for (const key of keys) {
+        try {
+            validator(key);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`Invalid ${label} '${key}': ${message}`);
+        }
+    }
+}
+const RegistryStateSchema = z.object({
+    version: z.literal(1),
+    workspaces: z.record(z.string(), z.string()),
+}).strict();
+export function getManagedWorkspacesDir(options = {}) {
+    return joinWorkspacePath(options.globalDataDir ?? getGlobalDataDir(), MANAGED_WORKSPACES_DIR_NAME);
+}
+export function getManagedWorkspaceRoot(workspaceName, options = {}) {
+    validateWorkspaceName(workspaceName);
+    return joinWorkspacePath(getManagedWorkspacesDir(options), workspaceName);
+}
+export function getWorkspaceRegistryPath(options = {}) {
+    return joinWorkspacePath(getManagedWorkspacesDir(options), WORKSPACE_REGISTRY_FILE_NAME);
+}
+export function parseWorkspaceRegistryState(content) {
+    const raw = parseYamlObject(content, 'workspace registry state');
+    const result = RegistryStateSchema.safeParse(raw);
+    if (!result.success) {
+        throw new Error(`Invalid workspace registry state: ${formatZodIssues(result.error)}`);
+    }
+    assertValidMapKeys(Object.keys(result.data.workspaces), validateWorkspaceName, 'workspace registry name');
+    return {
+        version: 1,
+        workspaces: result.data.workspaces,
+    };
+}
+export function serializeWorkspaceRegistryState(state) {
+    assertValidMapKeys(Object.keys(state.workspaces), validateWorkspaceName, 'workspace registry name');
+    for (const [workspaceName, workspaceRoot] of Object.entries(state.workspaces)) {
+        if (typeof workspaceRoot !== 'string') {
+            throw new Error(`Invalid workspace registry entry '${workspaceName}': path must be a string`);
+        }
+    }
+    return stringifyYaml({
+        version: 1,
+        workspaces: state.workspaces,
+    });
+}
+export function listWorkspaceRegistryEntries(registry) {
+    return Object.entries(registry.workspaces)
+        .map(([name, workspaceRoot]) => ({ name, workspaceRoot }))
+        .sort((a, b) => a.name.localeCompare(b.name));
+}
+export async function listKnownWorkspaceEntries(options = {}) {
+    const legacyRegistry = await readWorkspaceRegistryState(options);
+    const workspaces = new Map(Object.entries(legacyRegistry?.workspaces ?? {}));
+    for (const entry of await listManagedWorkspaceEntries(options)) {
+        workspaces.set(entry.name, entry.workspaceRoot);
+    }
+    return [...workspaces.entries()]
+        .map(([name, workspaceRoot]) => ({ name, workspaceRoot }))
+        .sort((a, b) => a.name.localeCompare(b.name));
+}
+export async function listManagedWorkspaceEntries(options = {}) {
+    const workspacesDir = getManagedWorkspacesDir(options);
+    if (!(await pathIsDirectory(workspacesDir))) {
+        return [];
+    }
+    const entries = await fs.readdir(workspacesDir, { withFileTypes: true });
+    const workspaces = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory()) {
+            continue;
+        }
+        const workspaceRoot = FileSystemUtils.canonicalizeExistingPath(joinWorkspacePath(workspacesDir, entry.name));
+        if (!(await isWorkspaceRoot(workspaceRoot))) {
+            continue;
+        }
+        try {
+            const state = await readWorkspaceViewState(workspaceRoot);
+            workspaces.push({ name: state.name, workspaceRoot });
+        }
+        catch {
+            workspaces.push({ name: entry.name, workspaceRoot });
+        }
+    }
+    return workspaces.sort((a, b) => a.name.localeCompare(b.name));
+}
+export async function readWorkspaceRegistryState(options = {}) {
+    const registryPath = getWorkspaceRegistryPath(options);
+    if (!(await pathIsFile(registryPath))) {
+        return null;
+    }
+    return parseWorkspaceRegistryState(await fs.readFile(registryPath, 'utf-8'));
+}
+export async function writeWorkspaceRegistryState(state, options = {}) {
+    await FileSystemUtils.writeFile(getWorkspaceRegistryPath(options), serializeWorkspaceRegistryState(state));
+}
+//# sourceMappingURL=registry.js.map

package/dist/core/workspace/skills.d.ts

@@ -1,6 +1,6 @@
 import { type AIToolOption } from '../config.js';
 import { type Delivery, type Profile } from '../global-config.js';
-import type { WorkspaceLocalState, WorkspaceSkillState } from './foundation.js';
+import type { WorkspaceSkillState } from './foundation.js';
 export interface WorkspaceSkillAgentResult {
     tool_id: string;
     name: string;
@@ -43,7 +43,9 @@ export declare function getCurrentWorkspaceSkillProfileSelection(): {
     delivery: Delivery;
     workflow_ids: string[];
 };
-export declare function hasWorkspaceSkillProfileDrift(localState: Pick<WorkspaceLocalState, 'workspace_skills'> | null | undefined): boolean;
+export declare function hasWorkspaceSkillProfileDrift(state: {
+    workspace_skills?: WorkspaceSkillState;
+} | null | undefined): boolean;
 export declare function getWorkspaceSkillCapableTools(): WorkspaceSkillCapableTool[];
 export declare function getWorkspaceSkillToolIds(): string[];
 export declare function parseWorkspaceSkillToolsValue(rawTools: string): string[];

package/dist/core/workspace/skills.js

@@ -44,8 +44,8 @@ function arraysEqual(left, right) {
     }
     return [...leftSet].every((value) => rightSet.has(value));
 }
-export function hasWorkspaceSkillProfileDrift(localState) {
-    const workspaceSkills = localState?.workspace_skills;
+export function hasWorkspaceSkillProfileDrift(state) {
+    const workspaceSkills = state?.workspace_skills;
     if (!workspaceSkills) {
         return false;
     }

package/dist/core/workspace/state-io.d.ts

@@ -0,0 +1,10 @@
+import { type WorkspaceViewState } from './foundation.js';
+export declare function isWorkspaceRoot(candidateRoot: string): Promise<boolean>;
+export declare function findWorkspaceRoot(startPath?: string): Promise<string | null>;
+export declare function workspaceStateFileExistsSync(workspaceRoot: string): boolean;
+export declare function readWorkspaceViewState(workspaceRoot: string): Promise<WorkspaceViewState>;
+export declare function readWorkspaceViewStateSync(workspaceRoot: string): WorkspaceViewState | null;
+export declare function readOptionalWorkspaceViewState(workspaceRoot: string): Promise<WorkspaceViewState | null>;
+export declare function writeWorkspaceViewState(workspaceRoot: string, state: WorkspaceViewState): Promise<void>;
+export declare function workspaceChangesDirExists(workspaceRoot: string): Promise<boolean>;
+//# sourceMappingURL=state-io.d.ts.map

package/dist/core/workspace/state-io.js

@@ -0,0 +1,119 @@
+import * as nodeFs from 'node:fs';
+import * as path from 'node:path';
+import { FileSystemUtils } from '../../utils/file-system.js';
+import { getWorkspaceChangesDir, getWorkspaceViewStatePath, parseWorkspaceViewState, serializeWorkspaceViewState, } from './foundation.js';
+import { getWorkspaceLegacyLocalStatePath, getWorkspaceLegacySharedStatePath, parseWorkspaceLocalState, parseWorkspaceSharedState, workspaceStatePartsToViewState, } from './legacy-state.js';
+const fs = nodeFs.promises;
+async function pathIsFile(filePath) {
+    try {
+        return (await fs.stat(filePath)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+async function pathIsDirectory(dirPath) {
+    try {
+        return (await fs.stat(dirPath)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function pathExistsAsFile(filePath) {
+    try {
+        return nodeFs.statSync(filePath).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function isFileNotFoundError(error) {
+    return (typeof error === 'object' &&
+        error !== null &&
+        'code' in error &&
+        error.code === 'ENOENT');
+}
+async function getSearchStartDirectory(startPath) {
+    const resolvedStart = path.resolve(startPath);
+    try {
+        const stats = await fs.stat(resolvedStart);
+        const searchStart = stats.isDirectory() ? resolvedStart : path.dirname(resolvedStart);
+        return FileSystemUtils.canonicalizeExistingPath(searchStart);
+    }
+    catch {
+        return resolvedStart;
+    }
+}
+export async function isWorkspaceRoot(candidateRoot) {
+    return ((await pathIsFile(getWorkspaceViewStatePath(candidateRoot))) ||
+        (await pathIsFile(getWorkspaceLegacySharedStatePath(candidateRoot))));
+}
+export async function findWorkspaceRoot(startPath = process.cwd()) {
+    let currentDir = await getSearchStartDirectory(startPath);
+    while (true) {
+        if (await isWorkspaceRoot(currentDir)) {
+            return FileSystemUtils.canonicalizeExistingPath(currentDir);
+        }
+        const parentDir = path.dirname(currentDir);
+        if (parentDir === currentDir) {
+            return null;
+        }
+        currentDir = parentDir;
+    }
+}
+export function workspaceStateFileExistsSync(workspaceRoot) {
+    return (pathExistsAsFile(getWorkspaceViewStatePath(workspaceRoot)) ||
+        pathExistsAsFile(getWorkspaceLegacySharedStatePath(workspaceRoot)));
+}
+export async function readWorkspaceViewState(workspaceRoot) {
+    const viewStatePath = getWorkspaceViewStatePath(workspaceRoot);
+    if (await pathIsFile(viewStatePath)) {
+        return parseWorkspaceViewState(await fs.readFile(viewStatePath, 'utf-8'));
+    }
+    const legacySharedState = parseWorkspaceSharedState(await fs.readFile(getWorkspaceLegacySharedStatePath(workspaceRoot), 'utf-8'));
+    let legacyLocalState = null;
+    try {
+        legacyLocalState = parseWorkspaceLocalState(await fs.readFile(getWorkspaceLegacyLocalStatePath(workspaceRoot), 'utf-8'));
+    }
+    catch (error) {
+        if (!isFileNotFoundError(error)) {
+            throw error;
+        }
+    }
+    return workspaceStatePartsToViewState(legacySharedState, legacyLocalState);
+}
+export function readWorkspaceViewStateSync(workspaceRoot) {
+    const viewStatePath = getWorkspaceViewStatePath(workspaceRoot);
+    if (pathExistsAsFile(viewStatePath)) {
+        return parseWorkspaceViewState(nodeFs.readFileSync(viewStatePath, 'utf-8'));
+    }
+    const legacySharedPath = getWorkspaceLegacySharedStatePath(workspaceRoot);
+    if (!pathExistsAsFile(legacySharedPath)) {
+        return null;
+    }
+    const legacySharedState = parseWorkspaceSharedState(nodeFs.readFileSync(legacySharedPath, 'utf-8'));
+    const legacyLocalPath = getWorkspaceLegacyLocalStatePath(workspaceRoot);
+    const legacyLocalState = pathExistsAsFile(legacyLocalPath)
+        ? parseWorkspaceLocalState(nodeFs.readFileSync(legacyLocalPath, 'utf-8'))
+        : null;
+    return workspaceStatePartsToViewState(legacySharedState, legacyLocalState);
+}
+export async function readOptionalWorkspaceViewState(workspaceRoot) {
+    try {
+        return await readWorkspaceViewState(workspaceRoot);
+    }
+    catch (error) {
+        if (isFileNotFoundError(error)) {
+            return null;
+        }
+        throw error;
+    }
+}
+export async function writeWorkspaceViewState(workspaceRoot, state) {
+    await FileSystemUtils.writeFile(getWorkspaceViewStatePath(workspaceRoot), serializeWorkspaceViewState(state));
+}
+export async function workspaceChangesDirExists(workspaceRoot) {
+    return pathIsDirectory(getWorkspaceChangesDir(workspaceRoot));
+}
+//# sourceMappingURL=state-io.js.map