freeharness 0.4.1

package/node_modules/@freeharness/sdd/dist/vendor/openspec/engine/change-metadata.d.ts

@@ -0,0 +1,46 @@
+import { z } from 'zod';
+export declare const METADATA_FILENAME = ".openspec.yaml";
+/**
+ * Per-change metadata, trimmed to the fields this store-free slice consumes.
+ * Extra keys are allowed (upstream carries goal / affected_areas / initiative /
+ * retire_capabilities); they are simply ignored here.
+ */
+export declare const ChangeMetadataSchema: z.ZodObject<{
+    schema: z.ZodString;
+    created: z.ZodOptional<z.ZodString>;
+    skip_specs: z.ZodOptional<z.ZodBoolean>;
+    depends_on: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    supersedes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$loose>;
+export type ChangeMetadata = z.infer<typeof ChangeMetadataSchema>;
+/**
+ * Error thrown when change metadata validation fails.
+ */
+export declare class ChangeMetadataError extends Error {
+    readonly metadataPath: string;
+    readonly cause?: Error | undefined;
+    constructor(message: string, metadataPath: string, cause?: Error | undefined);
+}
+/**
+ * Reads change metadata from `.openspec.yaml` in the change directory.
+ * Returns null when no metadata file exists; throws when it exists but is
+ * invalid or names an unknown schema.
+ */
+export declare function readChangeMetadata(changeDir: string, projectRoot?: string): ChangeMetadata | null;
+export interface ResolveSchemaForChangeOptions {
+    metadata?: ChangeMetadata | null;
+}
+/**
+ * Resolves the schema for a change.
+ *
+ * Resolution order (store-free slice):
+ *   1. Explicit schema (if provided)
+ *   2. Schema from `.openspec.yaml` metadata (if present)
+ *   3. Default 'spec-driven'
+ */
+export declare function resolveSchemaForChange(changeDir: string, explicitSchema?: string, projectRootOverride?: string, options?: ResolveSchemaForChangeOptions): string;
+/**
+ * Writes change metadata to `.openspec.yaml`. Used by the store-free
+ * `new change` shim. Validates the schema name against available schemas.
+ */
+export declare function writeChangeMetadata(changeDir: string, metadata: ChangeMetadata, projectRoot?: string): void;

package/node_modules/@freeharness/sdd/dist/vendor/openspec/engine/change-metadata.js

@@ -0,0 +1,128 @@
+// RECONSTRUCTED (store-free) from @fission-ai/openspec@1.8.0
+//   src/utils/change-metadata.ts + src/core/change-metadata/schema.ts
+//
+// The upstream module couples change metadata to project-config (config.yaml
+// schema fallback) and the multi-repo store. This slice keeps only what
+// status/instructions need: reading `.openspec.yaml`, validating it, and
+// resolving the governing schema. Resolution order is trimmed to
+//   1. explicit schema   2. metadata.schema   3. 'spec-driven'
+// (the project-config fallback is intentionally dropped — it is store/config
+// plumbing outside this slice). The ChangeMetadata zod schema is inlined
+// (only the fields this slice reads: schema + skip_specs) instead of vendoring
+// the id-grammar and initiative-link machinery.
+// FreeHarness addition: `depends_on` / `supersedes` (change-id lists), resolved
+// and enforced by the shim's validate/archive commands, not by this slice.
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as yaml from 'yaml';
+import { z } from 'zod';
+import { listSchemas } from './resolver.js';
+export const METADATA_FILENAME = '.openspec.yaml';
+/**
+ * Per-change metadata, trimmed to the fields this store-free slice consumes.
+ * Extra keys are allowed (upstream carries goal / affected_areas / initiative /
+ * retire_capabilities); they are simply ignored here.
+ */
+export const ChangeMetadataSchema = z
+    .object({
+    schema: z.string().min(1, { message: 'schema is required' }),
+    created: z
+        .string()
+        .regex(/^\d{4}-\d{2}-\d{2}$/, { message: 'created must be YYYY-MM-DD format' })
+        .optional(),
+    skip_specs: z.boolean().optional(),
+    depends_on: z.array(z.string()).optional(),
+    supersedes: z.array(z.string()).optional(),
+})
+    .passthrough();
+/**
+ * Error thrown when change metadata validation fails.
+ */
+export class ChangeMetadataError extends Error {
+    metadataPath;
+    cause;
+    constructor(message, metadataPath, cause) {
+        super(message);
+        this.metadataPath = metadataPath;
+        this.cause = cause;
+        this.name = 'ChangeMetadataError';
+    }
+}
+/**
+ * Reads change metadata from `.openspec.yaml` in the change directory.
+ * Returns null when no metadata file exists; throws when it exists but is
+ * invalid or names an unknown schema.
+ */
+export function readChangeMetadata(changeDir, projectRoot) {
+    const metaPath = path.join(changeDir, METADATA_FILENAME);
+    if (!fs.existsSync(metaPath)) {
+        return null;
+    }
+    let content;
+    try {
+        content = fs.readFileSync(metaPath, 'utf-8');
+    }
+    catch (err) {
+        const ioError = err instanceof Error ? err : new Error(String(err));
+        throw new ChangeMetadataError(`Failed to read metadata: ${ioError.message}`, metaPath, ioError);
+    }
+    let parsed;
+    try {
+        parsed = yaml.parse(content);
+    }
+    catch (err) {
+        const parseError = err instanceof Error ? err : new Error(String(err));
+        throw new ChangeMetadataError(`Invalid YAML in metadata file: ${parseError.message}`, metaPath, parseError);
+    }
+    const parseResult = ChangeMetadataSchema.safeParse(parsed);
+    if (!parseResult.success) {
+        throw new ChangeMetadataError(`Invalid metadata: ${parseResult.error.message}`, metaPath);
+    }
+    const availableSchemas = listSchemas(projectRoot);
+    if (!availableSchemas.includes(parseResult.data.schema)) {
+        throw new ChangeMetadataError(`Unknown schema '${parseResult.data.schema}'. Available: ${availableSchemas.join(', ')}`, metaPath);
+    }
+    return parseResult.data;
+}
+/**
+ * Resolves the schema for a change.
+ *
+ * Resolution order (store-free slice):
+ *   1. Explicit schema (if provided)
+ *   2. Schema from `.openspec.yaml` metadata (if present)
+ *   3. Default 'spec-driven'
+ */
+export function resolveSchemaForChange(changeDir, explicitSchema, projectRootOverride, options = {}) {
+    const projectRoot = projectRootOverride ?? path.resolve(changeDir, '../../..');
+    if (explicitSchema) {
+        return explicitSchema;
+    }
+    const metadata = options.metadata !== undefined ? options.metadata : readChangeMetadata(changeDir, projectRoot);
+    if (metadata?.schema) {
+        return metadata.schema;
+    }
+    return 'spec-driven';
+}
+/**
+ * Writes change metadata to `.openspec.yaml`. Used by the store-free
+ * `new change` shim. Validates the schema name against available schemas.
+ */
+export function writeChangeMetadata(changeDir, metadata, projectRoot) {
+    const metaPath = path.join(changeDir, METADATA_FILENAME);
+    const parseResult = ChangeMetadataSchema.safeParse(metadata);
+    if (!parseResult.success) {
+        throw new ChangeMetadataError(`Invalid metadata: ${parseResult.error.message}`, metaPath);
+    }
+    const availableSchemas = listSchemas(projectRoot);
+    if (!availableSchemas.includes(parseResult.data.schema)) {
+        throw new ChangeMetadataError(`Unknown schema '${parseResult.data.schema}'. Available: ${availableSchemas.join(', ')}`, metaPath);
+    }
+    const content = yaml.stringify(parseResult.data);
+    try {
+        fs.writeFileSync(metaPath, content, 'utf-8');
+    }
+    catch (err) {
+        const ioError = err instanceof Error ? err : new Error(String(err));
+        throw new ChangeMetadataError(`Failed to write metadata: ${ioError.message}`, metaPath, ioError);
+    }
+}

package/node_modules/@freeharness/sdd/dist/vendor/openspec/engine/change-status-policy.d.ts

@@ -0,0 +1,26 @@
+export interface ActionContext {
+    mode: 'repo-local';
+    sourceOfTruth: 'repo';
+    planningArtifacts: string[];
+    linkedContext: Array<{
+        name: string;
+    }>;
+    allowedEditRoots: string[];
+    requiresAffectedAreaSelection: boolean;
+    constraints: string[];
+}
+export interface ChangeStatusPolicyArtifact {
+    id: string;
+    status: 'done' | 'skipped' | 'ready' | 'blocked';
+}
+export interface ChangeNextStepsInput {
+    changeName: string;
+    artifactStatuses: ChangeStatusPolicyArtifact[];
+    allArtifactsComplete: boolean;
+}
+export interface ActionContextInput {
+    projectRoot: string;
+    artifactIds: string[];
+}
+export declare function buildActionContext(input: ActionContextInput): ActionContext;
+export declare function buildNextSteps(input: ChangeNextStepsInput): string[];

package/node_modules/@freeharness/sdd/dist/vendor/openspec/engine/change-status-policy.js

@@ -0,0 +1,32 @@
+// RECONSTRUCTED (store-free) from @fission-ai/openspec@1.8.0
+//   src/core/change-status-policy.ts
+//
+// buildActionContext and buildNextSteps are vendored faithfully. The only
+// change is that the store-aware pieces are dropped: PlanningHome /
+// summarizePlanningHome (multi-repo store home) and the `--store` flag that
+// buildNextSteps threaded into its command hints. Next-step commands are
+// emitted in their plain, store-free form.
+export function buildActionContext(input) {
+    return {
+        mode: 'repo-local',
+        sourceOfTruth: 'repo',
+        planningArtifacts: input.artifactIds,
+        linkedContext: [],
+        allowedEditRoots: [input.projectRoot],
+        requiresAffectedAreaSelection: false,
+        constraints: [
+            'Repo-local change artifacts and implementation edits are scoped to this project.',
+        ],
+    };
+}
+export function buildNextSteps(input) {
+    const readyArtifact = input.artifactStatuses.find((artifact) => artifact.status === 'ready');
+    const steps = [];
+    if (readyArtifact) {
+        steps.push(`Run openspec instructions ${readyArtifact.id} --change "${input.changeName}" --json before writing that artifact.`);
+    }
+    else if (input.allArtifactsComplete) {
+        steps.push(`All planning artifacts are complete. Run openspec instructions apply --change "${input.changeName}" --json to inspect implementation progress.`);
+    }
+    return steps;
+}

package/node_modules/@freeharness/sdd/dist/vendor/openspec/engine/file-system.d.ts

@@ -0,0 +1,50 @@
+export declare class FileSystemUtils {
+    /**
+     * Converts a path to use forward slashes (POSIX style).
+     * Essential for cross-platform compatibility with glob libraries like fast-glob.
+     */
+    static toPosixPath(p: string): string;
+    /**
+     * Returns a canonical absolute path when the target exists.
+     * Falls back to path.resolve() so callers can still produce a stable absolute path.
+     */
+    static canonicalizeExistingPath(targetPath: string): string;
+    /**
+     * Refuses a target that leaves an allowed directory, including through an
+     * existing symlink in either the target or one of its parent directories.
+     * Missing suffixes are resolved from their nearest existing ancestor.
+     */
+    static assertPathWithin(allowedDirectory: string, targetPath: string): void;
+    static resolveProjectArtifactPath(projectPath: string, artifactPath: string): string;
+    static assertProjectArtifactPath(projectPath: string, targetPath: string): void;
+    private static isPathWithin;
+    private static canonicalizePotentialPath;
+    private static isWindowsBasePath;
+    private static normalizeSegments;
+    static joinPath(basePath: string, ...segments: string[]): string;
+    static createDirectory(dirPath: string): Promise<void>;
+    static fileExists(filePath: string): Promise<boolean>;
+    /**
+     * Finds the first existing parent directory by walking up the directory tree.
+     * @param dirPath Starting directory path
+     * @returns The first existing directory path, or null if root is reached without finding one
+     */
+    private static findFirstExistingDirectory;
+    static canWriteFile(filePath: string): Promise<boolean>;
+    static directoryExists(dirPath: string): Promise<boolean>;
+    static writeFile(filePath: string, content: string): Promise<void>;
+    static readFile(filePath: string): Promise<string>;
+    static updateFileWithMarkers(filePath: string, content: string, startMarker: string, endMarker: string): Promise<void>;
+    static ensureWritePermissions(dirPath: string): Promise<boolean>;
+}
+/**
+ * Removes a marker block from file content.
+ * Only removes markers that are on their own lines (ignores inline mentions).
+ * Cleans up double blank lines that may result from removal.
+ *
+ * @param content - File content with markers
+ * @param startMarker - The start marker string
+ * @param endMarker - The end marker string
+ * @returns Content with marker block removed, or original content if markers not found/invalid
+ */
+export declare function removeMarkerBlock(content: string, startMarker: string, endMarker: string): string;

package/node_modules/@freeharness/sdd/dist/vendor/openspec/engine/file-system.js

@@ -0,0 +1,394 @@
+// Vendored faithfully from @fission-ai/openspec@1.8.0
+//   src/utils/file-system.ts
+// No behavioural changes. The schema-validation slice only uses
+// FileSystemUtils.assertPathWithin (called from resolver.ts), but the full
+// utility is kept intact to stay faithful to upstream.
+import * as nodeFs from 'fs';
+import path from 'path';
+const fs = nodeFs.promises;
+const { constants: fsConstants } = nodeFs;
+function hasOwnerGroupOrOtherWriteBit(stats) {
+    return (stats.mode & 0o222) !== 0;
+}
+function hasOwnerGroupOrOtherExecuteBit(stats) {
+    return (stats.mode & 0o111) !== 0;
+}
+async function hasWritableModeAndAccess(targetPath) {
+    try {
+        const stats = await fs.stat(targetPath);
+        // POSIX root can often write despite mode bits, but OpenSpec should respect
+        // explicit read-only file/directory modes when deciding whether an install
+        // path is user-writable. This also keeps permission checks deterministic in
+        // root-run CI containers. On Windows, chmod mode bits are not authoritative,
+        // so rely on fs.access below.
+        if (process.platform !== 'win32' && !hasOwnerGroupOrOtherWriteBit(stats)) {
+            return false;
+        }
+        if (process.platform !== 'win32' && stats.isDirectory() && !hasOwnerGroupOrOtherExecuteBit(stats)) {
+            return false;
+        }
+        const accessMode = stats.isDirectory()
+            ? fsConstants.W_OK | fsConstants.X_OK
+            : fsConstants.W_OK;
+        await fs.access(targetPath, accessMode);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function isMarkerOnOwnLine(content, markerIndex, markerLength) {
+    let leftIndex = markerIndex - 1;
+    while (leftIndex >= 0 && content[leftIndex] !== '\n') {
+        const char = content[leftIndex];
+        if (char !== ' ' && char !== '\t' && char !== '\r') {
+            return false;
+        }
+        leftIndex--;
+    }
+    let rightIndex = markerIndex + markerLength;
+    while (rightIndex < content.length && content[rightIndex] !== '\n') {
+        const char = content[rightIndex];
+        if (char !== ' ' && char !== '\t' && char !== '\r') {
+            return false;
+        }
+        rightIndex++;
+    }
+    return true;
+}
+function findMarkerIndex(content, marker, fromIndex = 0) {
+    let currentIndex = content.indexOf(marker, fromIndex);
+    while (currentIndex !== -1) {
+        if (isMarkerOnOwnLine(content, currentIndex, marker.length)) {
+            return currentIndex;
+        }
+        currentIndex = content.indexOf(marker, currentIndex + marker.length);
+    }
+    return -1;
+}
+export class FileSystemUtils {
+    /**
+     * Converts a path to use forward slashes (POSIX style).
+     * Essential for cross-platform compatibility with glob libraries like fast-glob.
+     */
+    static toPosixPath(p) {
+        return p.replace(/\\/g, '/');
+    }
+    /**
+     * Returns a canonical absolute path when the target exists.
+     * Falls back to path.resolve() so callers can still produce a stable absolute path.
+     */
+    static canonicalizeExistingPath(targetPath) {
+        try {
+            // Prefer the native resolver so Windows short-path aliases are expanded.
+            return nodeFs.realpathSync.native(targetPath);
+        }
+        catch {
+            try {
+                return nodeFs.realpathSync(targetPath);
+            }
+            catch {
+                return path.resolve(targetPath);
+            }
+        }
+    }
+    /**
+     * Refuses a target that leaves an allowed directory, including through an
+     * existing symlink in either the target or one of its parent directories.
+     * Missing suffixes are resolved from their nearest existing ancestor.
+     */
+    static assertPathWithin(allowedDirectory, targetPath) {
+        const resolvedDirectory = path.resolve(allowedDirectory);
+        const resolvedTarget = path.resolve(targetPath);
+        if (!this.isPathWithin(resolvedDirectory, resolvedTarget)) {
+            throw new Error(`Path is outside the allowed directory: ${targetPath}`);
+        }
+        const canonicalDirectory = this.canonicalizePotentialPath(resolvedDirectory);
+        const canonicalTarget = this.canonicalizePotentialPath(resolvedTarget);
+        if (!this.isPathWithin(canonicalDirectory, canonicalTarget)) {
+            throw new Error(`Path is outside the allowed directory: ${targetPath}`);
+        }
+    }
+    static resolveProjectArtifactPath(projectPath, artifactPath) {
+        if (path.isAbsolute(artifactPath)) {
+            throw new Error(`Refusing to manage an artifact outside the project: ${artifactPath}`);
+        }
+        const targetPath = path.join(projectPath, artifactPath);
+        this.assertPathWithin(projectPath, targetPath);
+        return targetPath;
+    }
+    static assertProjectArtifactPath(projectPath, targetPath) {
+        this.assertPathWithin(projectPath, targetPath);
+    }
+    static isPathWithin(allowedDirectory, targetPath) {
+        const relative = path.relative(allowedDirectory, targetPath);
+        return (relative === '' ||
+            (relative !== '..' &&
+                !relative.startsWith(`..${path.sep}`) &&
+                !path.isAbsolute(relative)));
+    }
+    static canonicalizePotentialPath(targetPath) {
+        let existingPath = targetPath;
+        const missingSegments = [];
+        while (true) {
+            try {
+                // lstat distinguishes a missing path from a dangling symlink. A
+                // dangling link cannot be proven confined, so realpath must fail it.
+                nodeFs.lstatSync(existingPath);
+                const canonicalExisting = nodeFs.realpathSync.native(existingPath);
+                return path.resolve(canonicalExisting, ...missingSegments);
+            }
+            catch (error) {
+                const code = error.code;
+                if (code !== 'ENOENT') {
+                    throw error;
+                }
+                try {
+                    if (nodeFs.lstatSync(existingPath).isSymbolicLink()) {
+                        throw new Error(`Cannot verify dangling symbolic link: ${existingPath}`);
+                    }
+                }
+                catch (lstatError) {
+                    if (lstatError.code !== 'ENOENT') {
+                        throw lstatError;
+                    }
+                }
+                const parent = path.dirname(existingPath);
+                if (parent === existingPath) {
+                    throw new Error(`Cannot resolve an existing parent for ${targetPath}`);
+                }
+                missingSegments.unshift(path.basename(existingPath));
+                existingPath = parent;
+            }
+        }
+    }
+    static isWindowsBasePath(basePath) {
+        return /^[A-Za-z]:[\\/]/.test(basePath) || basePath.startsWith('\\');
+    }
+    static normalizeSegments(segments) {
+        return segments
+            .flatMap((segment) => segment.split(/[\\/]+/u))
+            .filter((part) => part.length > 0);
+    }
+    static joinPath(basePath, ...segments) {
+        const normalizedSegments = this.normalizeSegments(segments);
+        if (this.isWindowsBasePath(basePath)) {
+            const normalizedBasePath = path.win32.normalize(basePath);
+            return normalizedSegments.length
+                ? path.win32.join(normalizedBasePath, ...normalizedSegments)
+                : normalizedBasePath;
+        }
+        const posixBasePath = basePath.replace(/\\/g, '/');
+        return normalizedSegments.length
+            ? path.posix.join(posixBasePath, ...normalizedSegments)
+            : path.posix.normalize(posixBasePath);
+    }
+    static async createDirectory(dirPath) {
+        await fs.mkdir(dirPath, { recursive: true });
+    }
+    static async fileExists(filePath) {
+        try {
+            await fs.access(filePath);
+            return true;
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT') {
+                console.debug(`Unable to check if file exists at ${filePath}: ${error.message}`);
+            }
+            return false;
+        }
+    }
+    /**
+     * Finds the first existing parent directory by walking up the directory tree.
+     * @param dirPath Starting directory path
+     * @returns The first existing directory path, or null if root is reached without finding one
+     */
+    static async findFirstExistingDirectory(dirPath) {
+        let currentDir = dirPath;
+        while (true) {
+            try {
+                const stats = await fs.stat(currentDir);
+                if (stats.isDirectory()) {
+                    return currentDir;
+                }
+                // Path component exists but is not a directory (edge case)
+                console.debug(`Path component ${currentDir} exists but is not a directory`);
+                return null;
+            }
+            catch (error) {
+                if (error.code === 'ENOENT') {
+                    // Directory doesn't exist, move up one level
+                    const parentDir = path.dirname(currentDir);
+                    if (parentDir === currentDir) {
+                        // Reached filesystem root without finding existing directory
+                        return null;
+                    }
+                    currentDir = parentDir;
+                }
+                else {
+                    // Unexpected error (permissions, I/O error, etc.)
+                    console.debug(`Error checking directory ${currentDir}: ${error.message}`);
+                    return null;
+                }
+            }
+        }
+    }
+    static async canWriteFile(filePath) {
+        try {
+            const stats = await fs.stat(filePath);
+            if (stats.isDirectory()) {
+                return hasWritableModeAndAccess(filePath);
+            }
+            if (!stats.isFile()) {
+                return true;
+            }
+            return hasWritableModeAndAccess(filePath);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                // File doesn't exist - find first existing parent directory and check its permissions
+                const parentDir = path.dirname(filePath);
+                const existingDir = await this.findFirstExistingDirectory(parentDir);
+                if (existingDir === null) {
+                    // No existing parent directory found (edge case)
+                    return false;
+                }
+                // Check if the existing parent directory is writable.
+                return hasWritableModeAndAccess(existingDir);
+            }
+            console.debug(`Unable to determine write permissions for ${filePath}: ${error.message}`);
+            return false;
+        }
+    }
+    static async directoryExists(dirPath) {
+        try {
+            const stats = await fs.stat(dirPath);
+            return stats.isDirectory();
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT') {
+                console.debug(`Unable to check if directory exists at ${dirPath}: ${error.message}`);
+            }
+            return false;
+        }
+    }
+    static async writeFile(filePath, content) {
+        const dir = path.dirname(filePath);
+        await this.createDirectory(dir);
+        await fs.writeFile(filePath, content, 'utf-8');
+    }
+    static async readFile(filePath) {
+        return await fs.readFile(filePath, 'utf-8');
+    }
+    static async updateFileWithMarkers(filePath, content, startMarker, endMarker) {
+        let existingContent = '';
+        if (await this.fileExists(filePath)) {
+            existingContent = await this.readFile(filePath);
+            const startIndex = findMarkerIndex(existingContent, startMarker);
+            const endIndex = startIndex !== -1
+                ? findMarkerIndex(existingContent, endMarker, startIndex + startMarker.length)
+                : findMarkerIndex(existingContent, endMarker);
+            if (startIndex !== -1 && endIndex !== -1) {
+                if (endIndex < startIndex) {
+                    throw new Error(`Invalid marker state in ${filePath}. End marker appears before start marker.`);
+                }
+                const before = existingContent.substring(0, startIndex);
+                const after = existingContent.substring(endIndex + endMarker.length);
+                existingContent = before + startMarker + '\n' + content + '\n' + endMarker + after;
+            }
+            else if (startIndex === -1 && endIndex === -1) {
+                existingContent = startMarker + '\n' + content + '\n' + endMarker + '\n\n' + existingContent;
+            }
+            else {
+                throw new Error(`Invalid marker state in ${filePath}. Found start: ${startIndex !== -1}, Found end: ${endIndex !== -1}`);
+            }
+        }
+        else {
+            existingContent = startMarker + '\n' + content + '\n' + endMarker;
+        }
+        await this.writeFile(filePath, existingContent);
+    }
+    static async ensureWritePermissions(dirPath) {
+        try {
+            // If directory doesn't exist, check parent directory permissions
+            if (!await this.directoryExists(dirPath)) {
+                const parentDir = path.dirname(dirPath);
+                if (!await this.directoryExists(parentDir)) {
+                    await this.createDirectory(parentDir);
+                }
+                return await this.ensureWritePermissions(parentDir);
+            }
+            const testFile = path.join(dirPath, '.openspec-test-' + Date.now() + '-' + Math.random().toString(36).slice(2));
+            await fs.writeFile(testFile, '');
+            // On Windows, file may be temporarily locked by antivirus or indexing services.
+            // Retry unlink with a small delay if it fails.
+            const maxRetries = 3;
+            for (let attempt = 0; attempt < maxRetries; attempt++) {
+                try {
+                    await fs.unlink(testFile);
+                    break;
+                }
+                catch (unlinkError) {
+                    if (attempt === maxRetries - 1) {
+                        // Last attempt failed, but we successfully wrote the file, so permissions are OK
+                        // Just log and continue - the temp file will be cleaned up eventually
+                        console.debug(`Could not clean up test file ${testFile}: ${unlinkError.message}`);
+                    }
+                    else {
+                        // Wait briefly before retrying (Windows file lock release)
+                        await new Promise((resolve) => setTimeout(resolve, 50));
+                    }
+                }
+            }
+            return true;
+        }
+        catch (error) {
+            console.debug(`Insufficient permissions to write to ${dirPath}: ${error.message}`);
+            return false;
+        }
+    }
+}
+/**
+ * Removes a marker block from file content.
+ * Only removes markers that are on their own lines (ignores inline mentions).
+ * Cleans up double blank lines that may result from removal.
+ *
+ * @param content - File content with markers
+ * @param startMarker - The start marker string
+ * @param endMarker - The end marker string
+ * @returns Content with marker block removed, or original content if markers not found/invalid
+ */
+export function removeMarkerBlock(content, startMarker, endMarker) {
+    const startIndex = findMarkerIndex(content, startMarker);
+    const endIndex = startIndex !== -1
+        ? findMarkerIndex(content, endMarker, startIndex + startMarker.length)
+        : findMarkerIndex(content, endMarker);
+    if (startIndex === -1 || endIndex === -1 || endIndex <= startIndex) {
+        return content;
+    }
+    // Find the start of the line containing the start marker
+    let lineStart = startIndex;
+    while (lineStart > 0 && content[lineStart - 1] !== '\n') {
+        lineStart--;
+    }
+    // Find the end of the line containing the end marker
+    let lineEnd = endIndex + endMarker.length;
+    while (lineEnd < content.length && content[lineEnd] !== '\n') {
+        lineEnd++;
+    }
+    // Include the trailing newline if present
+    if (lineEnd < content.length && content[lineEnd] === '\n') {
+        lineEnd++;
+    }
+    const before = content.substring(0, lineStart);
+    const after = content.substring(lineEnd);
+    // Clean up double blank lines (handle both Unix \n and Windows \r\n)
+    let result = before + after;
+    result = result.replace(/(\r?\n){3,}/g, '\n\n');
+    // Trim trailing whitespace but preserve leading whitespace and original newline style
+    if (result.trimEnd() === '') {
+        return '';
+    }
+    const newline = content.includes('\r\n') ? '\r\n' : '\n';
+    return result.trimEnd() + newline;
+}