@straiffi/archon 1.2.33 → 1.3.0

package/dist/server/index.js

@@ -9,8 +9,10 @@ import cors from 'cors';
 import { adjectives, animals, uniqueNamesGenerator } from 'unique-names-generator';
 import db from './db.js';
 import { deleteChatSession, getChatSession, listChatSessions, updateChatSessionMode } from './lib/chats.js';
-import { createChatAttachment, deleteChatAttachment, getChatAttachmentById, getChatAttachmentForSession, getChatAttachmentLinkedMessageId, MAX_CHAT_ATTACHMENTS_PER_TURN, MAX_CHAT_ATTACHMENT_SIZE_BYTES, readChatAttachmentContent, validateImageAttachment, } from './lib/attachments.js';
+import { deleteSpecSession, getCreatedTicketIdsForSnapshot, getSpecSession, getSpecSnapshot, listSpecSessions } from './lib/specs.js';
+import { createChatAttachment, createSpecAttachment, deleteChatAttachment, deleteSpecSessionAttachment, getChatAttachmentById, getChatAttachmentForSession, getChatAttachmentLinkedMessageId, getSpecAttachmentForSession, getSpecAttachmentLinkedMessageId, MAX_CHAT_ATTACHMENTS_PER_TURN, MAX_CHAT_ATTACHMENT_SIZE_BYTES, MAX_SPEC_ATTACHMENTS_PER_TURN, MAX_SPEC_ATTACHMENT_SIZE_BYTES, readChatAttachmentContent, readSpecAttachmentContent, validateImageAttachment, } from './lib/attachments.js';
 import { createProjectChatSession, resolveChatMode, resolveChatTool, stopProjectChatSessionResponse, submitProjectChatSessionMessage, } from './lib/chatOperations.js';
+import { createProjectSpecSession, deleteProjectSpecSession, stopProjectSpecSessionResponse, submitProjectSpecSessionMessage, } from './lib/specOperations.js';
 import { resolveChatSessionTarget } from './lib/chatTargets.js';
 import { createChatMessage, getChatMessage, updateChatMessageContent } from './lib/chatMessages.js';
 import { attachChatTicketProposalsToMessageContent } from './lib/chatTicketProposals.js';
@@ -23,7 +25,7 @@ import { browseRepoPath } from './lib/directoryPicker.js';
 import { resolveDesktopServerHost } from './lib/desktopServerHost.js';
 import { emitMobileRealtime, getMobileAccessStatus, regenerateMobilePairingChallenge, revokeMobileSession, setMobileAccessStatusChangeListener, startMobileAccess, stopMobileAccess, } from './lib/mobileAccess.js';
 import { validateDesktopMobileAccessRequest } from './lib/mobileAccessSecurity.js';
-import { refreshChatSessionUsageSnapshot, stopAllBuildAgents } from './lib/agent.js';
+import { refreshChatSessionUsageSnapshot, refreshSpecSessionUsageSnapshot, stopAllBuildAgents } from './lib/agent.js';
 import { runLightweightPrompt } from './lib/lightweightPrompt.js';
 import { startBuildChain, stopBuildChain } from './lib/buildChains.js';
 import { enqueueBundledBuild, getDependencyOrderedBundleTicketIds, removeTicketFromBuildSequence, stopAllActiveBuildSequences, } from './lib/buildSequences.js';
@@ -58,19 +60,17 @@ import { getActiveBundleStageChangeHead, undoTicketStage } from './lib/ticketUnd
 import { closeAllTerminalSessions, createProjectTerminalSession, createTerminalSessionForWorkspace, destroyTerminalSessionById, registerTerminalSocketHandlers, } from './lib/terminal.js';
 import { countBundleTickets, createTicketRecord, createBundle, deleteBundle, ensureProjectRootBundle, autoParkTicketIfStale, autoParkSettledBundleTicket, isBundleSettledForAutoPark, clearAutoParkDismissalIfNeeded, assignTicketDoneOrder, assignTicketLaneOrder, getBundle, getBundleByName, getBundleByBranch, getBundleRepresentativeTicketContext, isProjectRootBundle, getTicket, isBundledTicket, listTicketsInRunContext, listBundles, listBoardTicketEnrichment, listTickets, resolveTicketBranch, resolveTicketTool, } from './lib/tickets.js';
 import { createTicketMessage, upsertTicketDescriptionMessage } from './lib/ticketMessages.js';
