@fission-ai/openspec 1.3.1 → 1.4.1

package/dist/core/context-store/registry.js

@@ -0,0 +1,229 @@
+import * as fs from 'node:fs/promises';
+import { getContextStoreMetadataPath, getContextStoreMetadataDir, listContextStoreRegistryEntries, readContextStoreRegistryState, readOptionalContextStoreMetadataState, resolveGitContextStoreBackendConfig, updateContextStoreRegistryState, validateContextStoreId, writeContextStoreMetadataState, } from './foundation.js';
+import { ContextStoreError } from './errors.js';
+import { FileSystemUtils } from '../../utils/file-system.js';
+export function getStoreRootForBackend(backend) {
+    switch (backend.type) {
+        case 'git':
+            return backend.local_path;
+    }
+}
+function normalizePathForComparison(targetPath) {
+    try {
+        return FileSystemUtils.canonicalizeExistingPath(targetPath);
+    }
+    catch {
+        return targetPath;
+    }
+}
+export function assertNoRegisteredStoreConflict(registry, id, backend) {
+    const nextPath = normalizePathForComparison(getStoreRootForBackend(backend));
+    for (const entry of listContextStoreRegistryEntries(registry ?? { version: 1, stores: {} })) {
+        const entryPath = normalizePathForComparison(getStoreRootForBackend(entry.backend));
+        if (entry.id === id && entryPath === nextPath) {
+            continue;
+        }
+        if (entry.id === id) {
+            throw new ContextStoreError(`Context store '${id}' is already registered at ${getStoreRootForBackend(entry.backend)}.`, 'context_store_id_conflict', {
+                target: 'context_store.id',
+                fix: 'Use the existing registration or choose a different context store id.',
+            });
+        }
+        if (entryPath === nextPath) {
+            throw new ContextStoreError(`Context store path is already registered as '${entry.id}'.`, 'context_store_path_conflict', {
+                target: 'context_store.root',
+                fix: `Use the existing '${entry.id}' registration or choose a different path.`,
+            });
+        }
+    }
+}
+function withRegisteredStore(registry, id, backend) {
+    assertNoRegisteredStoreConflict(registry, id, backend);
+    const stores = {
+        ...(registry?.stores ?? {}),
+        [id]: {
+            backend,
+        },
+    };
+    return {
+        version: 1,
+        stores: Object.fromEntries(Object.entries(stores).sort(([leftId], [rightId]) => leftId.localeCompare(rightId))),
+    };
+}
+function getRegisteredStoreOrThrow(registry, id) {
+    const entry = registry?.stores[id];
+    if (!entry) {
+        throw new ContextStoreError(`Unknown context store '${id}'`, 'context_store_not_found', {
+            target: 'context_store.id',
+            fix: 'Run openspec context-store list to see registered stores.',
+        });
+    }
+    return {
+        id,
+        backend: entry.backend,
+    };
+}
+function contextStoreBackendsMatch(actual, expected) {
+    return (actual.type === expected.type &&
+        normalizePathForComparison(actual.local_path) ===
+            normalizePathForComparison(expected.local_path) &&
+        actual.remote === expected.remote &&
+        actual.branch === expected.branch);
+}
+function assertExpectedRegisteredBackend(id, actual, expected) {
+    if (!expected || contextStoreBackendsMatch(actual, expected))
+        return;
+    throw new ContextStoreError(`Context store '${id}' changed before cleanup completed.`, 'context_store_registry_changed', {
+        target: 'context_store.registry',
+        fix: 'Retry the cleanup command after reviewing the current context-store registration.',
+    });
+}
+function withoutRegisteredStore(registry, id, expectedBackend) {
+    const removed = getRegisteredStoreOrThrow(registry, id);
+    assertExpectedRegisteredBackend(id, removed.backend, expectedBackend);
+    const stores = { ...(registry?.stores ?? {}) };
+    delete stores[id];
+    return {
+        removed,
+        next: {
+            version: 1,
+            stores: Object.fromEntries(Object.entries(stores).sort(([leftId], [rightId]) => leftId.localeCompare(rightId))),
+        },
+    };
+}
+async function ensureStoreMetadata(storeRoot, id, options) {
+    const metadata = await readOptionalContextStoreMetadataState(storeRoot);
+    if (!metadata) {
+        if (!options.writeIfMissing) {
+            throw new ContextStoreError(`Registered context store '${id}' is missing metadata at ${getContextStoreMetadataPath(storeRoot)}`, 'context_store_metadata_missing', {
+                target: 'context_store.metadata',
+                fix: `Create ${getContextStoreMetadataPath(storeRoot)} or rerun context-store register.`,
+            });
+        }
+        await writeContextStoreMetadataState(storeRoot, {
+            version: 1,
+            id,
+        });
+        return true;
+    }
+    if (metadata.id !== id) {
+        throw new ContextStoreError(`Context store metadata id '${metadata.id}' does not match registered id '${id}'`, 'context_store_metadata_id_mismatch', {
+            target: 'context_store.metadata',
+            fix: 'Repair the local registry or store metadata so the ids match.',
+        });
+    }
+    return false;
+}
+export async function commitContextStoreRegistration(input) {
+    const id = validateContextStoreId(input.id);
+    const backend = input.backend;
+    const storeRoot = getStoreRootForBackend(backend);
+    let metadataCreated = false;
+    try {
+        metadataCreated = await ensureStoreMetadata(storeRoot, id, {
+            writeIfMissing: input.writeMetadataIfMissing,
+        });
+        await updateContextStoreRegistryState((registry) => withRegisteredStore(registry, id, backend), { globalDataDir: input.globalDataDir });
+    }
+    catch (error) {
+        if (metadataCreated) {
+            await fs.rm(getContextStoreMetadataPath(storeRoot), { force: true });
+            await fs.rmdir(getContextStoreMetadataDir(storeRoot)).catch(() => undefined);
+        }
+        throw error;
+    }
+    return {
+        id,
+        storeRoot,
+        backend,
+        metadataCreated,
+    };
+}
+export async function registerContextStore(input) {
+    const id = validateContextStoreId(input.id);
+    const backend = await resolveGitContextStoreBackendConfig({
+        localPath: input.localPath,
+        ...(input.remote !== undefined ? { remote: input.remote } : {}),
+        ...(input.branch !== undefined ? { branch: input.branch } : {}),
+    }, input.cwd);
+    const storeRoot = getStoreRootForBackend(backend);
+    const committed = await commitContextStoreRegistration({
+        id,
+        backend,
+        writeMetadataIfMissing: true,
+        ...(input.globalDataDir ? { globalDataDir: input.globalDataDir } : {}),
+    });
+    return {
+        id: committed.id,
+        storeRoot: committed.storeRoot,
+        backend: committed.backend,
+    };
+}
+export async function listRegisteredContextStores(options = {}) {
+    const registry = await readContextStoreRegistryState(options);
+    if (!registry) {
+        return [];
+    }
+    return listContextStoreRegistryEntries(registry).map((entry) => ({
+        ...entry,
+        storeRoot: getStoreRootForBackend(entry.backend),
+    }));
+}
+export async function getRegisteredContextStore(input) {
+    const id = validateContextStoreId(input.id);
+    const registry = await readContextStoreRegistryState({
+        globalDataDir: input.globalDataDir,
+    });
+    const entry = getRegisteredStoreOrThrow(registry, id);
+    assertExpectedRegisteredBackend(id, entry.backend, input.expectedBackend);
+    return {
+        ...entry,
+        storeRoot: getStoreRootForBackend(entry.backend),
+    };
+}
+export async function unregisterContextStoreRegistration(input) {
+    const id = validateContextStoreId(input.id);
+    let removed;
+    await updateContextStoreRegistryState(async (registry) => {
+        const result = withoutRegisteredStore(registry, id, input.expectedBackend);
+        const removedEntry = {
+            ...result.removed,
+            storeRoot: getStoreRootForBackend(result.removed.backend),
+        };
+        await input.beforeCommit?.(removedEntry);
+        removed = result.removed;
+        return result.next;
+    }, { globalDataDir: input.globalDataDir });
+    if (!removed) {
+        throw new ContextStoreError(`Unknown context store '${id}'`, 'context_store_not_found', {
+            target: 'context_store.id',
+            fix: 'Run openspec context-store list to see registered stores.',
+        });
+    }
+    return {
+        ...removed,
+        storeRoot: getStoreRootForBackend(removed.backend),
+    };
+}
+export async function resolveRegisteredContextStore(input) {
+    const id = validateContextStoreId(input.id);
+    const registry = await readContextStoreRegistryState({
+        globalDataDir: input.globalDataDir,
+    });
+    if (!registry) {
+        throw new ContextStoreError('No context store registry found', 'no_context_store_registry', {
+            target: 'context_store.id',
+            fix: 'Register a context store before using --store, or pass --store-path <path>.',
+        });
+    }
+    const entry = getRegisteredStoreOrThrow(registry, id);
+    const backend = entry.backend;
+    const storeRoot = getStoreRootForBackend(backend);
+    await ensureStoreMetadata(storeRoot, id, { writeIfMissing: false });
+    return {
+        id,
+        storeRoot,
+        backend,
+    };
+}
+//# sourceMappingURL=registry.js.map

