@opengsd/gsd-pi 1.2.0-dev.fbdca60b → 1.3.0-dev.65546769

package/dist/resources/extensions/gsd/mcp-filter.js

@@ -1,14 +1,37 @@
-import { existsSync, readFileSync } from "node:fs";
+import { readFileSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 import { resolve } from "node:path";
 import { isGsdBrowserMcpServerConfig } from "../shared/gsd-browser-cli.js";
 import { toMcpWildcardToolName } from "./mcp-tool-name.js";
 import { resolveModelMcpConfig } from "./preferences-mcp.js";
+const projectMcpDiscoveryCache = new Map();
 function isRecord(value) {
     return !!value && typeof value === "object" && !Array.isArray(value);
 }
-function readJsonFile(path, ignoreParseErrors = false) {
-    if (!existsSync(path))
+function getJsonFileSignature(path, ignoreAccessErrors = false) {
+    try {
+        const stats = statSync(path);
+        return { exists: true, mtimeMs: stats.mtimeMs, size: stats.size };
+    }
+    catch (err) {
+        const code = isRecord(err) ? err.code : undefined;
+        if (code === "ENOENT" || code === "ENOTDIR" || ignoreAccessErrors)
+            return { exists: false };
+        throw err;
+    }
+}
+function jsonFileSignaturesEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    return a.every((signature, index) => {
+        const other = b[index];
+        return signature.exists === other.exists
+            && signature.mtimeMs === other.mtimeMs
+            && signature.size === other.size;
+    });
+}
+function readJsonFile(path, ignoreParseErrors = false, signature = getJsonFileSignature(path, ignoreParseErrors)) {
+    if (!signature.exists)
         return undefined;
     try {
         return JSON.parse(readFileSync(path, "utf-8"));
@@ -25,12 +48,22 @@ function collectServerEntries(servers) {
     return Object.entries(servers).map(([name, config]) => ({ name, config }));
 }
 export function discoverMcpServers(projectDir) {
-    const mcpJsonPath = resolve(projectDir, ".mcp.json");
-    const settingsPath = resolve(projectDir, ".claude", "settings.json");
-    const localSettingsPath = resolve(projectDir, ".claude", "settings.local.json");
-    const mcpJson = readJsonFile(mcpJsonPath);
-    const settings = readJsonFile(settingsPath, true);
-    const localSettings = readJsonFile(localSettingsPath, true);
+    const resolvedProjectDir = resolve(projectDir);
+    const mcpJsonPath = resolve(resolvedProjectDir, ".mcp.json");
+    const settingsPath = resolve(resolvedProjectDir, ".claude", "settings.json");
+    const localSettingsPath = resolve(resolvedProjectDir, ".claude", "settings.local.json");
+    const signatures = [
+        getJsonFileSignature(mcpJsonPath, true),
+        getJsonFileSignature(settingsPath, true),
+        getJsonFileSignature(localSettingsPath, true),
+    ];
+    const cached = projectMcpDiscoveryCache.get(resolvedProjectDir);
+    if (cached && jsonFileSignaturesEqual(cached.signatures, signatures)) {
+        return [...cached.servers];
+    }
+    const mcpJson = readJsonFile(mcpJsonPath, false, signatures[0]);
+    const settings = readJsonFile(settingsPath, true, signatures[1]);
+    const localSettings = readJsonFile(localSettingsPath, true, signatures[2]);
     const seen = new Set();
     const discovered = [];
     for (const entry of [
@@ -44,7 +77,8 @@ export function discoverMcpServers(projectDir) {
         seen.add(entry.name);
         discovered.push(entry);
     }
-    return discovered;
+    projectMcpDiscoveryCache.set(resolvedProjectDir, { signatures, servers: discovered });
+    return [...discovered];
 }
 function isWorkflowMcpServerConfig(config) {
     if (!isRecord(config))

package/dist/resources/extensions/gsd/md-importer.js

@@ -4,11 +4,12 @@
 //
 // Exports: parseDecisionsTable, parseRequirementsSections, migrateFromMarkdown
 import { readFileSync, readdirSync, existsSync, statSync } from 'node:fs';
-import { join } from 'node:path';
+import { join, basename } from 'node:path';
 import { upsertDecision, upsertRequirement, insertArtifact, insertMilestone, insertSlice, insertTask, transaction, updateMilestoneStatus, updateSliceStatus, _getAdapter, } from './gsd-db.js';
 import { openWorkflowDatabasePath } from './db-workspace.js';
-import { resolveGsdRootFile, resolveMilestoneFile, resolveSliceFile, resolveTasksDir, milestonesDir, gsdRoot, resolveTaskFiles, } from './paths.js';
+import { resolveGsdRootFile, resolveMilestoneFile, resolveSliceFile, resolveTasksDir, legacyMilestonesDir, gsdRoot, resolveTaskFiles, resolveMilestonePath, } from './paths.js';
 import { findMilestoneIds } from './guided-flow.js';
+import { milestoneIdToPhaseNum } from './layout-policy.js';
 import { parseRoadmap, parsePlan } from './parsers-legacy.js';
 import { parseContextDependsOn } from './files.js';
 import { logWarning } from './workflow-logger.js';
@@ -278,7 +279,7 @@ function importRequirements(gsdDir) {
 // ─── Hierarchy Artifact Walker ─────────────────────────────────────────────
 /** Artifact suffixes to look for at each hierarchy level */
 const MILESTONE_SUFFIXES = ['ROADMAP', 'CONTEXT', 'RESEARCH', 'ASSESSMENT', 'SUMMARY', 'VALIDATION'];
-const SLICE_SUFFIXES = ['PLAN', 'SUMMARY', 'RESEARCH', 'CONTEXT', 'ASSESSMENT', 'UAT'];
+const SLICE_SUFFIXES = ['PLAN', 'SUMMARY', 'RESEARCH', 'CONTEXT', 'CONTEXT-DRAFT', 'ASSESSMENT', 'UAT', 'CONTINUE'];
 const TASK_SUFFIXES = ['PLAN', 'SUMMARY', 'CONTINUE', 'CONTEXT', 'RESEARCH'];
 /**
  * Import hierarchy artifacts (roadmaps, plans, summaries, etc.) from the .gsd/ tree.
@@ -305,55 +306,151 @@ function importHierarchyArtifacts(gsdDir) {
             count++;
         }
     }
-    // Walk milestones
+    // Walk phases (flat-phase layout: phases/NN-slug/, legacy: milestones/M001/)
     const milestoneIds = findMilestoneIds(gsdDir);
-    const msDir = milestonesDir(gsdDir);
+    const legacyDir = legacyMilestonesDir(gsdDir);
     for (const milestoneId of milestoneIds) {
-        // Find the actual milestone directory name (handles legacy naming)
-        const milestoneDirName = findDirByPrefix(msDir, milestoneId);
-        if (!milestoneDirName)
+        // Use resolveMilestonePath so canonical-name / newest-dir selection matches
+        // the same logic used by the renderer and reconciler, preventing import and
+        // render from landing on different phase trees for the same milestone.
+        const resolvedPhaseFullPath = resolveMilestonePath(gsdDir, milestoneId);
+        if (!resolvedPhaseFullPath) {
+            // Last resort: findDirByPrefix for legacy dirs
+            const milestoneDirName = findDirByPrefix(legacyDir, milestoneId);
+            if (!milestoneDirName)
+                continue;
+            count += importLegacyMilestoneArtifacts(join(legacyDir, milestoneDirName), milestoneDirName, milestoneId);
             continue;
-        const milestoneFullPath = join(msDir, milestoneDirName);
-        // Milestone-level files
-        count += importFilesAtLevel(milestoneFullPath, milestoneId, MILESTONE_SUFFIXES, `milestones/${milestoneDirName}`, milestoneId, null, null);
-        // Walk slices
-        const slicesDir = join(milestoneFullPath, 'slices');
-        if (!existsSync(slicesDir))
+        }
+        // Determine if this is a legacy (milestones/) or flat-phase (phases/) dir.
+        const legacyDirNorm = legacyDir.replace(/\\/g, "/");
+        const resolvedNorm = resolvedPhaseFullPath.replace(/\\/g, "/");
+        const isLegacyResolved = resolvedNorm.startsWith(legacyDirNorm + "/") || resolvedNorm === legacyDirNorm;
+        const phaseDirName = basename(resolvedPhaseFullPath);
+        if (isLegacyResolved) {
+            count += importLegacyMilestoneArtifacts(resolvedPhaseFullPath, phaseDirName, milestoneId);
             continue;
-        const sliceDirs = readdirSync(slicesDir, { withFileTypes: true })
-            .filter(d => d.isDirectory() && /^S\d+/.test(d.name))
-            .map(d => d.name)
+        }
+        const phaseFullPath = resolvedPhaseFullPath;
+        const phaseNum = milestoneIdToPhaseNum(milestoneId);
+        // Phase-level files (flat-phase: NN-SUFFIX.md, legacy: M001-SUFFIX.md)
+        const phasePrefix = `${String(phaseNum).padStart(2, "0")}`;
+        const artifactBase = `phases/${phaseDirName}`;
+        let phaseArtifacts = importFilesAtLevel(phaseFullPath, phasePrefix, MILESTONE_SUFFIXES, artifactBase, milestoneId, null, null);
+        if (phaseArtifacts === 0) {
+            phaseArtifacts = importFilesAtLevel(phaseFullPath, milestoneId, MILESTONE_SUFFIXES, artifactBase, milestoneId, null, null);
+        }
+        count += phaseArtifacts;
+        // Flat-phase: plan files are NN-MM-SUFFIX.md inside the phase dir.
+        // Also check legacy slices/ subdir for backward compat.
+        const planFiles = readdirSync(phaseFullPath, { withFileTypes: true })
+            .filter(f => f.isFile() && /^\d+-\d+-/.test(f.name))
+            .map(f => f.name)
             .sort();
-        for (const sliceDirName of sliceDirs) {
-            const sliceId = sliceDirName.match(/^(S\d+)/)?.[1] ?? sliceDirName;
-            const sliceFullPath = join(slicesDir, sliceDirName);
-            // Slice-level files
-            count += importFilesAtLevel(sliceFullPath, sliceId, SLICE_SUFFIXES, `milestones/${milestoneDirName}/slices/${sliceDirName}`, milestoneId, sliceId, null);
-            // Walk tasks
-            const tasksDir = join(sliceFullPath, 'tasks');
-            if (!existsSync(tasksDir))
+        for (const planFile of planFiles) {
+            const planMatch = planFile.match(/^\d+-(\d+)-([A-Z0-9-]+)\.md$/i);
+            if (!planMatch)
+                continue;
+            const planNum = parseInt(planMatch[1], 10);
+            const sliceId = `S${String(planNum).padStart(2, '0')}`;
+            const suffix = planMatch[2].toUpperCase();
+            const filePath = join(phaseFullPath, planFile);
+            if (!existsSync(filePath))
                 continue;
-            for (const suffix of TASK_SUFFIXES) {
-                const taskFiles = resolveTaskFiles(tasksDir, suffix);
-                for (const taskFileName of taskFiles) {
-                    const taskId = taskFileName.match(/^(T\d+)/)?.[1] ?? null;
-                    const taskFilePath = join(tasksDir, taskFileName);
-                    if (!existsSync(taskFilePath))
-                        continue;
-                    const content = readFileSync(taskFilePath, 'utf-8');
-                    const relPath = `milestones/${milestoneDirName}/slices/${sliceDirName}/tasks/${taskFileName}`;
-                    insertArtifact({
-                        path: relPath,
-                        artifact_type: suffix,
-                        milestone_id: milestoneId,
-                        slice_id: sliceId,
-                        task_id: taskId,
-                        full_content: content,
-                    });
-                    count++;
+            const content = readFileSync(filePath, 'utf-8');
+            insertArtifact({
+                path: `${artifactBase}/${planFile}`,
+                artifact_type: suffix,
+                milestone_id: milestoneId,
+                slice_id: sliceId,
+                task_id: null,
+                full_content: content,
+            });
+            count++;
+        }
+        // Legacy fallback: walk slices/ subdir if it exists
+        const slicesDir = join(phaseFullPath, 'slices');
+        if (existsSync(slicesDir)) {
+            const sliceDirs = readdirSync(slicesDir, { withFileTypes: true })
+                .filter(d => d.isDirectory() && /^S\d+/.test(d.name))
+                .map(d => d.name)
+                .sort();
+            for (const sliceDirName of sliceDirs) {
+                const sliceId = sliceDirName.match(/^(S\d+)/)?.[1] ?? sliceDirName;
+                const sliceFullPath = join(slicesDir, sliceDirName);
+                count += importFilesAtLevel(sliceFullPath, sliceId, SLICE_SUFFIXES, `phases/${phaseDirName}/slices/${sliceDirName}`, milestoneId, sliceId, null);
+                // Legacy tasks walk
+                const tasksDir = join(sliceFullPath, 'tasks');
+                if (!existsSync(tasksDir))
+                    continue;
+                for (const suffix of TASK_SUFFIXES) {
+                    const taskFiles = resolveTaskFiles(tasksDir, suffix);
+                    for (const taskFileName of taskFiles) {
+                        const taskId = taskFileName.match(/^(T\d+)/)?.[1] ?? null;
+                        const taskFilePath = join(tasksDir, taskFileName);
+                        if (!existsSync(taskFilePath))
+                            continue;
+                        const content = readFileSync(taskFilePath, 'utf-8');
+                        const relPath = `phases/${phaseDirName}/slices/${sliceDirName}/tasks/${taskFileName}`;
+                        insertArtifact({
+                            path: relPath,
+                            artifact_type: suffix,
+                            milestone_id: milestoneId,
+                            slice_id: sliceId,
+                            task_id: taskId,
+                            full_content: content,
+                        });
+                        count++;
+                    }
                 }
             }
         }
+        // Partial migration may leave nested milestones/M00N/ content alongside phases/.
+        const milestoneDirName = findDirByPrefix(legacyDir, milestoneId);
+        if (milestoneDirName) {
+            count += importLegacyMilestoneArtifacts(join(legacyDir, milestoneDirName), milestoneDirName, milestoneId);
+        }
+    }
+    return count;
+}
+/** Walk a pre-flat-phase milestones/M001/ tree when no phases/NN-slug dir exists. */
+function importLegacyMilestoneArtifacts(milestoneFullPath, milestoneDirName, milestoneId) {
+    let count = 0;
+    count += importFilesAtLevel(milestoneFullPath, milestoneId, MILESTONE_SUFFIXES, `milestones/${milestoneDirName}`, milestoneId, null, null);
+    const slicesDir = join(milestoneFullPath, 'slices');
+    if (!existsSync(slicesDir))
+        return count;
+    const sliceDirs = readdirSync(slicesDir, { withFileTypes: true })
+        .filter(d => d.isDirectory() && /^S\d+/.test(d.name))
+        .map(d => d.name)
+        .sort();
+    for (const sliceDirName of sliceDirs) {
+        const sliceId = sliceDirName.match(/^(S\d+)/)?.[1] ?? sliceDirName;
+        const sliceFullPath = join(slicesDir, sliceDirName);
+        count += importFilesAtLevel(sliceFullPath, sliceId, SLICE_SUFFIXES, `milestones/${milestoneDirName}/slices/${sliceDirName}`, milestoneId, sliceId, null);
+        const tasksDir = join(sliceFullPath, 'tasks');
+        if (!existsSync(tasksDir))
+            continue;
+        for (const suffix of TASK_SUFFIXES) {
+            const taskFiles = resolveTaskFiles(tasksDir, suffix);
+            for (const taskFileName of taskFiles) {
+                const taskId = taskFileName.match(/^(T\d+)/)?.[1] ?? null;
+                const taskFilePath = join(tasksDir, taskFileName);
+                if (!existsSync(taskFilePath))
+                    continue;
+                const content = readFileSync(taskFilePath, 'utf-8');
+                const relPath = `milestones/${milestoneDirName}/slices/${sliceDirName}/tasks/${taskFileName}`;
+                insertArtifact({
+                    path: relPath,
+                    artifact_type: suffix,
+                    milestone_id: milestoneId,
+                    slice_id: sliceId,
+                    task_id: taskId,
+                    full_content: content,
+                });
+                count++;
+            }
+        }
     }
     return count;
 }
@@ -418,9 +515,10 @@ function findFileByPrefixAndSuffix(dir, idPrefix, suffix) {
         const direct = entries.find(e => e.toUpperCase() === target);
         if (direct)
             return direct;
-        // Legacy: ID-DESCRIPTOR-SUFFIX.md
+        // Legacy: ID-DESCRIPTOR-SUFFIX.md — exclude double-numbered (NN-NN-*) slice
+        // files so a phase-prefix like "01" never matches a slice file "01-01-SUMMARY.md".
         const pattern = new RegExp(`^${idPrefix}-.*-${suffix}\\.md$`, 'i');
-        const match = entries.find(e => pattern.test(e));
+        const match = entries.find(e => pattern.test(e) && !/^\d+-\d+-/.test(e));
         return match ?? null;
     }
     catch {
@@ -564,9 +662,11 @@ export function migrateHierarchyToDb(basePath) {
             for (const taskEntry of plan.tasks) {
                 // Per K002: use 'complete' not 'done'
                 let taskStatus = taskEntry.done ? 'complete' : 'pending';
-                // Pre-migration consistency: if task is marked done in the plan but has
-                // no summary file on disk, import as 'pending' so it gets re-executed
-                // rather than silently importing bad state as the new DB authority.
+                // Pre-migration consistency (legacy layout only): if a task is marked
+                // done but has no per-task SUMMARY.md, import it as pending so it gets
+                // re-executed rather than silently entering the DB as complete.
+                // Flat-phase has no per-task summary files by design — the checkbox
+                // state is the authoritative completion signal and is imported as-is.
                 if (taskStatus === 'complete') {
                     const tDir = resolveTasksDir(basePath, milestoneId, sliceEntry.id);
                     if (tDir) {
@@ -600,11 +700,13 @@ export function migrateHierarchyToDb(basePath) {
                 const sliceSummaryPath = resolveSliceFile(basePath, milestoneId, sliceEntry.id, 'SUMMARY');
                 const hasSliceSummary = sliceSummaryPath !== null && existsSync(sliceSummaryPath);
                 const allTasksDone = plan.tasks.length > 0 && plan.tasks.every(t => {
+                    if (!t.done)
+                        return false;
                     const tDir = resolveTasksDir(basePath, milestoneId, sliceEntry.id);
+                    // Flat-phase has no per-task summary files — checkbox state is authoritative.
                     if (!tDir)
-                        return t.done;
-                    const summaryFile = join(tDir, `${t.id}-SUMMARY.md`);
-                    return t.done && existsSync(summaryFile);
+                        return true;
+                    return existsSync(join(tDir, `${t.id}-SUMMARY.md`));
                 });
                 if (allTasksDone && hasSliceSummary) {
                     if (_getAdapter()) {

package/dist/resources/extensions/gsd/metrics.js

@@ -611,12 +611,19 @@ function isMetricsLedger(data) {
 function defaultLedger() {
     return { version: 1, projectStartedAt: Date.now(), units: [] };
 }
+export const METRICS_LEDGER_KEEP_UNITS = 1500;
+function compareUnitsByTime(a, b) {
+    return a.finishedAt - b.finishedAt || a.startedAt - b.startedAt;
+}
+function keepNewestUnits(units, keepCount = METRICS_LEDGER_KEEP_UNITS) {
+    return units.length > keepCount ? [...units].sort(compareUnitsByTime).slice(-keepCount) : units;
+}
 /**
  * Prune the metrics ledger to at most `keepCount` most-recent unit entries.
  *
  * Called by the doctor when the ledger exceeds the bloat threshold.
- * Keeps the newest entries (highest index = most recent) and discards
- * the oldest from the head of the array. Preserves `projectStartedAt`.
+ * Keeps the newest entries by unit timestamps and discards the oldest.
+ * Preserves `projectStartedAt`.
  *
  * Updates both the on-disk file and the in-memory ledger if it is loaded,
  * so the current session sees the pruned state immediately.
@@ -628,11 +635,11 @@ export function pruneMetricsLedger(base, keepCount) {
     if (!disk || disk.units.length <= keepCount)
         return 0;
     const removed = disk.units.length - keepCount;
-    disk.units = disk.units.slice(-keepCount);
+    disk.units = keepNewestUnits(disk.units, keepCount);
     saveJsonFile(metricsPath(base), disk);
     // Keep the in-memory ledger in sync if it is loaded for this session.
     if (ledger) {
-        ledger.units = ledger.units.slice(-keepCount);
+        ledger.units = keepNewestUnits(ledger.units, keepCount);
     }
     // Invalidate all scoped ledger cache entries. Prune is rare; clearing the
     // entire map is simpler than tracking which entry belongs to `base`. Without
@@ -786,13 +793,13 @@ function saveLedger(base, data) {
             // Read current on-disk state and merge with worker's in-memory units.
             // Worker units take precedence on conflict (by finishedAt in deduplicateUnits).
             const onDisk = loadJsonFileOrNull(path, isMetricsLedger);
-            if (onDisk && onDisk.units.length > 0) {
-                const merged = deduplicateUnits([...onDisk.units, ...data.units]);
-                saveJsonFile(path, { ...data, units: merged });
-            }
-            else {
-                saveJsonFile(path, data);
-            }
+            const dataUnits = keepNewestUnits(data.units);
+            const merged = onDisk && onDisk.units.length > 0
+                ? deduplicateUnits([...keepNewestUnits(onDisk.units), ...dataUnits])
+                : dataUnits;
+            merged.sort(compareUnitsByTime);
+            data.units = keepNewestUnits(merged);
+            saveJsonFile(path, data);
         }
         finally {
             releaseLock(lockPath);
@@ -805,6 +812,7 @@ function saveLedger(base, data) {
         // to a torn write caused by two writers simultaneously executing the
         // read-merge-write sequence without mutual exclusion.
         logWarning("fs", "saveLedger: lock not acquired — falling back to direct write (no merge)");
+        data.units = keepNewestUnits(data.units);
         saveJsonFile(path, data);
     }
 }

package/dist/resources/extensions/gsd/migrate/layout-detect.js

@@ -0,0 +1,32 @@
+// Project/App: gsd-pi
+// File Purpose: Classify a parsed .planning/ tree into its layout so the
+// round-trip writer can recreate the same structure gsd-core wrote.
+//
+// This extracts the implicit 3-way branch that was buried in transformer.ts
+// transformToGSD (lines 425-467). Priority matches the transformer's if/else
+// chain: legacy-milestone-dir > multi-milestone > flat-phases.
+/**
+ * Determine which .planning/ layout a parsed project uses. Returns null when
+ * no layout signal is present (caller decides: treat as inactive or error).
+ *
+ * Priority (must match transformer.ts transformToGSD):
+ *   1. legacy-milestone-dir — milestones/<id>/ contains <id>-phases/ subdirs
+ *      with phase content. Detected when parsed.milestones has any entry with
+ *      non-empty phases.
+ *   2. multi-milestone — ROADMAP.md parsed into milestone sections.
+ *      Detected when roadmap.milestones.length > 0.
+ *   3. flat-phases — ROADMAP.md parsed into checkbox phase lines only.
+ *      Detected when roadmap.phases.length > 0.
+ */
+export function detectPlanningLayout(parsed) {
+    const hasMilestoneDirectories = parsed.milestones.some((m) => Object.keys(m.phases).length > 0);
+    if (hasMilestoneDirectories)
+        return "legacy-milestone-dir";
+    const isMultiMilestone = parsed.roadmap !== null && parsed.roadmap.milestones.length > 0;
+    if (isMultiMilestone)
+        return "multi-milestone";
+    const hasFlatPhases = parsed.roadmap !== null && parsed.roadmap.phases.length > 0;
+    if (hasFlatPhases)
+        return "flat-phases";
+    return null;
+}

package/dist/resources/extensions/gsd/migrate/planning-writer.js

@@ -0,0 +1,203 @@
+// Project/App: gsd-pi
+// File Purpose: DB → .planning/ projection. Parallel to writer.ts (which
+// emits .gsd/). Produces the .planning/ markdown shape that gsd-core reads.
+//
+// Layout policy (spec §4.4): emits the layout recorded in the compat marker.
+// v1 supports flat-phases; multi-milestone and legacy-milestone-dir are stubbed
+// with a clear error until fixtures exist to validate them.
+import { mkdirSync } from "node:fs";
+import { join, relative } from "node:path";
+import { getAllMilestones, getMilestoneSlices, getSliceTasks } from "../gsd-db.js";
+import { saveFile } from "../files.js";
+import { applyPlanningProjectionWrites, } from "../compat/planning-compat.js";
+function planningRoot(basePath) {
+    return join(basePath, ".planning");
+}
+function slugify(title, fallback) {
+    const slug = title
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 40);
+    return slug || fallback;
+}
+function pad(n, width = 2) {
+    return String(n).padStart(width, "0");
+}
+/**
+ * Format a roadmap for the flat-phases layout. Mirrors the checkbox line
+ * format that parsers.ts parsePhaseEntry recognizes: `- [x] NN — Title`.
+ */
+function formatPlanningRoadmapFlat(entries) {
+    const lines = ["# Roadmap", "", "## Phases", ""];
+    for (const e of entries) {
+        const box = e.done ? "[x]" : "[ ]";
+        lines.push(`- ${box} ${pad(e.number)} — ${e.title}`);
+    }
+    lines.push("");
+    return lines.join("\n");
+}
+/**
+ * Format STATE.md in gsd-core's phase-progress schema. gsd-pi is authoritative
+ * for status; this is a one-way DB→projection (edits to STATE.md are not
+ * re-imported — see spec §7).
+ */
+function formatPlanningState(activeMilestone, totalPhases, completedPhases) {
+    const pct = totalPhases === 0 ? 0 : Math.round((completedPhases / totalPhases) * 100);
+    const ts = new Date().toISOString();
+    return [
+        "---",
+        "gsd_state_version: 1.0",
+        `milestone: ${activeMilestone}`,
+        'milestone_name: "milestone"',
+        "status: active",
+        `stopped_at: Phase 01 — in progress`,
+        `last_updated: "${ts}"`,
+        `last_activity: ${ts.slice(0, 10)}`,
+        "progress:",
+        `  total_phases: ${totalPhases}`,
+        `  completed_phases: ${completedPhases}`,
+        `  total_plans: ${totalPhases}`,
+        `  completed_plans: ${completedPhases}`,
+        `  percent: ${pct}`,
+        "---",
+        "",
+        "# Project State",
+        "",
+        "Current Phase: **01**",
+        "Status: **active**",
+        "",
+    ].join("\n");
+}
+function formatPlanningProject(title) {
+    return `# ${title}\n`;
+}
+/**
+ * Format a phase plan file with the XML-tagged structure parsers.ts
+ * parseOldPlan recognizes: <objective>, <tasks>, <verification>.
+ */
+function formatPlanningPlan(phaseNum, planNum, title, tasks) {
+    const lines = [];
+    lines.push(`# ${pad(phaseNum)}-${pad(planNum)}: ${title}`, "");
+    lines.push("<objective>");
+    lines.push(`${title}.`);
+    lines.push("</objective>");
+    lines.push("");
+    lines.push("<tasks>");
+    for (const t of tasks) {
+        const est = t.estimate ? ` _(${t.estimate})_` : "";
+        lines.push(`- [ ] **${t.id}**: ${t.title}${est}`);
+    }
+    lines.push("</tasks>");
+    lines.push("");
+    lines.push("<verification>");
+    lines.push("All tasks complete and tests pass.");
+    lines.push("</verification>");
+    lines.push("");
+    return lines.join("\n");
+}
+/**
+ * Project DB state to .planning/ in the recorded layout.
+ * Reads DB directly (canonical source). Writes via saveFile (atomic).
+ *
+ * v1: flat-phases only. Each milestone's slices become sequentially-numbered
+ * phase dirs; each task within a slice becomes a plan file (NN-MM-PLAN.md).
+ */
+export async function writePlanningDirectory(basePath, layout) {
+    if (layout !== "flat-phases") {
+        // v1: flat-phases only. multi-milestone and legacy-milestone-dir need
+        // fixtures to validate the reverse-mapping (transformer.ts is non-injective
+        // — three layouts collapse to one .gsd/ shape); stub until then.
+        throw new Error(`writePlanningDirectory: layout "${layout}" not yet supported (v1 supports flat-phases only)`);
+    }
+    const root = planningRoot(basePath);
+    mkdirSync(root, { recursive: true });
+    const paths = [];
+    const projectionWrites = [];
+    const toPlanningRel = (absPath) => relative(root, absPath).replace(/\\/g, "/");
+    const milestones = getAllMilestones();
+    if (milestones.length === 0) {
+        return { paths, layout };
+    }
+    // Flat-phases: each slice becomes one phase. Tasks within become plan files.
+    let phaseNum = 0;
+    const roadmapEntries = [];
+    for (const milestone of milestones) {
+        const slices = getMilestoneSlices(milestone.id);
+        for (const slice of slices) {
+            phaseNum++;
+            const phaseSlug = slugify(slice.title || slice.id, slice.id.toLowerCase());
+            const phaseDirName = `${pad(phaseNum)}-${phaseSlug}`;
+            const phaseDir = join(root, "phases", phaseDirName);
+            mkdirSync(phaseDir, { recursive: true });
+            const tasks = getSliceTasks(milestone.id, slice.id);
+            const isDone = tasks.length > 0 && tasks.every((t) => t.status === "complete");
+            roadmapEntries.push({
+                number: phaseNum,
+                title: slice.title || slice.id,
+                done: isDone,
+            });
+            if (tasks.length === 0) {
+                // Empty phase — write a single placeholder plan so the dir isn't empty.
+                const planPath = join(phaseDir, `${pad(phaseNum)}-01-PLAN.md`);
+                await saveFile(planPath, formatPlanningPlan(phaseNum, 1, slice.title || slice.id, []));
+                paths.push(planPath);
+                projectionWrites.push({
+                    relPath: toPlanningRel(planPath),
+                    entities: [`${milestone.id}/${slice.id}`],
+                });
+            }
+            else {
+                for (let ti = 0; ti < tasks.length; ti++) {
+                    const task = tasks[ti];
+                    const planNum = ti + 1;
+                    const planPath = join(phaseDir, `${pad(phaseNum)}-${pad(planNum)}-PLAN.md`);
+                    await saveFile(planPath, formatPlanningPlan(phaseNum, planNum, task.title || task.id, [
+                        {
+                            id: task.id,
+                            title: task.title || task.id,
+                            estimate: task.estimate || undefined,
+                        },
+                    ]));
+                    paths.push(planPath);
+                    projectionWrites.push({
+                        relPath: toPlanningRel(planPath),
+                        entities: [`${milestone.id}/${slice.id}/${task.id}`],
+                    });
+                }
+            }
+        }
+    }
+    // If no slices produced any phases, write a single empty phase so ROADMAP.md
+    // isn't blank and the layout is still discoverable.
+    if (roadmapEntries.length === 0) {
+        const phaseDirName = `${pad(1)}-milestone`;
+        const phaseDir = join(root, "phases", phaseDirName);
+        mkdirSync(phaseDir, { recursive: true });
+        const planPath = join(phaseDir, `${pad(1)}-01-PLAN.md`);
+        await saveFile(planPath, formatPlanningPlan(1, 1, milestones[0].title || milestones[0].id, []));
+        paths.push(planPath);
+        projectionWrites.push({
+            relPath: toPlanningRel(planPath),
+            entities: [milestones[0].id],
+        });
+        roadmapEntries.push({ number: 1, title: milestones[0].title || milestones[0].id, done: false });
+    }
+    // Root files
+    const milestoneEntities = milestones.map((m) => m.id);
+    const roadmapPath = join(root, "ROADMAP.md");
+    await saveFile(roadmapPath, formatPlanningRoadmapFlat(roadmapEntries));
+    paths.push(roadmapPath);
+    projectionWrites.push({ relPath: toPlanningRel(roadmapPath), entities: milestoneEntities });
+    const completedPhases = roadmapEntries.filter((e) => e.done).length;
+    const statePath = join(root, "STATE.md");
+    await saveFile(statePath, formatPlanningState(milestones[0].id, roadmapEntries.length, completedPhases));
+    paths.push(statePath);
+    projectionWrites.push({ relPath: toPlanningRel(statePath), entities: [milestones[0].id] });
+    const projectPath = join(root, "PROJECT.md");
+    await saveFile(projectPath, formatPlanningProject(milestones[0].title || milestones[0].id));
+    paths.push(projectPath);
+    projectionWrites.push({ relPath: toPlanningRel(projectPath), entities: [milestones[0].id] });
+    applyPlanningProjectionWrites(basePath, projectionWrites);
+    return { paths, layout };
+}