+import { HttpError } from './lib/httpError.js';
+import { parseIncomingExternalSource } from './lib/externalSource.js';
+import { materializeTicketsWithDependencies } from './lib/ticketBatch.js';
+import { IMPLEMENTATION_READY_DESCRIPTION_SECTION_HEADINGS } from './lib/ticketDescriptionContract.js';
+import { buildSpecImplementationDraft } from './lib/specDraft.js';
+import { exportSpecToDocs, checkSpecExportCollision } from './lib/specExport.js';
 import { createTicketDependency, deleteTicketDependenciesForTicket, deleteTicketDependency, getTicketDependency, isTicketRunSetupReady, listTicketDependencies, validateCreateTicketDependency, } from './lib/ticketDependencies.js';
 import { startBuild } from './workers/build.js';
 import { startFollowUp } from './workers/followUp.js';
-import { expandPlanningTicketOutline, generatePlanningTicketOutline, generatePlanText, IMPLEMENTATION_READY_DESCRIPTION_SECTION_HEADINGS, prepareLinkedPlanningResearch, startPlan, } from './workers/plan.js';
+import { expandPlanningTicketOutline, generatePlanningTicketOutline, generatePlanText, prepareLinkedPlanningResearch, startPlan, } from './workers/plan.js';
 import { startReview } from './workers/review.js';
-class HttpError extends Error {
-    status;
-    constructor(status, message) {
-        super(message);
-        this.name = 'HttpError';
-        this.status = status;
-    }
-}
 const getErrorMessage = (error) => {
     return error instanceof Error ? error.message : String(error);
 };
@@ -296,6 +296,24 @@ const getChatAttachmentUploadErrorMessage = (error) => {
     }
     return 'Unable to upload the selected images right now.';
 };