package/dist/core/global-config.d.ts

@@ -25,7 +25,12 @@ export declare function getGlobalConfigDir(): string;
  * - Unix/macOS fallback: ~/.local/share/openspec/
  * - Windows fallback: %LOCALAPPDATA%/openspec/
  */
-export declare function getGlobalDataDir(): string;
+export interface GlobalDataDirOptions {
+    env?: NodeJS.ProcessEnv;
+    platform?: NodeJS.Platform;
+    homedir?: string;
+}
+export declare function getGlobalDataDir(options?: GlobalDataDirOptions): string;
 /**
  * Gets the path to the global config file.
  */

package/dist/core/global-config.js

@@ -36,32 +36,31 @@ export function getGlobalConfigDir() {
     // Unix/macOS fallback: ~/.config
     return path.join(os.homedir(), '.config', GLOBAL_CONFIG_DIR_NAME);
 }
-/**
- * Gets the global data directory path following XDG Base Directory Specification.
- * Used for user data like schema overrides.
- *
- * - All platforms: $XDG_DATA_HOME/openspec/ if XDG_DATA_HOME is set
- * - Unix/macOS fallback: ~/.local/share/openspec/
- * - Windows fallback: %LOCALAPPDATA%/openspec/
- */
-export function getGlobalDataDir() {
+function joinGlobalDataPath(platform, ...segments) {
+    return platform === 'win32'
+        ? path.win32.join(...segments)
+        : path.posix.join(...segments);
+}
+export function getGlobalDataDir(options = {}) {
+    const env = options.env ?? process.env;
+    const platform = options.platform ?? os.platform();
     // XDG_DATA_HOME takes precedence on all platforms when explicitly set
-    const xdgDataHome = process.env.XDG_DATA_HOME;
+    const xdgDataHome = env.XDG_DATA_HOME;
     if (xdgDataHome) {
-        return path.join(xdgDataHome, GLOBAL_DATA_DIR_NAME);
+        return joinGlobalDataPath(platform, xdgDataHome, GLOBAL_DATA_DIR_NAME);
     }
-    const platform = os.platform();
+    const homedir = options.homedir ?? os.homedir();
     if (platform === 'win32') {
         // Windows: use %LOCALAPPDATA%
-        const localAppData = process.env.LOCALAPPDATA;
+        const localAppData = env.LOCALAPPDATA;
         if (localAppData) {
-            return path.join(localAppData, GLOBAL_DATA_DIR_NAME);
+            return joinGlobalDataPath(platform, localAppData, GLOBAL_DATA_DIR_NAME);
         }
         // Fallback for Windows if LOCALAPPDATA is not set
-        return path.join(os.homedir(), 'AppData', 'Local', GLOBAL_DATA_DIR_NAME);
+        return joinGlobalDataPath(platform, homedir, 'AppData', 'Local', GLOBAL_DATA_DIR_NAME);
     }
     // Unix/macOS fallback: ~/.local/share
-    return path.join(os.homedir(), '.local', 'share', GLOBAL_DATA_DIR_NAME);
+    return joinGlobalDataPath(platform, homedir, '.local', 'share', GLOBAL_DATA_DIR_NAME);
 }
 /**
  * Gets the path to the global config file.

package/dist/core/index.d.ts

@@ -1,2 +1,6 @@
-export { GLOBAL_CONFIG_DIR_NAME, GLOBAL_CONFIG_FILE_NAME, GLOBAL_DATA_DIR_NAME, type GlobalConfig, getGlobalConfigDir, getGlobalConfigPath, getGlobalConfig, saveGlobalConfig, getGlobalDataDir } from './global-config.js';
+export { GLOBAL_CONFIG_DIR_NAME, GLOBAL_CONFIG_FILE_NAME, GLOBAL_DATA_DIR_NAME, type GlobalDataDirOptions, type GlobalConfig, getGlobalConfigDir, getGlobalConfigPath, getGlobalConfig, saveGlobalConfig, getGlobalDataDir } from './global-config.js';
+export * from './workspace/index.js';
+export * from './context-store/index.js';
+export * from './collections/index.js';
+export * from './planning-home.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/core/index.js

@@ -1,3 +1,7 @@
 // Core OpenSpec logic will be implemented here
 export { GLOBAL_CONFIG_DIR_NAME, GLOBAL_CONFIG_FILE_NAME, GLOBAL_DATA_DIR_NAME, getGlobalConfigDir, getGlobalConfigPath, getGlobalConfig, saveGlobalConfig, getGlobalDataDir } from './global-config.js';
+export * from './workspace/index.js';
+export * from './context-store/index.js';
+export * from './collections/index.js';
+export * from './planning-home.js';
 //# sourceMappingURL=index.js.map

package/dist/core/parsers/requirement-blocks.js

@@ -1,7 +1,7 @@
 export function normalizeRequirementName(name) {
     return name.trim();
 }
-const REQUIREMENT_HEADER_REGEX = /^###\s*Requirement:\s*(.+)\s*$/;
+const REQUIREMENT_HEADER_REGEX = /^###\s*Requirement:\s*(.+)\s*$/i;
 /**
  * Extracts the Requirements section from a spec file and parses requirement blocks.
  */
@@ -37,7 +37,7 @@ export function extractRequirementsSection(content) {
     let cursor = 0;
     let preambleLines = [];
     // Collect preamble lines until first requirement header
-    while (cursor < sectionBodyLines.length && !/^###\s+Requirement:/.test(sectionBodyLines[cursor])) {
+    while (cursor < sectionBodyLines.length && !REQUIREMENT_HEADER_REGEX.test(sectionBodyLines[cursor])) {
         preambleLines.push(sectionBodyLines[cursor]);
         cursor++;
     }
@@ -54,7 +54,7 @@ export function extractRequirementsSection(content) {
         cursor++;
         // Gather lines until next requirement header or end of section
         const bodyLines = [headerLineCandidate];
-        while (cursor < sectionBodyLines.length && !/^###\s+Requirement:/.test(sectionBodyLines[cursor]) && !/^##\s+/.test(sectionBodyLines[cursor])) {
+        while (cursor < sectionBodyLines.length && !REQUIREMENT_HEADER_REGEX.test(sectionBodyLines[cursor]) && !/^##\s+/.test(sectionBodyLines[cursor])) {
             bodyLines.push(sectionBodyLines[cursor]);
             cursor++;
         }
@@ -136,7 +136,7 @@ function parseRequirementBlocksFromSection(sectionBody) {
     let i = 0;
     while (i < lines.length) {
         // Seek next requirement header
-        while (i < lines.length && !/^###\s+Requirement:/.test(lines[i]))
+        while (i < lines.length && !REQUIREMENT_HEADER_REGEX.test(lines[i]))
             i++;
         if (i >= lines.length)
             break;
@@ -149,7 +149,7 @@ function parseRequirementBlocksFromSection(sectionBody) {
         const name = normalizeRequirementName(m[1]);
         const buf = [headerLine];
         i++;
-        while (i < lines.length && !/^###\s+Requirement:/.test(lines[i]) && !/^##\s+/.test(lines[i])) {
+        while (i < lines.length && !REQUIREMENT_HEADER_REGEX.test(lines[i]) && !/^##\s+/.test(lines[i])) {
             buf.push(lines[i]);
             i++;
         }

package/dist/core/parsers/spec-structure.js

@@ -1,7 +1,7 @@
 const REQUIREMENTS_SECTION_HEADER = /^##\s+Requirements\s*$/i;
 const TOP_LEVEL_SECTION_HEADER = /^##\s+/;
 const DELTA_HEADER = /^##\s+(ADDED|MODIFIED|REMOVED|RENAMED)\s+Requirements\s*$/i;
-const REQUIREMENT_HEADER = /^###\s+Requirement:\s*(.+)\s*$/;
+const REQUIREMENT_HEADER = /^###\s+Requirement:\s*(.+)\s*$/i;
 export function findMainSpecStructureIssues(content) {
     const normalized = content.replace(/\r\n?/g, '\n');
     const stripped = stripFencedCodeBlocksPreservingLines(normalized);

package/dist/core/planning-home.d.ts

@@ -0,0 +1,21 @@
+export type PlanningHomeKind = 'repo' | 'workspace';
+export interface PlanningHome {
+    kind: PlanningHomeKind;
+    root: string;
+    changesDir: string;
+    defaultSchema: string;
+    workspace?: {
+        name: string;
+        links: string[];
+    };
+}
+export interface ResolvePlanningHomeOptions {
+    startPath?: string;
+    allowImplicitRepoRoot?: boolean;
+}
+export declare function findWorkspacePlanningRootSync(startPath?: string): string | null;
+export declare function findRepoPlanningRootSync(startPath?: string): string | null;
+export declare function resolveCurrentPlanningHomeSync(options?: ResolvePlanningHomeOptions): PlanningHome;
+export declare function getChangeDir(planningHome: PlanningHome, changeName: string): string;
+export declare function formatChangeLocation(planningHome: PlanningHome, changeName: string): string;
+//# sourceMappingURL=planning-home.d.ts.map

package/dist/core/planning-home.js

@@ -0,0 +1,108 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { getWorkspaceChangesDir, readWorkspaceViewStateSync, workspaceStateFileExistsSync, } from './workspace/index.js';
+import { FileSystemUtils } from '../utils/file-system.js';
+const REPO_DEFAULT_SCHEMA = 'spec-driven';
+const WORKSPACE_DEFAULT_SCHEMA = 'workspace-planning';
+function pathExistsAsDirectory(candidatePath) {
+    try {
+        return fs.statSync(candidatePath).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function getSearchStartDirectory(startPath) {
+    const resolved = path.resolve(startPath);
+    try {
+        const stats = fs.statSync(resolved);
+        const searchStart = stats.isDirectory() ? resolved : path.dirname(resolved);
+        return FileSystemUtils.canonicalizeExistingPath(searchStart);
+    }
+    catch {
+        return resolved;
+    }
+}
+function findNearestAncestor(startPath, predicate) {
+    let currentDir = getSearchStartDirectory(startPath);
+    while (true) {
+        if (predicate(currentDir)) {
+            return FileSystemUtils.canonicalizeExistingPath(currentDir);
+        }
+        const parentDir = path.dirname(currentDir);
+        if (parentDir === currentDir) {
+            return null;
+        }
+        currentDir = parentDir;
+    }
+}
+export function findWorkspacePlanningRootSync(startPath = process.cwd()) {
+    return findNearestAncestor(startPath, workspaceStateFileExistsSync);
+}
+export function findRepoPlanningRootSync(startPath = process.cwd()) {
+    return findNearestAncestor(startPath, (dirPath) => pathExistsAsDirectory(path.join(dirPath, 'openspec')));
+}
+function isSameOrDescendant(rootPath, candidatePath) {
+    const relative = path.relative(rootPath, candidatePath);
+    return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+}
+function countPathSegments(candidatePath) {
+    return path.resolve(candidatePath).split(path.sep).filter(Boolean).length;
+}
+function isWindowsLikePath(candidatePath) {
+    return /^[A-Za-z]:[\\/]/.test(candidatePath) || candidatePath.startsWith('\\\\');
+}
+function relativePlanningPath(fromPath, toPath) {
+    if (isWindowsLikePath(fromPath) || isWindowsLikePath(toPath)) {
+        return path.win32.relative(path.win32.normalize(fromPath), path.win32.normalize(toPath));
+    }
+    return path.posix.relative(fromPath.replace(/\\/g, '/'), toPath.replace(/\\/g, '/'));
+}
+function workspacePlanningHome(workspaceRoot) {
+    const viewState = readWorkspaceViewStateSync(workspaceRoot);
+    return {
+        kind: 'workspace',
+        root: workspaceRoot,
+        changesDir: getWorkspaceChangesDir(workspaceRoot),
+        defaultSchema: WORKSPACE_DEFAULT_SCHEMA,
+        workspace: {
+            name: viewState?.name ?? path.basename(workspaceRoot),
+            links: Object.keys(viewState?.links ?? {}).sort((a, b) => a.localeCompare(b)),
+        },
+    };
+}
+function repoPlanningHome(repoRoot) {
+    return {
+        kind: 'repo',
+        root: repoRoot,
+        changesDir: path.join(repoRoot, 'openspec', 'changes'),
+        defaultSchema: REPO_DEFAULT_SCHEMA,
+    };
+}
+export function resolveCurrentPlanningHomeSync(options = {}) {
+    const startPath = options.startPath ?? process.cwd();
+    const searchStart = getSearchStartDirectory(startPath);
+    const workspaceRoot = findWorkspacePlanningRootSync(searchStart);
+    const repoRoot = findRepoPlanningRootSync(searchStart);
+    if (workspaceRoot && isSameOrDescendant(workspaceRoot, searchStart)) {
+        if (!repoRoot || countPathSegments(workspaceRoot) >= countPathSegments(repoRoot)) {
+            return workspacePlanningHome(workspaceRoot);
+        }
+    }
+    if (repoRoot) {
+        return repoPlanningHome(repoRoot);
+    }
+    if (options.allowImplicitRepoRoot === false) {
+        throw new Error('No OpenSpec planning home found from the current directory.');
+    }
+    return repoPlanningHome(FileSystemUtils.canonicalizeExistingPath(searchStart));
+}
+export function getChangeDir(planningHome, changeName) {
+    return FileSystemUtils.joinPath(planningHome.changesDir, changeName);
+}
+export function formatChangeLocation(planningHome, changeName) {
+    const changeDir = getChangeDir(planningHome, changeName);
+    const relative = relativePlanningPath(planningHome.root, changeDir);
+    return relative.length > 0 ? relative : changeDir;
+}
+//# sourceMappingURL=planning-home.js.map

package/dist/core/profiles.d.ts

@@ -9,7 +9,7 @@ import type { Profile } from './global-config.js';
  * Core workflows included in the 'core' profile.
  * These provide the streamlined experience for new users.
  */
-export declare const CORE_WORKFLOWS: readonly ["propose", "explore", "apply", "archive"];
+export declare const CORE_WORKFLOWS: readonly ["propose", "explore", "apply", "sync", "archive"];
 /**
  * All available workflows in the system.
  */

package/dist/core/profiles.js

@@ -8,7 +8,7 @@
  * Core workflows included in the 'core' profile.
  * These provide the streamlined experience for new users.
  */
-export const CORE_WORKFLOWS = ['propose', 'explore', 'apply', 'archive'];
+export const CORE_WORKFLOWS = ['propose', 'explore', 'apply', 'sync', 'archive'];
 /**
  * All available workflows in the system.
  */

package/dist/core/specs-apply.js

@@ -211,7 +211,7 @@ export async function buildUpdatedSpec(update, changeName) {
             throw new Error(`${specName} MODIFIED failed for header "### Requirement: ${mod.name}" - not found`);
         }
         // Replace block with provided raw (ensure header line matches key)
-        const modHeaderMatch = mod.raw.split('\n')[0].match(/^###\s*Requirement:\s*(.+)\s*$/);
+        const modHeaderMatch = mod.raw.split('\n')[0].match(/^###\s*Requirement:\s*(.+)\s*$/i);
         if (!modHeaderMatch || normalizeRequirementName(modHeaderMatch[1]) !== key) {
             throw new Error(`${specName} MODIFIED failed for header "### Requirement: ${mod.name}" - header mismatch in content`);
         }

package/dist/core/templates/workflows/apply-change.js

@@ -23,6 +23,7 @@ export function getApplyChangeSkillTemplate() {
    \`\`\`
    Parse the JSON to understand:
    - \`schemaName\`: The workflow being used (e.g., "spec-driven")
+   - \`planningHome\`, \`changeRoot\`, and \`actionContext\`: planning scope and edit constraints
    - Which artifact contains the tasks (typically "tasks" for spec-driven, check status for others)
 
 3. **Get apply instructions**
@@ -42,6 +43,8 @@ export function getApplyChangeSkillTemplate() {
    - If \`state: "all_done"\`: congratulate, suggest archive
    - Otherwise: proceed to implementation
 
+   **Workspace guard:** If status JSON reports \`actionContext.mode: "workspace-planning"\` and \`allowedEditRoots\` is empty, explain that full workspace apply is not supported in this slice. Treat linked repos and folders as read-only context, ask the user to select an affected area through an explicit implementation workflow, and STOP before editing files.
+
 4. **Read context files**
 
    Read every file path listed under \`contextFiles\` from the apply instructions output.
@@ -179,6 +182,7 @@ export function getOpsxApplyCommandTemplate() {
    \`\`\`
    Parse the JSON to understand:
    - \`schemaName\`: The workflow being used (e.g., "spec-driven")
+   - \`planningHome\`, \`changeRoot\`, and \`actionContext\`: planning scope and edit constraints
    - Which artifact contains the tasks (typically "tasks" for spec-driven, check status for others)
 
 3. **Get apply instructions**
@@ -198,6 +202,8 @@ export function getOpsxApplyCommandTemplate() {
    - If \`state: "all_done"\`: congratulate, suggest archive
    - Otherwise: proceed to implementation
 
+   **Workspace guard:** If status JSON reports \`actionContext.mode: "workspace-planning"\` and \`allowedEditRoots\` is empty, explain that full workspace apply is not supported in this slice. Treat linked repos and folders as read-only context, ask the user to select an affected area through an explicit implementation workflow, and STOP before editing files.
+
 4. **Read context files**
 
    Read every file path listed under \`contextFiles\` from the apply instructions output.