@specship/specship 0.11.0

package/dist/server/routes/projects.js

@@ -0,0 +1,197 @@
+/**
+ * GET /api/projects        — enumerate every project visible to Claude Code
+ *                            (every dir under ~/.claude/projects/).
+ * GET /api/projects/events  — SSE stream that pushes a refresh whenever the
+ *                            watcher sees the project list change. Used by
+ *                            the desktop UI's Project picker so newly opened
+ *                            projects appear without a refresh.
+ *
+ * Why this lives in its own route file: the rest of the analytics endpoints
+ * already read ~/.claude/projects/ via the ingest pipeline. This route adds
+ * a *navigation* primitive on top of that data — "what projects does the
+ * user have at all?" — without coupling to the specship instance.
+ */
+import { EventEmitter } from 'node:events';
+import { promises as fs, watch } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { decodeProjectSlug } from '../ingest/ingestor.js';
+const projectsBus = new EventEmitter();
+projectsBus.setMaxListeners(0); // many SSE subscribers + internal
+export async function enumerate(claudeRoot) {
+    let entries;
+    try {
+        entries = await fs.readdir(claudeRoot, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const ent of entries) {
+        if (!ent.isDirectory())
+            continue;
+        const slug = ent.name;
+        const decoded = decodeProjectSlug(slug);
+        const projDir = path.join(claudeRoot, slug);
+        let sessionCount = 0;
+        let lastModifiedMs = 0;
+        try {
+            const inside = await fs.readdir(projDir, { withFileTypes: true });
+            for (const f of inside) {
+                if (f.isFile() && f.name.toLowerCase().endsWith('.jsonl')) {
+                    sessionCount++;
+                    try {
+                        const stat = await fs.stat(path.join(projDir, f.name));
+                        if (stat.mtimeMs > lastModifiedMs)
+                            lastModifiedMs = stat.mtimeMs;
+                    }
+                    catch { /* ignore */ }
+                }
+            }
+        }
+        catch { /* project dir disappeared mid-scan — skip its files */ }
+        let exists = false;
+        let initialized = false;
+        try {
+            const st = await fs.stat(decoded);
+            exists = st.isDirectory();
+            if (exists) {
+                try {
+                    const cg = await fs.stat(path.join(decoded, '.specship'));
+                    initialized = cg.isDirectory();
+                }
+                catch { /* not initialized — OK */ }
+            }
+        }
+        catch { /* path missing — OK, still surface it so UI can flag it */ }
+        out.push({ slug, path: decoded, exists, initialized, sessionCount, lastModifiedMs });
+    }
+    // Recent activity first; ties broken by path.
+    out.sort((a, b) => {
+        if (b.lastModifiedMs !== a.lastModifiedMs)
+            return b.lastModifiedMs - a.lastModifiedMs;
+        return a.path.localeCompare(b.path);
+    });
+    return out;
+}
+// --- Watcher (singleton across the process) ---------------------------------
+let watcher = null;
+let lastSlugs = new Set();
+let debounceHandle = null;
+let watchedRoot = null;
+function startWatcher(claudeRoot, verbose) {
+    if (watcher)
+        return;
+    watchedRoot = claudeRoot;
+    try {
+        watcher = watch(claudeRoot, { persistent: true }, () => {
+            scheduleRescan(claudeRoot);
+        });
+        if (verbose)
+            console.error(`[projects] watching ${claudeRoot}`);
+        // Warm the cache so the first SSE snapshot has accurate state and the
+        // first change diff is meaningful.
+        void enumerate(claudeRoot).then((list) => {
+            lastSlugs = new Set(list.map((p) => p.slug));
+        });
+    }
+    catch (err) {
+        if (verbose)
+            console.error(`[projects] watch failed for ${claudeRoot}:`, err instanceof Error ? err.message : String(err));
+        // Directory may not exist yet — that's OK, every /api/projects GET
+        // returns [] until it does. We don't retry here; if the watcher is
+        // critical the user can restart the server after creating it.
+    }
+}
+function scheduleRescan(claudeRoot) {
+    if (debounceHandle)
+        clearTimeout(debounceHandle);
+    debounceHandle = setTimeout(async () => {
+        debounceHandle = null;
+        const list = await enumerate(claudeRoot);
+        const newSlugs = new Set(list.map((p) => p.slug));
+        const added = list.filter((p) => !lastSlugs.has(p.slug));
+        const removed = [...lastSlugs].filter((s) => !newSlugs.has(s));
+        lastSlugs = newSlugs;
+        if (added.length || removed.length) {
+            projectsBus.emit('change', { added, removed, list });
+        }
+        // Refresh is always emitted so subscribers can pick up lastModified /
+        // sessionCount drift even without slug-level changes.
+        projectsBus.emit('refresh', { list });
+    }, 350);
+}
+function stopWatcher() {
+    if (watcher) {
+        try {
+            watcher.close();
+        }
+        catch { /* ignore */ }
+        watcher = null;
+    }
+    if (debounceHandle) {
+        clearTimeout(debounceHandle);
+        debounceHandle = null;
+    }
+    watchedRoot = null;
+}
+// --- Route registration -----------------------------------------------------
+export async function registerProjectsRoutes(app) {
+    const claudeRoot = path.join(os.homedir(), '.claude', 'projects');
+    startWatcher(claudeRoot, false);
+    app.addHook('onClose', async () => { stopWatcher(); });
+    app.get('/api/projects', async () => {
+        return { claudeRoot, projects: await enumerate(claudeRoot) };
+    });
+    app.get('/api/projects/events', async (req, reply) => {
+        reply.raw.setHeader('Content-Type', 'text/event-stream');
+        reply.raw.setHeader('Cache-Control', 'no-cache');
+        reply.raw.setHeader('Connection', 'keep-alive');
+        reply.raw.flushHeaders();
+        let closed = false;
+        const onClose = () => {
+            closed = true;
+            projectsBus.off('change', onChange);
+            projectsBus.off('refresh', onRefresh);
+            clearInterval(hb);
+        };
+        req.raw.on('close', onClose);
+        const writeEvent = (event, data) => {
+            if (closed)
+                return;
+            try {
+                reply.raw.write(`event: ${event}\n`);
+                reply.raw.write(`data: ${JSON.stringify(data)}\n\n`);
+            }
+            catch { /* socket gone */
+                closed = true;
+            }
+        };
+        const initial = await enumerate(claudeRoot);
+        lastSlugs = new Set(initial.map((p) => p.slug));
+        writeEvent('snapshot', { claudeRoot, projects: initial });
+        const onChange = (payload) => {
+            writeEvent('change', payload);
+        };
+        const onRefresh = (payload) => {
+            writeEvent('refresh', payload);
+        };
+        projectsBus.on('change', onChange);
+        projectsBus.on('refresh', onRefresh);
+        // Heartbeat keeps proxies / NATs from dropping the idle connection.
+        const hb = setInterval(() => {
+            if (closed) {
+                clearInterval(hb);
+                return;
+            }
+            try {
+                reply.raw.write(`: ping\n\n`);
+            }
+            catch {
+                onClose();
+            }
+        }, 30000);
+    });
+}
+/** Test seam — re-export so __tests__ can stop the watcher between cases. */
+export const _testing = { stopWatcher, watchedRoot: () => watchedRoot };

package/dist/server/routes/reflect.js

@@ -0,0 +1,93 @@
+/**
+ * Reflection engine HTTP surface (REFLECT-DOC).
+ *
+ *   GET  /api/reflect                 — list persisted proposals (?state=open|applied|undone|dismissed)
+ *   POST /api/reflect/analyze         — run a reflection pass, persist, return open proposals
+ *   GET  /api/reflect/:hash/preview   — non-mutating diff of the change a proposal would make
+ *   POST /api/reflect/:hash/apply     — preview-confirmed write (idempotent + reversible)
+ *   POST /api/reflect/:hash/undo      — reverse a previously applied proposal
+ *   POST /api/reflect/:hash/dismiss   — hide a proposal from future sweeps
+ *
+ * Like the tips engine, reflection reads the cross-project claude_* tables that
+ * live in the boot-time "primary" project's DB, so every handler resolves the
+ * primary instance and drives it through its `reflect*` methods. These are
+ * instance methods on the dynamically-loaded SpecShip — NOT a runtime package
+ * import — so the route never trips the stale-build hazard.
+ */
+export async function registerReflectRoutes(app) {
+    function requirePrimary(reply) {
+        if (!app.primaryCg) {
+            reply.code(409).send({ error: 'reflection unavailable: no primary project configured', code: 'no_primary' });
+            return null;
+        }
+        return app.primaryCg;
+    }
+    // List persisted proposals, optionally filtered by state.
+    app.get('/api/reflect', async (req, reply) => {
+        const cg = requirePrimary(reply);
+        if (!cg)
+            return;
+        const state = req.query.state;
+        return { proposals: cg.reflectList(state) };
+    });
+    // Run a reflection pass: mine + persist + return the current open proposals.
+    app.post('/api/reflect/analyze', async (_req, reply) => {
+        const cg = requirePrimary(reply);
+        if (!cg)
+            return;
+        const result = cg.reflectAnalyze();
+        return { open: result.open, empty: result.empty };
+    });
+    // Non-mutating preview of a proposal's change (REQ-REFLECT-003).
+    app.get('/api/reflect/:hash/preview', async (req, reply) => {
+        const cg = requirePrimary(reply);
+        if (!cg)
+            return;
+        const preview = cg.reflectPreview(req.params.hash);
+        if (!preview) {
+            reply.code(404).send({ error: 'proposal not found', code: 'not_found' });
+            return;
+        }
+        return preview;
+    });
+    // Apply a proposal — preview-confirmed write (REQ-REFLECT-004).
+    app.post('/api/reflect/:hash/apply', async (req, reply) => {
+        const cg = requirePrimary(reply);
+        if (!cg)
+            return;
+        const outcome = cg.reflectApply(req.params.hash);
+        if (outcome === null) {
+            reply.code(404).send({ error: 'proposal not found', code: 'not_found' });
+            return;
+        }
+        if (outcome === 'conflict') {
+            reply.code(409).send({ error: 'a non-SpecShip file already occupies the target path', code: 'conflict' });
+            return;
+        }
+        return { outcome, proposal: cg.reflectGet(req.params.hash) };
+    });
+    // Undo a previously applied proposal (REQ-REFLECT-004.A3).
+    app.post('/api/reflect/:hash/undo', async (req, reply) => {
+        const cg = requirePrimary(reply);
+        if (!cg)
+            return;
+        const outcome = cg.reflectUndo(req.params.hash);
+        if (outcome === null) {
+            reply.code(404).send({ error: 'proposal not found', code: 'not_found' });
+            return;
+        }
+        return { outcome, proposal: cg.reflectGet(req.params.hash) };
+    });
+    // Dismiss a proposal so it does not resurface on later sweeps (REQ-REFLECT-007.A2).
+    app.post('/api/reflect/:hash/dismiss', async (req, reply) => {
+        const cg = requirePrimary(reply);
+        if (!cg)
+            return;
+        const ok = cg.reflectDismiss(req.params.hash);
+        if (!ok) {
+            reply.code(404).send({ error: 'proposal not found', code: 'not_found' });
+            return;
+        }
+        return { ok: true, proposal: cg.reflectGet(req.params.hash) };
+    });
+}

package/dist/server/routes/spec.js

@@ -0,0 +1,373 @@
+/**
+ * Spec layer routes — list / fetch / link assert / link verify / drift queue.
+ * Plus the v0.2 write endpoints: PUT /api/spec/:id and POST /api/specs,
+ * which let the dashboard's Monaco editor save spec edits back to disk.
+ *
+ * Every route is project-scoped via `?project=<slug>` (falls back to the
+ * boot-time primary). Returns 409 / `no_project` when neither is selectable.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+/**
+ * Resolve a project-relative path to an absolute path under the project
+ * root, refusing anything that escapes the root (path-traversal guard).
+ * Returns null when the resolved path is outside the project — caller
+ * surfaces 400 in that case.
+ */
+function safeProjectPath(projectRoot, relPath) {
+    // Strip leading slashes so absolute paths in user input don't blow past
+    // path.resolve's "drop earlier components" behavior.
+    const cleaned = relPath.replace(/^[/\\]+/, '');
+    const abs = path.resolve(projectRoot, cleaned);
+    const rootResolved = path.resolve(projectRoot);
+    const rel = path.relative(rootResolved, abs);
+    if (rel.startsWith('..') || path.isAbsolute(rel))
+        return null;
+    return abs;
+}
+/**
+ * Extract the `brief:` value from the leading YAML frontmatter block of a
+ * spec source file (between the first pair of `---` fences). Returns null
+ * when there is no frontmatter, no `brief:` key, or the value is empty.
+ *
+ * Deliberately dependency-free: a simple line scan that mirrors the style
+ * used by `MarkdownSpecExtractor.parseFrontmatter`. Exported so tests can
+ * exercise the parsing logic in isolation.
+ */
+export function parseBriefField(source) {
+    const lines = source.split(/\r?\n/);
+    if (lines.length === 0 || (lines[0] ?? '').trim() !== '---')
+        return null;
+    // Find the closing `---` fence.
+    let closingIdx = -1;
+    for (let i = 1; i < lines.length; i++) {
+        if ((lines[i] ?? '').trim() === '---') {
+            closingIdx = i;
+            break;
+        }
+    }
+    if (closingIdx === -1)
+        return null;
+    // Scan frontmatter body for `brief: <value>`.
+    for (let i = 1; i < closingIdx; i++) {
+        const line = (lines[i] ?? '').trim();
+        if (!line.startsWith('brief:'))
+            continue;
+        let value = line.slice('brief:'.length).trim();
+        if (!value)
+            return null;
+        // Strip surrounding quotes.
+        if ((value.startsWith('"') && value.endsWith('"')) ||
+            (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1).trim();
+        }
+        else {
+            // Strip a trailing ` # comment` from an UNQUOTED value only. Requires
+            // whitespace before the `#` so a `#fragment` inside the path — or a `#`
+            // inside a quoted value (handled above) — isn't mangled.
+            const hashIdx = value.search(/\s#/);
+            if (hashIdx !== -1)
+                value = value.slice(0, hashIdx).trim();
+        }
+        return value || null;
+    }
+    return null;
+}
+/**
+ * Atomic file write: tmp + rename. Mirrors `atomicWriteFileSync` in
+ * `src/installer/targets/shared.ts` — kept local here to avoid the
+ * @selvakumaresra/specship deep-import dance for a 10-line helper.
+ */
+function atomicWriteFile(targetPath, content) {
+    const dir = path.dirname(targetPath);
+    fs.mkdirSync(dir, { recursive: true });
+    const tmp = `${targetPath}.tmp.${process.pid}.${Date.now()}`;
+    fs.writeFileSync(tmp, content, 'utf-8');
+    fs.renameSync(tmp, targetPath);
+}
+async function resolveCg(app, req, reply) {
+    const cg = await app.activeCg(req);
+    if (!cg) {
+        reply.code(409).send({ error: 'no project selected', code: 'no_project' });
+        return null;
+    }
+    return cg;
+}
+export async function registerSpecRoutes(app) {
+    app.get('/api/specs', async (req, reply) => {
+        const cg = await resolveCg(app, req, reply);
+        if (!cg)
+            return;
+        const docs = cg.getSpecQueries().getAllSpecs();
+        return { specs: docs };
+    });
+    // Spec lifecycle funnel: idea → spec → implemented (REQ-FUNNEL-006). Computed
+    // on the dynamically-loaded SpecShip instance — no runtime import of the
+    // package from the server.
+    app.get('/api/spec/funnel', async (req, reply) => {
+        const cg = await resolveCg(app, req, reply);
+        if (!cg)
+            return;
+        return cg.getSpecFunnel();
+    });
+    app.get('/api/spec/:id', async (req, reply) => {
+        const cg = await resolveCg(app, req, reply);
+        if (!cg)
+            return;
+        const sq = cg.getSpecQueries();
+        const spec = sq.getSpecById(req.params.id);
+        if (!spec)
+            return reply.code(404).send({ error: 'spec not found' });
+        const parent = spec.parentId ? sq.getSpecById(spec.parentId) : null;
+        const children = sq.getSpecsByParent(spec.id);
+        const siblings = parent ? sq.getSpecsByParent(parent.id).filter((s) => s.id !== spec.id) : [];
+        const links = sq.getLinksBySpec(spec.id);
+        // Per-child links so the detail page can show each acceptance criterion's
+        // met/unmet state and an "N / M met" rollup (DASH-SPECDETAIL-DOC, REQ-004).
+        const childLinks = {};
+        for (const c of children)
+            childLinks[c.id] = sq.getLinksBySpec(c.id);
+        // Read the raw source file so the dashboard's Monaco editor can edit
+        // the whole document, not just the DB-parsed body fragment for this
+        // requirement. The `spec.body` field stores per-section content; the
+        // editor needs the file.
+        let source = null;
+        try {
+            const projectRoot = cg.getProjectRoot();
+            const absPath = safeProjectPath(projectRoot, spec.sourcePath);
+            if (absPath && fs.existsSync(absPath)) {
+                source = fs.readFileSync(absPath, 'utf-8');
+            }
+        }
+        catch {
+            // File missing or unreadable — return null so the UI can show a
+            // "source not available" hint without failing the whole fetch.
+        }
+        return { spec, parent, siblings, children, links, childLinks, source };
+    });
+    /**
+     * GET /api/spec/:id/brief — return the brainstorm brief for a spec.
+     *
+     * Reads the spec's source file, parses the `brief:` frontmatter key, and
+     * returns the brief markdown from the path it names. The `brief:` value is
+     * resolved relative to the spec file's own directory (so a nested spec at
+     * `specs/area/foo.md` with `brief: foo/brief.md` resolves to
+     * `specs/area/foo/brief.md`). safeProjectPath guards against traversal.
+     */
+    app.get('/api/spec/:id/brief', async (req, reply) => {
+        const cg = await resolveCg(app, req, reply);
+        if (!cg)
+            return;
+        const spec = cg.getSpecQueries().getSpecById(req.params.id);
+        if (!spec)
+            return reply.code(404).send({ error: 'spec not found' });
+        const projectRoot = cg.getProjectRoot();
+        const specAbs = safeProjectPath(projectRoot, spec.sourcePath);
+        if (!specAbs)
+            return reply.code(404).send({ error: 'no brief' });
+        // TOCTOU: read directly under try/catch rather than existsSync-then-read,
+        // so a file deleted between the check and the read degrades to 404 (the
+        // sibling GET /api/spec/:id read is guarded the same way) instead of 500.
+        let specSource;
+        try {
+            specSource = fs.readFileSync(specAbs, 'utf-8');
+        }
+        catch {
+            return reply.code(404).send({ error: 'no brief' });
+        }
+        const briefRel = parseBriefField(specSource);
+        if (!briefRel)
+            return reply.code(404).send({ error: 'no brief' });
+        // CONVENTION: `brief:` is relative to the SPEC FILE's own directory (resolves
+        // whether the spec is flat at specs/<id>.md or nested at specs/<area>/<id>.md).
+        // safeProjectPath GUARDS against traversal outside the project root.
+        const briefAbs = safeProjectPath(projectRoot, path.join(path.dirname(spec.sourcePath), briefRel));
+        if (!briefAbs)
+            return reply.code(404).send({ error: 'no brief' });
+        try {
+            return { path: briefRel, markdown: fs.readFileSync(briefAbs, 'utf-8') };
+        }
+        catch {
+            return reply.code(404).send({ error: 'no brief' });
+        }
+    });
+    app.get('/api/drift', async (req, reply) => {
+        const cg = await resolveCg(app, req, reply);
+        if (!cg)
+            return;
+        const sq = cg.getSpecQueries();
+        const validStates = [
+            'drafted', 'implementing', 'implemented', 'verified',
+            'drifted', 'broken', 'orphaned',
+        ];
+        const requested = (req.query.state ?? 'drifted,broken,orphaned')
+            .split(',')
+            .map((s) => s.trim())
+            .filter((s) => validStates.includes(s));
+        const limit = Math.min(parseInt(req.query.limit ?? '100', 10) || 100, 500);
+        const links = sq.getLinksByState(requested).slice(0, limit);
+        const out = links.map((l) => {
+            const spec = sq.getSpecById(l.specId);
+            return { ...l, specTitle: spec?.title ?? null };
+        });
+        return { links: out };
+    });
+    app.post('/api/spec/link-assert', async (req, reply) => {
+        const cg = await resolveCg(app, req, reply);
+        if (!cg)
+            return;
+        const body = req.body;
+        if (!body?.spec_id || !body.target_file_path || !body.target_qualified_name) {
+            return reply.code(400).send({ error: 'spec_id, target_file_path, target_qualified_name required' });
+        }
+        const sq = cg.getSpecQueries();
+        const spec = sq.getSpecById(body.spec_id);
+        if (!spec)
+            return reply.code(404).send({ error: 'spec not found' });
+        const now = Date.now();
+        const id = sq.upsertSpecLink({
+            specId: body.spec_id,
+            targetFilePath: body.target_file_path,
+            targetQualifiedName: body.target_qualified_name,
+            targetNodeKind: body.target_node_kind ?? 'function',
+            resolvedNodeId: undefined,
+            kind: body.kind ?? 'implements',
+            state: 'implemented',
+            driftAxis: null,
+            specHashAtLink: spec.contentHash,
+            nodeSigAtLink: undefined,
+            provenance: 'agent-asserted',
+            confidence: 1.0,
+            createdAt: now,
+            updatedAt: now,
+        });
+        cg.getSpecLinkResolver().resolveLinksForFiles([body.target_file_path]);
+        return { id, ok: true };
+    });
+    app.post('/api/spec/link-verify', async (req, reply) => {
+        const cg = await resolveCg(app, req, reply);
+        if (!cg)
+            return;
+        const body = req.body;
+        if (typeof body?.link_id !== 'number' || (body.result !== 'pass' && body.result !== 'fail')) {
+            return reply.code(400).send({ error: 'link_id (number) and result ("pass"|"fail") required' });
+        }
+        const sq = cg.getSpecQueries();
+        const link = sq.getLinkById(body.link_id);
+        if (!link)
+            return reply.code(404).send({ error: 'link not found' });
+        sq.updateSpecLinkState(body.link_id, body.result === 'pass' ? 'verified' : 'broken', null);
+        return { ok: true, state: body.result === 'pass' ? 'verified' : 'broken' };
+    });
+    /**
+     * PUT /api/spec/:id — overwrite the spec file backing this spec.
+     *
+     * Resolves the source file path from the existing spec row, validates it's
+     * under the project root (path-traversal guard), atomically writes the new
+     * content, then re-syncs the project so the indexer picks up the change.
+     * Returns the freshly re-parsed spec node. Used by the dashboard's Monaco
+     * editor.
+     */
+    app.put('/api/spec/:id', async (req, reply) => {
+        const cg = await resolveCg(app, req, reply);
+        if (!cg)
+            return;
+        const sq = cg.getSpecQueries();
+        const spec = sq.getSpecById(req.params.id);
+        if (!spec)
+            return reply.code(404).send({ error: 'spec not found' });
+        const body = req.body;
+        if (typeof body?.content !== 'string') {
+            return reply.code(400).send({ error: 'content (string) required' });
+        }
+        const projectRoot = cg.getProjectRoot();
+        const absPath = safeProjectPath(projectRoot, spec.sourcePath);
+        if (!absPath) {
+            return reply.code(400).send({
+                error: 'spec.sourcePath resolves outside project root',
+                code: 'path_traversal',
+            });
+        }
+        try {
+            atomicWriteFile(absPath, body.content);
+        }
+        catch (e) {
+            return reply.code(500).send({
+                error: 'failed to write spec file',
+                detail: e instanceof Error ? e.message : String(e),
+            });
+        }
+        // Re-index so the freshly-edited spec replaces the old graph nodes.
+        // The Markdown extractor will rebuild the doc + REQs + acceptance
+        // children, and the link resolver re-runs against the new content
+        // hash so drift states transition correctly.
+        try {
+            await cg.sync();
+        }
+        catch (e) {
+            // Sync errors don't roll back the write — the file is on disk and
+            // the next sync will pick it up. Surface so the UI can show a
+            // "saved but not yet indexed" hint.
+            const updated = sq.getSpecById(req.params.id);
+            return {
+                ok: true,
+                spec: updated ?? spec,
+                syncError: e instanceof Error ? e.message : String(e),
+            };
+        }
+        const updated = sq.getSpecById(req.params.id);
+        return { ok: true, spec: updated ?? spec };
+    });
+    /**
+     * POST /api/specs — create a new spec file under the project's specs/
+     * directory.
+     *
+     * `filePath` is project-relative (e.g. `specs/billing.md`). 409 if the
+     * file already exists. Used by the dashboard's Draft-with-Claude flow
+     * for the optional "finalize via dashboard" path.
+     */
+    app.post('/api/specs', async (req, reply) => {
+        const cg = await resolveCg(app, req, reply);
+        if (!cg)
+            return;
+        const body = req.body;
+        if (typeof body?.filePath !== 'string' || typeof body?.content !== 'string') {
+            return reply.code(400).send({ error: 'filePath and content (strings) required' });
+        }
+        const projectRoot = cg.getProjectRoot();
+        const absPath = safeProjectPath(projectRoot, body.filePath);
+        if (!absPath) {
+            return reply.code(400).send({
+                error: 'filePath resolves outside project root',
+                code: 'path_traversal',
+            });
+        }
+        if (fs.existsSync(absPath)) {
+            return reply.code(409).send({
+                error: 'file already exists',
+                code: 'file_exists',
+                filePath: body.filePath,
+            });
+        }
+        try {
+            atomicWriteFile(absPath, body.content);
+        }
+        catch (e) {
+            return reply.code(500).send({
+                error: 'failed to write spec file',
+                detail: e instanceof Error ? e.message : String(e),
+            });
+        }
+        try {
+            await cg.sync();
+        }
+        catch (e) {
+            return {
+                ok: true,
+                filePath: body.filePath,
+                syncError: e instanceof Error ? e.message : String(e),
+            };
+        }
+        return { ok: true, filePath: body.filePath };
+    });
+}