+const specAttachmentUpload = multer({
+    storage: multer.memoryStorage(),
+    limits: {
+        files: MAX_SPEC_ATTACHMENTS_PER_TURN,
+        fileSize: MAX_SPEC_ATTACHMENT_SIZE_BYTES,
+    },
+});
+const getSpecAttachmentUploadErrorMessage = (error) => {
+    if (error instanceof multer.MulterError) {
+        if (error.code === 'LIMIT_FILE_COUNT') {
+            return 'You can attach up to 4 images per turn.';
+        }
+        if (error.code === 'LIMIT_FILE_SIZE') {
+            return 'Images must be 10 MB or smaller.';
+        }
+    }
+    return 'Unable to upload the selected images right now.';
+};
 const normalizeGeneratedCommitMessage = (value) => {
     const firstLine = value
         .replace(/\r/g, '\n')
@@ -396,33 +414,6 @@ const listBundleReviewTicketContextsStatement = db.prepare(`
     AND tickets.worktree_bundle_id = ?
   ORDER BY tickets.updated_at DESC, tickets.id DESC
 `);
-const parseIncomingExternalSource = (value) => {
-    if (!value || typeof value !== 'object' || Array.isArray(value)) {
-        return null;
-    }
-    const payload = value;
-    const provider = asTrimmedString(payload.provider);
-    const externalId = asTrimmedString(payload.external_id);
-    const externalKey = asTrimmedString(payload.external_key);
-    const externalUrl = asTrimmedString(payload.external_url);
-    if (provider === '' && externalId === '' && externalKey === '' && externalUrl === '') {
-        return null;
-    }
-    if ((provider !== 'jira' && provider !== 'github') || !externalId || !externalKey) {
-        throw new HttpError(400, 'external_source must contain a supported provider, external_id, and external_key');
-    }
-    const metadata = payload.metadata;
-    if (metadata != null && (typeof metadata !== 'object' || Array.isArray(metadata))) {
-        throw new HttpError(400, 'external_source metadata must be an object when provided');
-    }
-    return {
-        provider: provider,
-        external_id: externalId,
-        external_key: externalKey,
-        external_url: externalUrl || null,
-        metadata: metadata ?? null,
-    };
-};
 const slugify = (text) => {
     const slug = String(text ?? '')
         .replace(/[^a-zA-Z0-9\s-]/g, '')
@@ -574,6 +565,13 @@ const getProjectChatSession = (projectId, chatSessionId) => {
     }
     return chatSession;
 };
+const getProjectSpecSession = (projectId, specSessionId) => {
+    const specSession = getSpecSession(specSessionId, { includeMessages: true });
+    if (!specSession || specSession.project_id !== projectId) {
+        return null;
+    }
+    return specSession;
+};
 const resolveTicketDiffWorkspace = (ticket) => {
     const project = getEffectiveProject(ticket);
     if (!project) {
@@ -1910,35 +1908,25 @@ const validateExpandedPlanningAgentDraft = (outline, draft) => {
     return draft;
 };
 const createPlanningAgentTickets = db.transaction(({ draft, initiativePrompt, projectId, model, variant, skills, tool, worktreeBundleId, }) => {
-    const createdTickets = [];
-    const createdDependencies = [];
-    const ticketIdsByKey = new Map();
-    const createdTicketDefinitions = new Map();
-    for (const ticket of draft.tickets) {
-        const planningContext = {
-            source_kind: 'multi',
-            initiative_prompt: initiativePrompt,
-            related_ticket_ids: [],
-            open_questions: ticket.open_questions,
-        };
-        const createdTicket = createTicketRecord({
-            title: ticket.title,
-            description: ticket.description,
+    const { createdTickets, createdDependencies, ticketIdsByKey } = materializeTicketsWithDependencies({
+        options: {
+            projectId,
             model,
             variant,
             skills,
             tool: tool ?? 'opencode',
-            agentStatus: 'done',
-            projectId,
             worktreeBundleId,
-            planningContext,
-        });
-        if (!createdTicket) {
-            throw new HttpError(500, 'Unable to create the generated tickets.');
+            agentStatus: 'done',
+        },
+        tickets: draft.tickets,
+        dependencies: draft.dependencies,
+    });
+    const createdTicketDefinitions = new Map();
+    for (const ticket of draft.tickets) {
+        const createdId = ticketIdsByKey.get(ticket.key);
+        if (createdId) {
+            createdTicketDefinitions.set(createdId, ticket);
         }
-        createdTickets.push(createdTicket);
-        ticketIdsByKey.set(ticket.key, createdTicket.id);
-        createdTicketDefinitions.set(createdTicket.id, ticket);
     }
     const createdTicketIds = createdTickets.map(ticket => ticket.id);
     for (const createdTicket of createdTickets) {
@@ -1961,72 +1949,28 @@ const createPlanningAgentTickets = db.transaction(({ draft, initiativePrompt, pr
             });
         }
     }
-    for (const dependency of draft.dependencies) {
-        const blockerTicketId = ticketIdsByKey.get(dependency.blocker_key);
-        const dependentTicketId = ticketIdsByKey.get(dependency.dependent_key);
-        if (!blockerTicketId || !dependentTicketId) {
-            throw new HttpError(500, 'Planning agent returned a dependency for an unknown generated ticket.');
-        }
-        const validation = validateCreateTicketDependency({
-            blockerTicketId,
-            dependentTicketId,
-            projectId,
-        });
-        if (!validation.ok) {
-            throw new HttpError(validation.status, validation.error);
-        }
-        const createdDependency = createTicketDependency(blockerTicketId, dependentTicketId);
-        if (!createdDependency) {
-            throw new HttpError(500, 'Unable to create the generated ticket dependency.');
-        }
-        createdDependencies.push(createdDependency);
-    }
     return { tickets: createdTickets, dependencies: createdDependencies };
 });
 const createChatProposedTickets = db.transaction(({ project, chatSession, proposals, }) => {
-    const createdTickets = [];
-    const createdDependencies = [];
-    const ticketIdsByKey = new Map();
-    for (const proposedTicket of proposals.tickets) {
-        const bundle = createAutoBundleForName(proposedTicket.title, project.id);
-        const createdTicket = createTicketRecord({
-            title: proposedTicket.title,
-            description: proposedTicket.description,
+    const bundle = createAutoPlanningBundle(project.id);
+    const { createdTickets, createdDependencies, ticketIdsByKey } = materializeTicketsWithDependencies({
+        options: {
+            projectId: project.id,
             model: chatSession.model,
             variant: chatSession.variant,
             skills: chatSession.skills,
-            tool: chatSession.tool,
-            projectId: project.id,
+            tool: null,
             worktreeBundleId: bundle.id,
-        });
-        if (!createdTicket) {
-            throw new HttpError(500, 'Unable to create the proposed tickets.');
-        }
-        createdTickets.push({ key: proposedTicket.key, ticket: createdTicket });
-        ticketIdsByKey.set(proposedTicket.key, createdTicket.id);
-    }
-    for (const dependency of proposals.dependencies) {
-        const blockerTicketId = ticketIdsByKey.get(dependency.blocker_key);
-        const dependentTicketId = ticketIdsByKey.get(dependency.dependent_key);
-        if (!blockerTicketId || !dependentTicketId) {
-            throw new HttpError(500, 'Chat ticket proposal returned a dependency for an unknown ticket key.');
-        }
-        const validation = validateCreateTicketDependency({
-            blockerTicketId,
-            dependentTicketId,
-            projectId: project.id,
-        });
-        if (!validation.ok) {
-            throw new HttpError(validation.status, validation.error);
-        }
-        const createdDependency = createTicketDependency(blockerTicketId, dependentTicketId);
-        if (!createdDependency) {
-            throw new HttpError(500, 'Unable to create the proposed ticket dependency.');
-        }
-        createdDependencies.push(createdDependency);
-    }
+        },
+        tickets: proposals.tickets,
+        dependencies: proposals.dependencies,
+    });
+    const createdTicketsWithKeys = createdTickets.map(ticket => {
+        const key = [...ticketIdsByKey.entries()].find(([, id]) => id === ticket.id)?.[0] ?? '';
+        return { key, ticket };
+    });
     return {
-        createdTickets,
+        createdTickets: createdTicketsWithKeys,
         createdDependencies,
     };
 });
@@ -2441,6 +2385,323 @@ app.post('/projects/:id/chat-sessions/:sessionId/messages/:messageId/create-tick
         return res.status(500).json({ error: getErrorMessage(error) || 'Unable to create tickets from the chat proposal.' });
     }
 });
+app.get('/projects/:id/spec-sessions', (req, res) => {
+    const project = getProjectById(req.params.id);
+    if (!project) {
+        return res.status(404).json({ error: 'Not found' });
+    }
+    return res.json(listSpecSessions(project.id));
+});
+app.post('/projects/:id/spec-sessions', (req, res) => {
+    const result = createProjectSpecSession({
+        projectId: req.params.id,
+        payload: req.body,
+        broadcaster: io,
+    });
+    if (!result.ok) {
+        return res.status(result.status).json({ error: result.error });
+    }
+    return res.status(result.status).json(result.value);
+});
+app.get('/projects/:id/spec-sessions/:sessionId', (req, res) => {
+    const project = getProjectById(req.params.id);
+    if (!project) {
+        return res.status(404).json({ error: 'Not found' });
+    }
+    const specSession = getProjectSpecSession(project.id, req.params.sessionId);
+    if (!specSession) {
+        return res.status(404).json({ error: 'Not found' });
+    }
+    const refreshedSpecSession = refreshSpecSessionUsageSnapshot(specSession.id, { includeMessages: true });
+    if (!refreshedSpecSession || refreshedSpecSession.project_id !== project.id) {
+        return res.json(specSession);
+    }
+    return res.json(refreshedSpecSession);
+});
+app.post('/projects/:id/spec-sessions/:sessionId/messages', (req, res) => {
+    const result = submitProjectSpecSessionMessage({
+        projectId: req.params.id,
+        specSessionId: req.params.sessionId,
+        payload: req.body,
+        broadcaster: io,
+    });
+    if (!result.ok) {
+        return res.status(result.status).json({ error: result.error });
+    }
+    return res.status(result.status).json(result.value);
+});
+app.post('/projects/:id/spec-sessions/:sessionId/attachments', (req, res) => {
+    const project = getProjectById(req.params.id);
+    if (!project) {
+        return res.status(404).json({ error: 'Not found' });
+    }
+    const specSession = getProjectSpecSession(project.id, req.params.sessionId);
+    if (!specSession) {
+        return res.status(404).json({ error: 'Not found' });
+    }
+    if (specSession.agent_status === 'running') {
+        return res.status(409).json({ error: 'Wait for the current spec response to finish before uploading images.' });
+    }
+    return specAttachmentUpload.array('files', MAX_SPEC_ATTACHMENTS_PER_TURN)(req, res, error => {
+        if (error) {
+            return res.status(400).json({ error: getSpecAttachmentUploadErrorMessage(error) });
+        }
+        const files = (req.files ?? []);
+        if (files.length === 0) {
+            return res.status(400).json({ error: 'At least one image is required.' });
+        }
+        for (const file of files) {
+            const validationError = validateImageAttachment({
+                mimeType: file.mimetype,
+                originalName: file.originalname,
+            });
+            if (validationError) {
+                return res.status(400).json({ error: validationError });
+            }
+        }
+        const createdAttachmentIds = [];
+        try {
+            const attachments = files.map(file => {
+                const attachment = createSpecAttachment({
+                    specSessionId: specSession.id,
+                    originalName: file.originalname,
+                    mimeType: file.mimetype,
+                    buffer: file.buffer,
+                    projectId: project.id,
+                });
+                createdAttachmentIds.push(attachment.id);
+                return attachment;
+            });
+            return res.status(201).json({ attachments });
+        }
+        catch (uploadError) {
+            for (const attachmentId of createdAttachmentIds) {
+                const attachment = getChatAttachmentById(attachmentId);
+                if (!attachment) {
+                    continue;
+                }
+                deleteSpecSessionAttachment(attachment);
+            }
+            return res.status(500).json({ error: uploadError instanceof Error ? uploadError.message : 'Unable to upload the selected images right now.' });
+        }
+    });
+});
+app.delete('/projects/:id/spec-sessions/:sessionId/attachments/:attachmentId', (req, res) => {
+    const project = getProjectById(req.params.id);
+    if (!project) {
+        return res.status(404).json({ error: 'Not found' });
+    }
+    const specSession = getProjectSpecSession(project.id, req.params.sessionId);
+    if (!specSession) {
+        return res.status(404).json({ error: 'Not found' });
+    }
+    const attachment = getSpecAttachmentForSession(req.params.attachmentId, specSession.id);
+    if (!attachment) {
+        return res.status(404).json({ error: 'Attachment not found' });
+    }
+    if (getSpecAttachmentLinkedMessageId(attachment.id)) {
+        return res.status(409).json({ error: 'Sent message attachments cannot be removed.' });
+    }
+    deleteSpecSessionAttachment(attachment);
+    return res.json({ ok: true });
+});
+app.get('/projects/:id/spec-sessions/:sessionId/attachments/:attachmentId/content', (req, res) => {
+    const project = getProjectById(req.params.id);
+    if (!project) {
+        return res.status(404).json({ error: 'Not found' });
+    }
+    const specSession = getProjectSpecSession(project.id, req.params.sessionId);
+    if (!specSession) {
+        return res.status(404).json({ error: 'Not found' });
+    }
+    const attachment = getSpecAttachmentForSession(req.params.attachmentId, specSession.id);
+    if (!attachment) {
+        return res.status(404).json({ error: 'Attachment not found' });
+    }
+    try {
+        const content = readSpecAttachmentContent(attachment);
+        res.type(attachment.mime_type);
+        return res.send(content);
+    }
+    catch {
+        return res.status(404).json({ error: 'Attachment content not found' });
+    }
+});
+app.post('/projects/:id/spec-sessions/:sessionId/stop', async (req, res) => {
+    const result = await stopProjectSpecSessionResponse({
+        projectId: req.params.id,
+        specSessionId: req.params.sessionId,
+    });
+    if (!result.ok) {
+        return res.status(result.status).json({ error: result.error });
+    }
+    return res.status(result.status).json(result.value);
+});
+app.delete('/projects/:id/spec-sessions/:sessionId', (req, res) => {
+    const project = getProjectById(req.params.id);
+    if (!project) {
+        return res.status(404).json({ error: 'Not found' });
+    }
+    const specSession = getProjectSpecSession(project.id, req.params.sessionId);
+    if (!specSession) {
+        return res.status(404).json({ error: 'Not found' });
+    }
+    if (specSession.agent_status === 'running') {
+        return res.status(409).json({ error: 'Wait for the current spec response to finish before deleting this session.' });
+    }
+    deleteProjectSpecSession({
+        projectId: project.id,
+        specSessionId: specSession.id,
+        broadcaster: io,
+    });
+    return res.json({ ok: true });
+});
+app.get('/projects/:id/spec-sessions/:sessionId/snapshots/:snapshotId', (req, res) => {
+    const project = getProjectById(req.params.id);
+    if (!project) {
+        return res.status(404).json({ error: 'Not found' });
+    }
+    const specSession = getProjectSpecSession(project.id, req.params.sessionId);
+    if (!specSession) {
+        return res.status(404).json({ error: 'Not found' });
+    }
+    const snapshot = getSpecSnapshot(req.params.snapshotId);
+    if (!snapshot) {
+        return res.status(404).json({ error: 'Not found' });
+    }
+    if (snapshot.spec_session_id !== specSession.id) {
+        return res.status(404).json({ error: 'Not found' });
+    }
+    return res.json({
+        ...snapshot,
+        created_ticket_ids: getCreatedTicketIdsForSnapshot(snapshot.id, project.id),
+    });
+});
+app.post('/projects/:id/spec-sessions/:sessionId/snapshots/:snapshotId/create-tickets', (req, res) => {
+    const project = getProjectById(req.params.id);
+    if (!project) {
+        return res.status(404).json({ error: 'Not found' });
+    }
+    const specSession = getProjectSpecSession(project.id, req.params.sessionId);
+    if (!specSession) {
+        return res.status(404).json({ error: 'Not found' });
+    }
+    const snapshot = getSpecSnapshot(req.params.snapshotId);
+    if (!snapshot || snapshot.spec_session_id !== specSession.id) {
+        return res.status(404).json({ error: 'Not found' });
+    }
+    if (snapshot.tickets.length === 0) {
+        return res.status(409).json({ error: 'This spec snapshot has no proposed tickets to create.' });
+    }
+    const existingTicketIds = getCreatedTicketIdsForSnapshot(snapshot.id, project.id);
+    if (existingTicketIds.length > 0) {
+        return res.status(409).json({
+            error: 'Tickets have already been created from this spec snapshot.',
+            existing_ticket_ids: existingTicketIds,
+        });
+    }
+    const ticketsWithoutTestingGuidance = snapshot.tickets.filter(ticket => !hasTestingGuidance(ticket.description));
+    if (ticketsWithoutTestingGuidance.length > 0) {
+        const ticketKeys = ticketsWithoutTestingGuidance.map(ticket => ticket.key).join(', ');
+        return res.status(422).json({
+            error: `Spec tickets must include testing or verification guidance in their descriptions before they can be created on the board. Missing guidance in: ${ticketKeys}`,
+        });
+    }
+    try {
+        const bundleName = specSession.external_source?.external_key ?? '';
+        const bundle = bundleName
+            ? createAutoBundleForName(bundleName, project.id)
+            : createAutoPlanningBundle(project.id);
+        const { createdTickets, createdDependencies } = materializeTicketsWithDependencies({
+            options: {
+                projectId: project.id,
+                model: specSession.model,
+                variant: specSession.variant,
+                skills: specSession.skills,
+                tool: null,
+                worktreeBundleId: bundle.id,
+                originSpecSessionId: specSession.id,
+                originSpecSnapshotId: snapshot.id,
+            },
+            tickets: snapshot.tickets,
+            dependencies: snapshot.dependencies,
+        });
+        for (const createdTicket of createdTickets) {
+            io.emit('ticket:created', createdTicket);
+        }
+        for (const createdDependency of createdDependencies) {
+            io.emit('ticket-dependency:created', createdDependency);
+        }
+        return res.status(201).json({
+            tickets: createdTickets,
+            dependencies: createdDependencies,
+        });
+    }
+    catch (error) {
+        if (error instanceof HttpError) {
+            return res.status(error.status).json({ error: error.message });
+        }
+        return res.status(500).json({ error: getErrorMessage(error) || 'Unable to create tickets from the spec snapshot.' });
+    }
+});
+app.post('/projects/:id/spec-sessions/:sessionId/snapshots/:snapshotId/implement-in-chat', (req, res) => {
+    const project = getProjectById(req.params.id);
+    if (!project) {
+        return res.status(404).json({ error: 'Not found' });
+    }
+    const specSession = getProjectSpecSession(project.id, req.params.sessionId);
+    if (!specSession) {
+        return res.status(404).json({ error: 'Not found' });
+    }
+    const snapshot = getSpecSnapshot(req.params.snapshotId);
+    if (!snapshot || snapshot.spec_session_id !== specSession.id) {
+        return res.status(404).json({ error: 'Not found' });
+    }
+    const draftText = buildSpecImplementationDraft({ snapshot, specSession });
+    return res.status(200).json({
+        draft_text: draftText,
+        spec_session_id: specSession.id,
+        spec_snapshot_id: snapshot.id,
+    });
+});
+app.post('/projects/:id/spec-sessions/:sessionId/snapshots/:snapshotId/export', (req, res) => {
+    const project = getProjectById(req.params.id);
+    if (!project) {
+        return res.status(404).json({ error: 'Not found' });
+    }
+    const specSession = getProjectSpecSession(project.id, req.params.sessionId);
+    if (!specSession) {
+        return res.status(404).json({ error: 'Not found' });
+    }
+    const snapshot = getSpecSnapshot(req.params.snapshotId);
+    if (!snapshot || snapshot.spec_session_id !== specSession.id) {
+        return res.status(404).json({ error: 'Not found' });
+    }
+    try {
+        const collision = checkSpecExportCollision({
+            specSession,
+            repoPath: project.repo_path,
+        });
+        if (collision) {
+            return res.status(409).json({
+                error: 'A spec with this title has already been exported.',
+                conflicting_path: collision,
+            });
+        }
+        const result = exportSpecToDocs({
+            snapshot,
+            specSession,
+            repoPath: project.repo_path,
+        });
+        return res.status(201).json({
+            path: result.filePath,
+            content: result.content,
+        });
+    }
+    catch (error) {
+        return res.status(500).json({ error: getErrorMessage(error) || 'Unable to export the spec snapshot.' });
+    }
+});
 app.get('/tickets', async (req, res) => {
     const requestedProjectId = getRequestedProjectId(req);
     const detail = req.query.detail === 'board-enrichment'
@@ -4635,9 +4896,9 @@ app.post('/tickets', (req, res) => {
     if (!project) {
         return res.status(400).json({ error: 'project_id must reference an existing project' });
     }
-    const tool = resolveChatTool(req.body.tool ?? config.tool);
-    const model = tool === 'opencode' && req.body.model != null ? normalizeModelId(req.body.model) || null : null;
-    const variant = tool === 'opencode' && typeof req.body.variant === 'string' && req.body.variant.trim()
+    const requestTool = resolveChatTool(req.body.tool ?? config.tool);
+    const model = requestTool === 'opencode' && req.body.model != null ? normalizeModelId(req.body.model) || null : null;
+    const variant = requestTool === 'opencode' && typeof req.body.variant === 'string' && req.body.variant.trim()
         ? req.body.variant.trim()
         : null;
     const skills = resolveRequestedSkills(req.body.skills);
@@ -4665,7 +4926,7 @@ app.post('/tickets', (req, res) => {
             model,
             variant,
             skills,
-            tool,
+            tool: null,
             projectId: project_id,
             worktreeBundleId: resolvedBundleId,
             externalSource,