@fission-ai/openspec 1.4.0 → 1.5.0

package/dist/core/openers.js

@@ -0,0 +1,251 @@
+import * as nodeFs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import { z } from 'zod';
+import { StoreError } from './store/errors.js';
+import { formatZodIssues } from './zod-issues.js';
+const DEFAULT_ATTACH_FLAG = '--add-dir';
+/**
+ * Temporary kill-switch (2026-06): worksets open only in IDE-style
+ * ('workspace-file') tools while the CLI-agent ('attach-dirs') open flow
+ * is reworked. The agents (Claude Code, codex) launch in a single primary
+ * cwd rather than a true combined multi-root view, which makes "where does
+ * my change land?" ambiguous. Default off; set
+ * OPENSPEC_ENABLE_CLI_AGENT_OPENERS=1 to restore them (internal rollback seam).
+ */
+export function isCliAgentOpenersEnabled() {
+    return process.env.OPENSPEC_ENABLE_CLI_AGENT_OPENERS === '1';
+}
+/** Whether a tool can be opened right now (CLI-agent styles are gated). */
+export function isOpenerEnabled(opener) {
+    return isCliAgentOpenersEnabled() || opener.style !== 'attach-dirs';
+}
+export const BUILTIN_OPENERS = [
+    {
+        id: 'code',
+        label: 'VS Code',
+        style: 'workspace-file',
+        command: 'code',
+        args: [],
+        attachFlag: DEFAULT_ATTACH_FLAG,
+    },
+    {
+        id: 'cursor',
+        label: 'Cursor',
+        style: 'workspace-file',
+        command: 'cursor',
+        args: [],
+        attachFlag: DEFAULT_ATTACH_FLAG,
+    },
+    {
+        id: 'claude',
+        label: 'Claude Code',
+        style: 'attach-dirs',
+        command: 'claude',
+        args: [],
+        attachFlag: DEFAULT_ATTACH_FLAG,
+    },
+    {
+        id: 'codex',
+        label: 'codex',
+        style: 'attach-dirs',
+        command: 'codex',
+        args: ['--sandbox', 'workspace-write'],
+        attachFlag: DEFAULT_ATTACH_FLAG,
+    },
+];
+const OPENER_STYLES = ['workspace-file', 'attach-dirs'];
+const OpenerConfigRowSchema = z
+    .object({
+    style: z.enum(OPENER_STYLES).optional(),
+    label: z.string().min(1).optional(),
+    command: z.string().min(1).optional(),
+    args: z.array(z.string()).optional(),
+    attach_flag: z.string().min(1).optional(),
+})
+    .strict();
+const OpenersConfigSchema = z.record(z.string(), OpenerConfigRowSchema);
+function invalidOpenerConfigError(message, configPath) {
+    return new StoreError(`Invalid openers config: ${message}`, 'invalid_opener_config', {
+        target: 'openers.config',
+        fix: `Each entry under "openers" in ${configPath} may set style ('workspace-file' or 'attach-dirs'), label, command, args, and attach_flag; new tools must set style.`,
+    });
+}
+/**
+ * Merges the global config file's raw `openers` value over the
+ * built-in table. A row keyed by a built-in id overrides only the
+ * fields it sets; a new id adds a tool (style required, command and
+ * label default to the id). Malformed rows fail typed - never
+ * silently ignored.
+ */
+function cloneOpener(opener) {
+    return { ...opener, args: [...opener.args] };
+}
+export function mergeOpenerTable(rawOpeners, configPath) {
+    if (rawOpeners === undefined || rawOpeners === null) {
+        return BUILTIN_OPENERS.map(cloneOpener);
+    }
+    const result = OpenersConfigSchema.safeParse(rawOpeners);
+    if (!result.success) {
+        throw invalidOpenerConfigError(formatZodIssues(result.error, 'openers'), configPath);
+    }
+    const table = BUILTIN_OPENERS.map(cloneOpener);
+    for (const [id, row] of Object.entries(result.data)) {
+        const builtinIndex = table.findIndex((opener) => opener.id === id);
+        if (builtinIndex >= 0) {
+            const builtin = table[builtinIndex];
+            table[builtinIndex] = {
+                ...builtin,
+                ...(row.style !== undefined ? { style: row.style } : {}),
+                ...(row.label !== undefined ? { label: row.label } : {}),
+                ...(row.command !== undefined ? { command: row.command } : {}),
+                ...(row.args !== undefined ? { args: row.args } : {}),
+                ...(row.attach_flag !== undefined
+                    ? { attachFlag: row.attach_flag }
+                    : {}),
+            };
+            continue;
+        }
+        if (row.style === undefined) {
+            throw invalidOpenerConfigError(`'${id}' adds a new tool and must set style ('workspace-file' or 'attach-dirs')`, configPath);
+        }
+        table.push({
+            id,
+            label: row.label ?? id,
+            style: row.style,
+            command: row.command ?? id,
+            args: row.args ?? [],
+            attachFlag: row.attach_flag ?? DEFAULT_ATTACH_FLAG,
+        });
+    }
+    return table;
+}
+function getPathValue(env) {
+    return env.PATH ?? env.Path ?? env.path ?? '';
+}
+function getPathExtensions(platform, env) {
+    if (platform !== 'win32') {
+        return [''];
+    }
+    return (env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD')
+        .split(';')
+        .map((extension) => extension.trim())
+        .filter((extension) => extension.length > 0);
+}
+function defaultIsExecutableFile(candidatePath, platform) {
+    try {
+        if (!nodeFs.statSync(candidatePath).isFile()) {
+            return false;
+        }
+    }
+    catch {
+        return false;
+    }
+    if (platform === 'win32') {
+        return true;
+    }
+    try {
+        nodeFs.accessSync(candidatePath, nodeFs.constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * PATH availability scan (ported from the deleted workspace openers
+ * at f858c19^, sharpened for injectability: the path module is keyed
+ * by the injected platform, and a command already carrying a known
+ * executable extension matches as-is).
+ */
+export function isOpenerCommandAvailable(command, options = {}) {
+    const env = options.env ?? process.env;
+    const platform = options.platform ?? os.platform();
+    const pathModule = platform === 'win32' ? path.win32 : path.posix;
+    const isExecutable = options.isExecutableFile ??
+        ((candidate) => defaultIsExecutableFile(candidate, platform));
+    const extensions = getPathExtensions(platform, env);
+    const lowerCommand = command.toLowerCase();
+    const carriesKnownExtension = extensions.some((extension) => extension.length > 0 && lowerCommand.endsWith(extension.toLowerCase()));
+    // One suffix policy: a command already carrying a known executable
+    // extension matches as-is and never gets a second extension appended
+    // - agreeing with spawn-time resolution.
+    const suffixes = carriesKnownExtension ? [''] : extensions;
+    if (/[\\/]/u.test(command)) {
+        // Direct paths additionally match bare even on win32 (the spawn
+        // call receives the literal path).
+        const directSuffixes = Array.from(new Set(['', ...suffixes]));
+        return directSuffixes.some((suffix) => isExecutable(command + suffix));
+    }
+    for (const directory of getPathValue(env).split(pathModule.delimiter)) {
+        if (directory.length === 0) {
+            continue;
+        }
+        if (suffixes.some((suffix) => isExecutable(pathModule.join(directory, command + suffix)))) {
+            return true;
+        }
+    }
+    return false;
+}
+/** Table order preserved, available tools first (stable sort). */
+export function listOpenerChoices(table, options = {}) {
+    return table
+        .filter((opener) => isOpenerEnabled(opener))
+        .map((opener) => {
+        const available = isOpenerCommandAvailable(opener.command, options);
+        return {
+            opener,
+            available,
+            note: available ? null : `(${opener.command} not found on PATH)`,
+        };
+    })
+        .sort((a, b) => {
+        if (a.available === b.available) {
+            return 0;
+        }
+        return a.available ? -1 : 1;
+    });
+}
+export function findOpener(table, id) {
+    return table.find((opener) => opener.id === id) ?? null;
+}
+/**
+ * Pure argv builder. workspace-file: pre-args + the generated file's
+ * absolute path (which also defuses the cursor shim's `agent`
+ * first-arg hijack). attach-dirs: pre-args + one attach flag + path
+ * pair per surviving member, the primary included (the locked "one
+ * attach flag per member"); never a trailing positional - both agent
+ * CLIs would read one as a starter prompt, which 7.1 locks out.
+ */
+export function buildLaunchCommand(opener, input) {
+    if (input.members.length === 0) {
+        throw new Error('buildLaunchCommand requires at least one member.');
+    }
+    // The no-hijack and no-positional guarantees lean on absolute paths
+    // (the child resolves relative argv against its own cwd) - keep the
+    // invariant local instead of three modules away.
+    if (!path.isAbsolute(input.codeWorkspacePath)) {
+        throw new Error(`buildLaunchCommand requires an absolute workspace-file path (got '${input.codeWorkspacePath}').`);
+    }
+    const cwd = input.members[0].path;
+    if (opener.style === 'workspace-file') {
+        return {
+            executable: opener.command,
+            args: [...opener.args, input.codeWorkspacePath],
+            cwd,
+            label: opener.label,
+            style: opener.style,
+        };
+    }
+    return {
+        executable: opener.command,
+        args: [
+            ...opener.args,
+            ...input.members.flatMap((member) => [opener.attachFlag, member.path]),
+        ],
+        cwd,
+        label: opener.label,
+        style: opener.style,
+    };
+}
+//# sourceMappingURL=openers.js.map

package/dist/core/openspec-root.d.ts

@@ -0,0 +1,45 @@
+import { type StoreDiagnostic } from './store/errors.js';
+export declare const OPENSPEC_ROOT_DIR = "openspec";
+export declare const OPENSPEC_CONFIG_YAML = "openspec/config.yaml";
+export declare const OPENSPEC_CONFIG_YML = "openspec/config.yml";
+export declare const OPENSPEC_SPECS_DIR = "openspec/specs";
+export declare const OPENSPEC_CHANGES_DIR = "openspec/changes";
+export declare const OPENSPEC_ARCHIVE_DIR = "openspec/changes/archive";
+export declare const DEFAULT_OPENSPEC_SCHEMA = "spec-driven";
+export declare const DIRECTORY_ANCHOR_FILE_NAME = ".gitkeep";
+export declare const ANCHORED_OPENSPEC_DIRS: readonly ["openspec/specs", "openspec/changes/archive"];
+export interface CreatedPathLedgerEntry {
+    relativePath: string;
+    absolutePath: string;
+    kind: 'directory' | 'file';
+}
+export interface OpenSpecRootInspection {
+    present: boolean | null;
+    config: {
+        present: boolean | null;
+        path?: string;
+    };
+    specs: {
+        present: boolean | null;
+    };
+    changes: {
+        present: boolean | null;
+    };
+    archive: {
+        present: boolean | null;
+    };
+    healthy: boolean;
+    diagnostics: StoreDiagnostic[];
+}
+export interface EnsureOpenSpecRootResult {
+    inspection: OpenSpecRootInspection;
+    createdArtifacts: string[];
+    createdPaths: CreatedPathLedgerEntry[];
+}
+export declare function inspectOpenSpecRoot(storeRoot: string): Promise<OpenSpecRootInspection>;
+export interface EnsureOpenSpecRootOptions {
+    anchorEmptyDirectories?: boolean;
+}
+export declare function ensureOpenSpecRoot(storeRoot: string, options?: EnsureOpenSpecRootOptions): Promise<EnsureOpenSpecRootResult>;
+export declare function rollbackCreatedPaths(entries: CreatedPathLedgerEntry[]): Promise<void>;
+//# sourceMappingURL=openspec-root.d.ts.map

package/dist/core/openspec-root.js

@@ -0,0 +1,192 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { FileSystemUtils } from '../utils/file-system.js';
+import { serializeConfig } from './config-prompts.js';
+import { makeStoreDiagnostic, } from './store/errors.js';
+export const OPENSPEC_ROOT_DIR = 'openspec';
+export const OPENSPEC_CONFIG_YAML = 'openspec/config.yaml';
+export const OPENSPEC_CONFIG_YML = 'openspec/config.yml';
+export const OPENSPEC_SPECS_DIR = 'openspec/specs';
+export const OPENSPEC_CHANGES_DIR = 'openspec/changes';
+export const OPENSPEC_ARCHIVE_DIR = 'openspec/changes/archive';
+export const DEFAULT_OPENSPEC_SCHEMA = 'spec-driven';
+export const DIRECTORY_ANCHOR_FILE_NAME = '.gitkeep';
+// Git cannot track empty directories, so clones of a fresh store would lose
+// these and fail root-health checks. Anchored at setup time.
+export const ANCHORED_OPENSPEC_DIRS = [OPENSPEC_SPECS_DIR, OPENSPEC_ARCHIVE_DIR];
+async function pathKind(targetPath) {
+    try {
+        const stat = await fs.stat(targetPath);
+        if (stat.isDirectory())
+            return 'directory';
+        if (stat.isFile())
+            return 'file';
+        return 'other';
+    }
+    catch (error) {
+        if (typeof error === 'object' &&
+            error !== null &&
+            'code' in error &&
+            error.code === 'ENOENT') {
+            return 'missing';
+        }
+        throw error;
+    }
+}
+function relativeArtifact(relativePath, kind) {
+    const normalized = FileSystemUtils.toPosixPath(relativePath);
+    return kind === 'directory' ? `${normalized}/` : normalized;
+}
+function unresolvedInspection() {
+    return {
+        present: null,
+        config: { present: null },
+        specs: { present: null },
+        changes: { present: null },
+        archive: { present: null },
+        healthy: false,
+        diagnostics: [],
+    };
+}
+function missingDirectoryDiagnostic(code, message, target) {
+    return makeStoreDiagnostic('error', code, message, { target });
+}
+export async function inspectOpenSpecRoot(storeRoot) {
+    const rootKind = await pathKind(storeRoot);
+    const inspection = unresolvedInspection();
+    if (rootKind === 'missing') {
+        inspection.diagnostics.push(missingDirectoryDiagnostic('openspec_store_root_missing', 'Store root does not exist.', 'store.root'));
+        return inspection;
+    }
+    if (rootKind !== 'directory') {
+        inspection.diagnostics.push(missingDirectoryDiagnostic('openspec_store_root_not_directory', 'Store root is not a directory.', 'store.root'));
+        return inspection;
+    }
+    const openspecPath = path.join(storeRoot, OPENSPEC_ROOT_DIR);
+    const openspecKind = await pathKind(openspecPath);
+    inspection.present = openspecKind === 'directory';
+    if (openspecKind === 'missing') {
+        inspection.diagnostics.push(missingDirectoryDiagnostic('openspec_root_missing', 'Missing openspec/ directory.', 'openspec.root'));
+        return inspection;
+    }
+    if (openspecKind !== 'directory') {
+        inspection.diagnostics.push(missingDirectoryDiagnostic('openspec_root_not_directory', 'openspec/ exists but is not a directory.', 'openspec.root'));
+        return inspection;
+    }
+    const configYamlKind = await pathKind(path.join(storeRoot, OPENSPEC_CONFIG_YAML));
+    const configYmlKind = await pathKind(path.join(storeRoot, OPENSPEC_CONFIG_YML));
+    if (configYamlKind === 'file') {
+        inspection.config = { present: true, path: OPENSPEC_CONFIG_YAML };
+    }
+    else if (configYmlKind === 'file') {
+        inspection.config = { present: true, path: OPENSPEC_CONFIG_YML };
+    }
+    else {
+        inspection.config = { present: false };
+        if (configYamlKind !== 'missing' || configYmlKind !== 'missing') {
+            inspection.diagnostics.push(missingDirectoryDiagnostic('openspec_config_not_file', 'OpenSpec config path exists but is not a file.', 'openspec.config'));
+        }
+        else {
+            inspection.diagnostics.push(missingDirectoryDiagnostic('openspec_config_missing', 'Missing openspec/config.yaml or openspec/config.yml.', 'openspec.config'));
+        }
+    }
+    for (const [key, relativePath, code, message, target] of [
+        ['specs', OPENSPEC_SPECS_DIR, 'openspec_specs_missing', 'Missing openspec/specs/.', 'openspec.specs'],
+        ['changes', OPENSPEC_CHANGES_DIR, 'openspec_changes_missing', 'Missing openspec/changes/.', 'openspec.changes'],
+        ['archive', OPENSPEC_ARCHIVE_DIR, 'openspec_archive_missing', 'Missing openspec/changes/archive/.', 'openspec.archive'],
+    ]) {
+        const kind = await pathKind(path.join(storeRoot, relativePath));
+        inspection[key] = { present: kind === 'directory' };
+        if (kind === 'directory')
+            continue;
+        inspection.diagnostics.push(missingDirectoryDiagnostic(kind === 'missing' ? code : code.replace('_missing', '_not_directory'), kind === 'missing' ? message : `${relativePath}/ exists but is not a directory.`, target));
+    }
+    inspection.healthy =
+        inspection.present === true &&
+            inspection.config.present === true &&
+            inspection.specs.present === true &&
+            inspection.changes.present === true &&
+            inspection.archive.present === true;
+    return inspection;
+}
+async function ensureDirectory(storeRoot, relativePath, ledger) {
+    const absolutePath = path.join(storeRoot, relativePath);
+    const kind = await pathKind(absolutePath);
+    if (kind === 'directory')
+        return;
+    if (kind !== 'missing') {
+        throw new Error(`${relativePath}/ exists but is not a directory.`);
+    }
+    await fs.mkdir(absolutePath, { recursive: true });
+    ledger.push({
+        relativePath: relativeArtifact(relativePath, 'directory'),
+        absolutePath,
+        kind: 'directory',
+    });
+}
+async function ensureDefaultConfig(storeRoot, ledger) {
+    const configYamlPath = path.join(storeRoot, OPENSPEC_CONFIG_YAML);
+    const configYmlPath = path.join(storeRoot, OPENSPEC_CONFIG_YML);
+    const yamlKind = await pathKind(configYamlPath);
+    const ymlKind = await pathKind(configYmlPath);
+    if (yamlKind === 'file' || ymlKind === 'file')
+        return;
+    if (yamlKind !== 'missing' || ymlKind !== 'missing') {
+        throw new Error('OpenSpec config path exists but is not a file.');
+    }
+    await FileSystemUtils.writeFile(configYamlPath, serializeConfig({ schema: DEFAULT_OPENSPEC_SCHEMA }));
+    ledger.push({
+        relativePath: relativeArtifact(OPENSPEC_CONFIG_YAML, 'file'),
+        absolutePath: configYamlPath,
+        kind: 'file',
+    });
+}
+async function ensureDirectoryAnchor(storeRoot, relativeDir, ledger) {
+    const directory = path.join(storeRoot, relativeDir);
+    if ((await fs.readdir(directory)).length > 0)
+        return;
+    const relativePath = `${relativeDir}/${DIRECTORY_ANCHOR_FILE_NAME}`;
+    const absolutePath = path.join(directory, DIRECTORY_ANCHOR_FILE_NAME);
+    await fs.writeFile(absolutePath, '', 'utf-8');
+    ledger.push({
+        relativePath: relativeArtifact(relativePath, 'file'),
+        absolutePath,
+        kind: 'file',
+    });
+}
+export async function ensureOpenSpecRoot(storeRoot, options = {}) {
+    const ledger = [];
+    const rootKind = await pathKind(storeRoot);
+    if (rootKind === 'missing') {
+        await fs.mkdir(storeRoot, { recursive: true });
+    }
+    else if (rootKind !== 'directory') {
+        throw new Error('Store root is not a directory.');
+    }
+    await ensureDirectory(storeRoot, OPENSPEC_ROOT_DIR, ledger);
+    await ensureDirectory(storeRoot, OPENSPEC_SPECS_DIR, ledger);
+    await ensureDirectory(storeRoot, OPENSPEC_CHANGES_DIR, ledger);
+    await ensureDirectory(storeRoot, OPENSPEC_ARCHIVE_DIR, ledger);
+    await ensureDefaultConfig(storeRoot, ledger);
+    if (options.anchorEmptyDirectories) {
+        for (const relativeDir of ANCHORED_OPENSPEC_DIRS) {
+            await ensureDirectoryAnchor(storeRoot, relativeDir, ledger);
+        }
+    }
+    return {
+        inspection: await inspectOpenSpecRoot(storeRoot),
+        createdArtifacts: ledger.map((entry) => entry.relativePath),
+        createdPaths: ledger,
+    };
+}
+export async function rollbackCreatedPaths(entries) {
+    for (const entry of [...entries].reverse()) {
+        if (entry.kind === 'file') {
+            await fs.rm(entry.absolutePath, { force: true }).catch(() => undefined);
+        }
+        else {
+            await fs.rmdir(entry.absolutePath).catch(() => undefined);
+        }
+    }
+}
+//# sourceMappingURL=openspec-root.js.map

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

@@ -1,19 +1,14 @@
-export type PlanningHomeKind = 'repo' | 'workspace';
+export type PlanningHomeKind = 'repo';
 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;

package/dist/core/planning-home.js

@@ -1,9 +1,7 @@
 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();
@@ -36,41 +34,9 @@ function findNearestAncestor(startPath, predicate) {
         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',
@@ -82,13 +48,7 @@ function repoPlanningHome(repoRoot) {
 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);
     }
@@ -101,8 +61,7 @@ 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;
+    // Repo homes always nest changesDir under the root.
+    return path.relative(planningHome.root, getChangeDir(planningHome, changeName));
 }
 //# sourceMappingURL=planning-home.js.map

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

@@ -16,8 +16,18 @@ export declare const ProjectConfigSchema: z.ZodObject<{
     schema: z.ZodString;
     context: z.ZodOptional<z.ZodString>;
     rules: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>;
+    store: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
-export type ProjectConfig = z.infer<typeof ProjectConfigSchema>;
+/** Normalized in-memory shape of a referenced store declaration. */
+export interface DeclarationEntry {
+    id: string;
+    /** Clone source rendered into onboarding fixes. */
+    remote?: string;
+}
+export type ProjectConfig = z.infer<typeof ProjectConfigSchema> & {
+    references?: DeclarationEntry[];
+};
+export declare const MAX_CONTEXT_SIZE: number;
 /**
  * Read and parse openspec/config.yaml from project root.
  * Uses resilient parsing - validates each field independently using Zod safeParse.
@@ -61,4 +71,37 @@ export declare function suggestSchemas(invalidSchemaName: string, availableSchem
     name: string;
     isBuiltIn: boolean;
 }[]): string;
+export interface StorePointerRead {
+    /** The declared store id, when present and a string. */
+    value?: string;
+    /** Set when the pointer cannot be trusted: the config file could not be
+     * read as YAML, or the store key is present but not a string. An empty
+     * or comments-only config is NOT malformed - it simply has no pointer. */
+    malformed?: 'unparseable' | 'non_string';
+    /** Absolute path of the config file actually read, or null when none exists. */
+    filePath: string | null;
+}
+/**
+ * Warning-silent targeted read of the `store:` pointer. Used by root
+ * resolution (which must not re-emit the resilient parser's field
+ * warnings) and by `openspec init`'s pointer guard. Unlike
+ * `readProjectConfig`, a malformed value is REPORTED, not dropped —
+ * a dropped pointer would silently flip where work lands.
+ */
+export declare function readStorePointer(projectRoot: string): StorePointerRead;
+/** Shared .yaml/.yml probe used by readProjectConfig and readStorePointer. */
+export declare function resolveConfigFilePath(projectRoot: string): string | null;
+/** Human rendering of a malformed pointer reason, shared by every surface. */
+export declare function storePointerProblem(reason: 'unparseable' | 'non_string'): string;
+export interface OpenSpecDirClassification {
+    /** True when openspec/specs or openspec/changes exists as a directory. */
+    hasPlanningShape: boolean;
+    pointer: StorePointerRead;
+}
+/**
+ * One classification for "real root vs config-only pointer dir", shared
+ * by root resolution and the init pointer guard so they can never
+ * disagree (slice 3.2).
+ */
+export declare function classifyOpenSpecDir(projectRoot: string): OpenSpecDirClassification;
 //# sourceMappingURL=project-config.d.ts.map