orbital-command 0.1.4 → 0.3.0

package/dist/server/server/services/scope-service.js

@@ -1,7 +1,7 @@
 import fs from 'fs';
 import path from 'path';
 import matter from 'gray-matter';
-import { normalizeStatus, parseAllScopes, parseScopeFile, setValidStatuses } from '../parsers/scope-parser.js';
+import { parseAllScopes, parseScopeFile, setValidStatuses } from '../parsers/scope-parser.js';
 import { createLogger } from '../utils/logger.js';
 const log = createLogger('scope');
 export class ScopeService {
@@ -38,6 +38,44 @@ export class ScopeService {
         this.cache.loadAll(scopes);
         return scopes.length;
     }
+    /** Reconcile files whose directory doesn't match their frontmatter status.
+     *  Frontmatter is the authoritative source — files are moved to match it.
+     *  Called once at startup after syncFromFilesystem(). */
+    reconcileDirectories() {
+        let moved = 0;
+        for (const scope of this.cache.getAll()) {
+            if (scope.id < 0)
+                continue; // slug-only icebox items (negative IDs)
+            const currentDir = path.basename(path.dirname(scope.file_path));
+            if (currentDir === scope.status)
+                continue;
+            if (!this.engine.isValidStatus(scope.status))
+                continue;
+            const targetDir = path.join(this.scopesDir, scope.status);
+            if (!fs.existsSync(targetDir))
+                fs.mkdirSync(targetDir, { recursive: true });
+            const newPath = path.join(targetDir, path.basename(scope.file_path));
+            this.suppressedPaths.add(scope.file_path);
+            this.suppressedPaths.add(newPath);
+            try {
+                fs.renameSync(scope.file_path, newPath);
+                this.updateFromFile(newPath);
+                this.removeByFilePath(scope.file_path);
+                moved++;
+                log.warn('Reconciled directory mismatch', {
+                    id: scope.id, frontmatter: scope.status, directory: currentDir,
+                });
+            }
+            catch (err) {
+                log.error('Failed to reconcile scope directory', { id: scope.id, error: String(err) });
+            }
+            setTimeout(() => {
+                this.suppressedPaths.delete(scope.file_path);
+                this.suppressedPaths.delete(newPath);
+            }, 2000);
+        }
+        return moved;
+    }
     /** Check if a path is suppressed from watcher processing (during programmatic moves) */
     isSuppressed(filePath) {
         return this.suppressedPaths.has(filePath);
@@ -89,6 +127,7 @@ export class ScopeService {
     }
     /** Update a scope's status with transition validation.
      *  Writes the new status to the frontmatter file and updates the cache.
+     *  This is the SINGLE validation point — all status changes must flow through here.
      *  @param context - caller trust level: 'patch', 'dispatch', 'event', 'bulk-sync', 'rollback' */
     updateStatus(id, status, context = 'patch') {
         if (!this.engine.isValidStatus(status)) {
@@ -111,12 +150,11 @@ export class ScopeService {
             if (!check.ok)
                 return check;
         }
-        // Write to filesystem via updateScopeFrontmatter (which updates cache + emits)
-        const current = context === 'bulk-sync' || context === 'rollback'
-            ? this.cache.getById(id)
-            : this.cache.getById(id); // already fetched above for validation, but may be null in bulk-sync
+        // Fetch current scope for fromStatus logging. In bulk-sync/rollback contexts
+        // the validation block above is skipped, so this may be the first lookup.
+        const current = this.cache.getById(id);
         const fromStatus = current?.status ?? 'unknown';
-        const result = this.updateScopeFrontmatter(id, { status }, context);
+        const result = this._writeFrontmatter(id, { status });
         if (result.ok) {
             log.info('Status updated', { id, from: fromStatus, to: status, context });
             for (const cb of this.onStatusChangeCallbacks)
@@ -124,8 +162,31 @@ export class ScopeService {
         }
         return result;
     }
+    /** Update scope fields via a public API (e.g. PATCH route).
+     *  Status changes are routed through updateStatus for validation.
+     *  Non-status fields are written directly via _writeFrontmatter. */
+    updateFields(id, fields) {
+        const { status, ...nonStatusFields } = fields;
+        // Status changes go through updateStatus (validates transition, fires callbacks)
+        if (status) {
+            const current = this.cache.getById(id);
+            if (!current)
+                return { ok: false, error: 'Scope not found', code: 'NOT_FOUND' };
+            if (status !== current.status) {
+                const result = this.updateStatus(id, status);
+                if (!result.ok)
+                    return result;
+            }
+        }
+        // Non-status field updates written directly
+        if (Object.keys(nonStatusFields).length > 0) {
+            return this._writeFrontmatter(id, nonStatusFields);
+        }
+        return { ok: true, moved: !!status };
+    }
     /** Compute the next sequential scope ID by scanning all non-icebox scopes.
-     *  Checks both filesystem (all subdirs except icebox) and cache to prevent collisions. */
+     *  Checks both filesystem (all subdirs except icebox) and cache to prevent collisions.
+     *  Skips IDs >= 500 to handle legacy icebox-origin files during migration. */
     getNextScopeId() {
         let maxId = 0;
         // Scan all scope subdirectories except icebox
@@ -136,8 +197,13 @@ export class ScopeService {
                 const dirPath = path.join(this.scopesDir, dir.name);
                 for (const file of fs.readdirSync(dirPath)) {
                     const m = file.match(/^(\d+)-/);
-                    if (m)
-                        maxId = Math.max(maxId, parseInt(m[1], 10));
+                    if (!m)
+                        continue;
+                    const id = parseInt(m[1], 10);
+                    // Skip legacy icebox-origin IDs (500+) to prevent namespace pollution
+                    if (id >= 500)
+                        continue;
+                    maxId = Math.max(maxId, id);
                 }
             }
         }
@@ -147,50 +213,61 @@ export class ScopeService {
         return maxId + 1;
     }
     // ─── Idea CRUD (filesystem-backed icebox cards) ────────────
-    /** Get the next available icebox ID (starts at 501, increments from max found) */
-    getNextIceboxId() {
-        const iceboxDir = path.join(this.scopesDir, 'icebox');
-        if (!fs.existsSync(iceboxDir))
-            return 501;
-        let maxId = 500;
-        for (const file of fs.readdirSync(iceboxDir)) {
-            const m = file.match(/^(\d+)-/);
-            if (m)
-                maxId = Math.max(maxId, parseInt(m[1], 10));
+    /** Normalize Date objects in gray-matter frontmatter to YYYY-MM-DD strings */
+    normalizeFrontmatterDates(data) {
+        for (const key of Object.keys(data)) {
+            if (data[key] instanceof Date) {
+                data[key] = data[key].toISOString().split('T')[0];
+            }
         }
-        return maxId + 1;
     }
-    /** Find an icebox file by its ID prefix.
-     *  Matches both padded (091-) and unpadded (91-) filenames
-     *  since demoted scopes keep their 3-digit-padded names. */
-    findIdeaFile(iceboxDir, id) {
+    /** Generate a slug from a title */
+    slugify(title) {
+        const slug = title
+            .toLowerCase()
+            .replace(/[^a-z0-9]+/g, '-')
+            .replace(/^-|-$/g, '')
+            .slice(0, 60);
+        if (!slug)
+            return 'untitled';
+        return slug;
+    }
+    /** Find an icebox file by its slug.
+     *  Matches slug-only files ({slug}.md) and legacy numeric-prefixed files ({NNN}-{slug}.md). */
+    findIdeaFile(iceboxDir, slug) {
         if (!fs.existsSync(iceboxDir))
             return null;
         const match = fs.readdirSync(iceboxDir).find((f) => {
             if (!f.endsWith('.md'))
                 return false;
-            const m = f.match(/^(\d+)-/);
-            return m != null && parseInt(m[1], 10) === id;
+            // Match slug-only: {slug}.md
+            if (f === `${slug}.md`)
+                return true;
+            // Match legacy numeric-prefixed: {NNN}-{slug}.md
+            return f.match(/^\d+-/) && f.slice(f.indexOf('-') + 1) === `${slug}.md`;
         });
         return match ? path.join(iceboxDir, match) : null;
     }
-    /** Create an icebox idea as a markdown file. IDs start at 501. */
+    /** Create an icebox idea as a slug-only markdown file. */
     createIdeaFile(title, description) {
         const iceboxDir = path.join(this.scopesDir, 'icebox');
         if (!fs.existsSync(iceboxDir))
             fs.mkdirSync(iceboxDir, { recursive: true });
-        const nextId = this.getNextIceboxId();
-        const slug = title
-            .toLowerCase()
-            .replace(/[^a-z0-9]+/g, '-')
-            .replace(/^-|-$/g, '')
-            .slice(0, 60);
-        const fileName = `${nextId}-${slug}.md`;
-        const filePath = path.join(iceboxDir, fileName);
+        const slug = this.slugify(title);
+        let fileName = `${slug}.md`;
+        let filePath = path.join(iceboxDir, fileName);
+        // Handle slug collisions by appending -2, -3, etc.
+        if (fs.existsSync(filePath)) {
+            let suffix = 2;
+            while (fs.existsSync(path.join(iceboxDir, `${slug}-${suffix}.md`)))
+                suffix++;
+            fileName = `${slug}-${suffix}.md`;
+            filePath = path.join(iceboxDir, fileName);
+        }
+        const finalSlug = fileName.replace(/\.md$/, '');
         const now = new Date().toISOString().split('T')[0];
         const content = [
             '---',
-            `id: ${nextId}`,
             `title: "${title.replace(/"/g, '\\"')}"`,
             'status: icebox',
             `created: ${now}`,
@@ -206,105 +283,124 @@ export class ScopeService {
         fs.writeFileSync(filePath, content, 'utf-8');
         // Eagerly sync to cache + emit scope:created
         this.updateFromFile(filePath);
-        log.info('Idea created', { id: nextId, title });
-        return { id: nextId, title };
+        log.info('Idea created', { slug: finalSlug, title });
+        return { slug: finalSlug, title };
     }
-    /** Update an icebox idea's title and description by rewriting its file */
-    updateIdeaFile(id, title, description) {
+    /** Update an icebox idea's title and description in-place. Renames the file if the title slug changes. */
+    updateIdeaFile(slug, title, description) {
         const iceboxDir = path.join(this.scopesDir, 'icebox');
-        const filePath = this.findIdeaFile(iceboxDir, id);
+        const filePath = this.findIdeaFile(iceboxDir, slug);
         if (!filePath)
             return false;
         // Preserve the original created date from existing frontmatter
         const existing = fs.readFileSync(filePath, 'utf-8');
-        const createdMatch = existing.match(/^created:\s*(.+)$/m);
-        const created = createdMatch?.[1]?.trim() ?? new Date().toISOString().split('T')[0];
+        const parsed = matter(existing);
+        const created = parsed.data.created ? String(parsed.data.created) : new Date().toISOString().split('T')[0];
         const now = new Date().toISOString().split('T')[0];
-        const content = [
-            '---',
-            `id: ${id}`,
-            `title: "${title.replace(/"/g, '\\"')}"`,
-            'status: icebox',
-            `created: ${created}`,
-            `updated: ${now}`,
-            'blocked_by: []',
-            'blocks: []',
-            'tags: []',
-            '---',
-            '',
-            description || '',
-            '',
-        ].join('\n');
-        fs.writeFileSync(filePath, content, 'utf-8');
-        // Watcher handles cache sync + scope:updated event
+        // Update frontmatter fields while preserving other data (like ghost)
+        parsed.data.title = title;
+        parsed.data.updated = now;
+        parsed.data.created = created;
+        this.normalizeFrontmatterDates(parsed.data);
+        const newContent = matter.stringify(description ? `\n${description}\n` : '\n', parsed.data);
+        fs.writeFileSync(filePath, newContent, 'utf-8');
+        // If title changed, rename file to new slug
+        const newSlug = this.slugify(title);
+        if (newSlug !== slug) {
+            const newFileName = `${newSlug}.md`;
+            const newPath = path.join(iceboxDir, newFileName);
+            if (!fs.existsSync(newPath)) {
+                this.suppressedPaths.add(filePath);
+                this.suppressedPaths.add(newPath);
+                this.removeByFilePath(filePath);
+                fs.renameSync(filePath, newPath);
+                this.updateFromFile(newPath);
+                setTimeout(() => {
+                    this.suppressedPaths.delete(filePath);
+                    this.suppressedPaths.delete(newPath);
+                }, 2000);
+            }
+            else {
+                // Collision with existing slug — keep old filename, still sync content changes
+                log.warn('Slug collision during rename, keeping old filename', { slug, newSlug });
+                this.updateFromFile(filePath);
+            }
+        }
+        else {
+            // Eagerly sync content changes to cache
+            this.updateFromFile(filePath);
+        }
         return true;
     }
     /** Delete an icebox idea by removing its file */
-    deleteIdeaFile(id) {
+    deleteIdeaFile(slug) {
         const iceboxDir = path.join(this.scopesDir, 'icebox');
-        const filePath = this.findIdeaFile(iceboxDir, id);
+        const filePath = this.findIdeaFile(iceboxDir, slug);
         if (!filePath)
             return false;
         fs.unlinkSync(filePath);
         // Eagerly remove from cache + emit scope:deleted
         this.removeByFilePath(filePath);
-        log.info('Idea deleted', { id });
+        log.info('Idea deleted', { slug });
         return true;
     }
     /** Promote an icebox idea to planning — assigns a proper sequential scope ID,
      *  moves the file, and syncs cache. Returns the new scope ID. */
-    promoteIdea(id) {
+    promoteIdea(slug) {
         const iceboxDir = path.join(this.scopesDir, 'icebox');
-        const oldPath = this.findIdeaFile(iceboxDir, id);
+        const oldPath = this.findIdeaFile(iceboxDir, slug);
         if (!oldPath)
             return null;
         // Read existing file for metadata
-        const content = fs.readFileSync(oldPath, 'utf-8');
-        const titleMatch = content.match(/^title:\s*"?([^"\n]+)"?\s*$/m);
-        const createdMatch = content.match(/^created:\s*(.+)$/m);
-        const title = titleMatch?.[1]?.trim() ?? 'Untitled';
-        const created = createdMatch?.[1]?.trim() ?? new Date().toISOString().split('T')[0];
-        // Extract body after frontmatter
-        const fmEnd = content.indexOf('---', content.indexOf('---') + 3);
-        const description = fmEnd !== -1 ? content.slice(fmEnd + 3).trim() : '';
+        const raw = fs.readFileSync(oldPath, 'utf-8');
+        const parsed = matter(raw);
+        const title = parsed.data.title ? String(parsed.data.title) : 'Untitled';
+        const created = parsed.data.created ? String(parsed.data.created) : new Date().toISOString().split('T')[0];
+        const description = parsed.content.trim();
         // Assign the next sequential scope ID (excludes icebox items)
         const newId = this.getNextScopeId();
         const paddedId = String(newId).padStart(3, '0');
-        // Build slug and new path
-        const slug = title
-            .toLowerCase()
-            .replace(/[^a-z0-9]+/g, '-')
-            .replace(/^-|-$/g, '')
-            .slice(0, 60);
+        // Build new path
+        const titleSlug = this.slugify(title);
         const planningDir = path.join(this.scopesDir, 'planning');
         if (!fs.existsSync(planningDir))
             fs.mkdirSync(planningDir, { recursive: true });
-        const newFileName = `${paddedId}-${slug}.md`;
+        const newFileName = `${paddedId}-${titleSlug}.md`;
         const newPath = path.join(planningDir, newFileName);
         const now = new Date().toISOString().split('T')[0];
-        // Write new file with planning status and new sequential ID
-        const newContent = [
-            '---',
-            `id: ${paddedId}`,
-            `title: "${title.replace(/"/g, '\\"')}"`,
-            'status: planning',
-            `created: ${created}`,
-            `updated: ${now}`,
-            'blocked_by: []',
-            'blocks: []',
-            'tags: []',
-            '---',
-            '',
-            description || '',
-            '',
-        ].join('\n');
-        fs.writeFileSync(newPath, newContent, 'utf-8');
-        // Sync cache before deleting old file (avoids window where scope is missing)
+        // Update frontmatter in-place: assign ID and change status (preserve other fields)
+        parsed.data.id = newId;
+        parsed.data.status = 'planning';
+        parsed.data.updated = now;
+        parsed.data.created = created;
+        delete parsed.data.ghost;
+        this.normalizeFrontmatterDates(parsed.data);
+        const newContent = matter.stringify(parsed.content, parsed.data);
+        // Write updated content to old path, then rename/move (no intermediate missing state)
+        const originalContent = fs.readFileSync(oldPath, 'utf-8');
+        fs.writeFileSync(oldPath, newContent, 'utf-8');
+        // Suppress watcher events during programmatic move
+        this.suppressedPaths.add(oldPath);
+        this.suppressedPaths.add(newPath);
+        try {
+            fs.renameSync(oldPath, newPath);
+        }
+        catch (err) {
+            // Restore original content on rename failure
+            fs.writeFileSync(oldPath, originalContent, 'utf-8');
+            this.suppressedPaths.delete(oldPath);
+            this.suppressedPaths.delete(newPath);
+            log.error('Failed to rename during promote', { oldPath, newPath, error: String(err) });
+            return null;
+        }
         this.updateFromFile(newPath);
-        fs.unlinkSync(oldPath);
         this.removeByFilePath(oldPath);
+        setTimeout(() => {
+            this.suppressedPaths.delete(oldPath);
+            this.suppressedPaths.delete(newPath);
+        }, 2000);
         const relPath = path.relative(path.resolve(this.scopesDir, '..'), newPath);
-        log.info('Idea promoted', { oldId: id, newId, title });
+        log.info('Idea promoted', { slug, newId, title });
         return { id: newId, filePath: relPath, title, description };
     }
     /** Find a scope file by its numeric ID prefix across all status directories */
@@ -325,10 +421,11 @@ export class ScopeService {
         }
         return null;
     }
-    /** Update a scope's frontmatter fields and write back to the .md file.
-     *  If status changes, validates the transition and moves the file to the new status directory.
-     *  @param context - transition context for validation (default 'patch') */
-    updateScopeFrontmatter(id, fields, context = 'patch') {
+    /** Write frontmatter fields to a scope's .md file.
+     *  If the effective status differs from the current directory, moves the file.
+     *  This is a trusted write operation — callers must validate transitions
+     *  via updateStatus() before calling this method with status changes. */
+    _writeFrontmatter(id, fields) {
         const filePath = this.findScopeFile(id);
         if (!filePath) {
             return { ok: false, error: 'Scope file not found', code: 'NOT_FOUND' };
@@ -336,25 +433,19 @@ export class ScopeService {
         const raw = fs.readFileSync(filePath, 'utf-8');
         const parsed = matter(raw);
         const today = new Date().toISOString().split('T')[0];
-        // Validate status transition before any writes
+        // Determine if the file needs to move to a different directory.
+        // Compare against the DIRECTORY name (not frontmatter status) since the question
+        // is whether the physical file location matches the desired status.
         const newStatus = fields.status;
-        const rawOldStatus = String(parsed.data.status ?? 'planning');
-        const oldStatus = normalizeStatus(rawOldStatus);
-        let needsMove = false;
-        if (newStatus && newStatus !== oldStatus) {
-            if (!this.engine.isValidStatus(newStatus)) {
-                return { ok: false, error: `Invalid status: '${newStatus}'`, code: 'INVALID_STATUS' };
-            }
-            const check = this.engine.validateTransition(oldStatus, newStatus, context);
-            if (!check.ok)
-                return check;
-            needsMove = true;
-            // Auto-unlock spec when reverting backlog → planning
-            if (newStatus === 'planning' && oldStatus === 'backlog')
-                fields.spec_locked = false;
+        const dirName = path.basename(path.dirname(filePath));
+        const effectiveStatus = newStatus ?? String(parsed.data.status ?? dirName);
+        const needsMove = effectiveStatus !== dirName && this.engine.isValidStatus(effectiveStatus);
+        // Auto-unlock spec when reverting backlog → planning
+        if (newStatus === 'planning' && dirName === 'backlog') {
+            fields = { ...fields, spec_locked: false };
         }
         // Merge editable fields into frontmatter
-        const editableKeys = ['title', 'status', 'priority', 'effort_estimate', 'category', 'tags', 'blocked_by', 'blocks', 'spec_locked'];
+        const editableKeys = ['title', 'status', 'priority', 'effort_estimate', 'category', 'tags', 'blocked_by', 'blocks', 'spec_locked', 'favourite'];
         for (const key of editableKeys) {
             if (key in fields) {
                 const val = fields[key];
@@ -384,8 +475,8 @@ export class ScopeService {
             log.info('Frontmatter updated', { id, fields: Object.keys(fields) });
             return { ok: true };
         }
-        // Status change → move file to new directory
-        const targetDir = path.join(this.scopesDir, newStatus);
+        // Status differs from directory → move file to correct directory
+        const targetDir = path.join(this.scopesDir, effectiveStatus);
         if (!fs.existsSync(targetDir))
             fs.mkdirSync(targetDir, { recursive: true });
         const fileName = path.basename(filePath);
@@ -403,13 +494,13 @@ export class ScopeService {
         setTimeout(() => {
             this.suppressedPaths.delete(filePath);
             this.suppressedPaths.delete(newPath);
-        }, 500);
+        }, 2000);
         return { ok: true, moved: true };
     }
     /** Approve a ghost idea — removes ghost:true from frontmatter and refreshes cache */
-    approveGhostIdea(id) {
+    approveGhostIdea(slug) {
         const iceboxDir = path.join(this.scopesDir, 'icebox');
-        const filePath = this.findIdeaFile(iceboxDir, id);
+        const filePath = this.findIdeaFile(iceboxDir, slug);
         if (!filePath)
             return false;
         const content = fs.readFileSync(filePath, 'utf-8');
@@ -418,7 +509,7 @@ export class ScopeService {
         fs.writeFileSync(filePath, updated, 'utf-8');
         // Re-parse file to refresh cache with is_ghost=false
         this.updateFromFile(filePath);
-        log.info('Ghost approved', { id });
+        log.info('Ghost approved', { slug });
         return true;
     }
 }

package/dist/server/server/services/scope-service.test.js

@@ -0,0 +1,137 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { ScopeService } from './scope-service.js';
+import { ScopeCache } from './scope-cache.js';
+import { WorkflowEngine } from '../../shared/workflow-engine.js';
+import { CONFIG_WITH_HOOKS } from '../../shared/__fixtures__/workflow-configs.js';
+import { createMockEmitter } from '../__tests__/helpers/mock-emitter.js';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+describe('ScopeService', () => {
+    let tmpDir;
+    let cache;
+    let emitter;
+    let engine;
+    let service;
+    beforeEach(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'scope-svc-test-'));
+        cache = new ScopeCache();
+        emitter = createMockEmitter();
+        engine = new WorkflowEngine(CONFIG_WITH_HOOKS);
+        service = new ScopeService(cache, emitter, tmpDir, engine);
+        // Create status directories
+        for (const status of ['icebox', 'backlog', 'active', 'review', 'shipped']) {
+            fs.mkdirSync(path.join(tmpDir, status), { recursive: true });
+        }
+    });
+    afterEach(() => {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+    function writeScopeFile(status, filename, frontmatter, body = '') {
+        const filePath = path.join(tmpDir, status, filename);
+        const yamlLines = Object.entries(frontmatter).map(([k, v]) => {
+            if (Array.isArray(v))
+                return `${k}: [${v.join(', ')}]`;
+            return `${k}: ${v}`;
+        }).join('\n');
+        fs.writeFileSync(filePath, `---\n${yamlLines}\n---\n${body}\n`);
+        return filePath;
+    }
+    // ─── syncFromFilesystem() ─────────────────────────────────
+    describe('syncFromFilesystem()', () => {
+        it('loads all .md files into cache', () => {
+            writeScopeFile('backlog', '001-first.md', { title: 'First', status: 'backlog' });
+            writeScopeFile('active', '002-second.md', { title: 'Second', status: 'active' });
+            const count = service.syncFromFilesystem();
+            expect(count).toBe(2);
+            expect(cache.size).toBe(2);
+        });
+        it('returns 0 for empty directories', () => {
+            expect(service.syncFromFilesystem()).toBe(0);
+        });
+    });
+    // ─── getAll() / getById() ─────────────────────────────────
+    describe('getAll() / getById()', () => {
+        it('delegates to cache', () => {
+            writeScopeFile('backlog', '001-test.md', { title: 'Test', status: 'backlog' });
+            service.syncFromFilesystem();
+            expect(service.getAll()).toHaveLength(1);
+            expect(service.getById(1)?.title).toBe('Test');
+            expect(service.getById(999)).toBeUndefined();
+        });
+    });
+    // ─── updateStatus() ──────────────────────────────────────
+    describe('updateStatus()', () => {
+        beforeEach(() => {
+            writeScopeFile('backlog', '001-test.md', { title: 'Test', status: 'backlog' });
+            service.syncFromFilesystem();
+        });
+        it('validates transition via engine', () => {
+            // backlog → shipped is not a valid edge in CONFIG_WITH_HOOKS
+            const result = service.updateStatus(1, 'shipped', 'patch');
+            expect(result.ok).toBe(false);
+        });
+        it('bulk-sync bypasses validation', () => {
+            const result = service.updateStatus(1, 'shipped', 'bulk-sync');
+            expect(result.ok).toBe(true);
+        });
+        it('returns NOT_FOUND for unknown scope', () => {
+            const result = service.updateStatus(999, 'active', 'dispatch');
+            expect(result.ok).toBe(false);
+        });
+        it('fires onStatusChange callbacks on successful transition', () => {
+            const callback = vi.fn();
+            service.onStatusChange(callback);
+            // Use bulk-sync to bypass edge validation — focuses on the callback mechanism
+            const result = service.updateStatus(1, 'active', 'bulk-sync');
+            if (result.ok) {
+                expect(callback).toHaveBeenCalledWith(1, 'active');
+            }
+        });
+    });
+    // ─── createIdeaFile() ─────────────────────────────────────
+    describe('createIdeaFile()', () => {
+        it('creates file in icebox directory', () => {
+            const result = service.createIdeaFile('My New Idea', 'A description of the idea');
+            expect(result.slug).toBeDefined();
+            expect(result.title).toBe('My New Idea');
+            // Verify file exists
+            const files = fs.readdirSync(path.join(tmpDir, 'icebox'));
+            expect(files.length).toBe(1);
+            expect(files[0]).toMatch(/\.md$/);
+        });
+        it('slugifies the title', () => {
+            const result = service.createIdeaFile('Some Feature Idea!', '');
+            expect(result.slug).toMatch(/^[a-z0-9-]+$/);
+        });
+    });
+    // ─── deleteIdeaFile() ─────────────────────────────────────
+    describe('deleteIdeaFile()', () => {
+        it('removes the idea file', () => {
+            const { slug } = service.createIdeaFile('To Delete', '');
+            const result = service.deleteIdeaFile(slug);
+            expect(result).toBe(true);
+            const files = fs.readdirSync(path.join(tmpDir, 'icebox'));
+            expect(files).toHaveLength(0);
+        });
+        it('returns false for non-existent slug', () => {
+            expect(service.deleteIdeaFile('nonexistent-slug')).toBe(false);
+        });
+    });
+    // ─── reconcileDirectories() ───────────────────────────────
+    describe('reconcileDirectories()', () => {
+        it('moves files to correct directory based on frontmatter', () => {
+            // Put a file in backlog but with status: active in frontmatter
+            writeScopeFile('backlog', '001-misplaced.md', { title: 'Misplaced', status: 'active' });
+            service.syncFromFilesystem();
+            const moved = service.reconcileDirectories();
+            expect(moved).toBeGreaterThanOrEqual(0);
+        });
+    });
+    // ─── isSuppressed() ──────────────────────────────────────
+    describe('isSuppressed()', () => {
+        it('returns false by default', () => {
+            expect(service.isSuppressed('/some/path.md')).toBe(false);
+        });
+    });
+});