specrails-desktop 2.64.1 → 2.65.0

package/server/dist/project-router-tickets.js

@@ -44,14 +44,18 @@ const project_repositories_1 = require("./project-repositories");
 const ids_1 = require("./ids");
 const db_1 = require("./db");
 const providers_1 = require("./providers");
+const non_goals_1 = require("./modules/specs/domain/non-goals");
 const contract_refine_runner_1 = require("./modules/specs/runtime/contract-refine-runner");
 const explore_contract_refine_1 = require("./modules/conversations/runtime/explore-contract-refine");
+const ticket_trash_1 = require("./modules/specs/runtime/ticket-trash");
+const ticket_trash_service_1 = require("./modules/specs/runtime/ticket-trash-service");
 const smash_runner_1 = require("./modules/specs/runtime/smash-runner");
 const explore_smash_1 = require("./modules/conversations/runtime/explore-smash");
 const ai_invocations_1 = require("./modules/accounting/runtime/ai-invocations");
-const context_scope_1 = require("./modules/conversations/runtime/context-scope");
+const spec_generation_1 = require("./modules/specs/runtime/spec-generation");
 const result_event_1 = require("./modules/accounting/runtime/result-event");
 const runtime_1 = require("./providers/runtime");
+const project_env_1 = require("./project-env");
 const crypto_1 = require("crypto");
 const spec_models_1 = require("./modules/specs/runtime/spec-models");
 const provider_selection_1 = require("./provider-selection");
@@ -63,10 +67,12 @@ const transient_children_1 = require("./transient-children");
 const process_admission_1 = require("./process-admission");
 const readline_1 = require("readline");
 const tree_kill_1 = __importDefault(require("tree-kill"));
-const workspace_resolution_1 = require("./workspace-resolution");
 const multer_1 = __importDefault(require("multer"));
+const timeline_http_1 = require("./modules/specs/adapters/timeline-http");
 const attachment_manager_1 = require("./attachment-manager");
 const project_router_helpers_1 = require("./project-router-helpers");
+/** The client's Undo window (8 s) plus margin: outbound Jira writes of undoable edits wait this long. */
+const UNDO_WINDOW_HOLD_MS = 10_000;
 /**
  * A NULL conversation provider is the intentional single-provider encoding:
  * it means "use this project's primary provider", never "use Claude".
@@ -174,6 +180,86 @@ function registerTicketsRoutes(deps) {
             res.status(500).json({ error: 'Failed to read tickets' });
         }
     });
+    // ─── Recently deleted (soft-deleted specs) ───────────────────────────────────
+    // Registered before GET /tickets/:id so `trash` is not read as a ticket id.
+    const trashDeps = (req) => {
+        const c = ctx(req);
+        return {
+            ticketStorePath: () => ticketPath(req),
+            db: c.db,
+            deleteAttachments: (key) => attachment_manager_1.attachmentManager.deleteAll(c.project.slug, key),
+            forgetExploreConversation: (conversationId) => {
+                c.chatManager?.forgetSpecDraft(conversationId);
+                c.chatManager?.forgetExploreLifecycle(conversationId);
+            },
+        };
+    };
+    // GET /:projectId/tickets/trash — "Recently deleted" specs (newest first).
+    router.get('/:projectId/tickets/trash', async (req, res) => {
+        try {
+            await (0, ticket_trash_service_1.purgeProjectTrash)(trashDeps(req));
+            const items = (0, ticket_trash_1.listTrashedTickets)(ticketPath(req)).map((e) => ({
+                ticket: e.ticket,
+                deletedAt: e.deleted_at,
+                purgeAt: new Date(Date.parse(e.deleted_at) + ticket_trash_1.TRASH_RETENTION_MS).toISOString(),
+            }));
+            res.json({ items, retentionDays: ticket_trash_1.TRASH_RETENTION_DAYS });
+        }
+        catch (err) {
+            console.error('[project-router] ticket trash list error:', err);
+            res.status(500).json({ error: 'Failed to read recently deleted specs' });
+        }
+    });
+    // POST /:projectId/tickets/:id/restore — Undo a delete. Idempotent.
+    router.post('/:projectId/tickets/:id/restore', (req, res) => {
+        const ticketId = req.params.id;
+        if (!/^\d+$/.test(ticketId)) {
+            res.status(400).json({ error: 'Invalid ticket ID' });
+            return;
+        }
+        try {
+            const result = (0, ticket_trash_1.restoreTicket)(ticketPath(req), Number(ticketId));
+            if (!result) {
+                res.status(404).json({ error: 'Ticket not found in recently deleted' });
+                return;
+            }
+            const { broadcast, ticketWatcher, project } = ctx(req);
+            if (!result.alreadyLive) {
+                ticketWatcher.notifyDesktopWrite(result.revision);
+                const now = new Date().toISOString();
+                broadcast({ type: 'ticket_created', ticket: result.ticket, projectId: project.id, timestamp: now });
+                for (const child of result.readoptedChildren) {
+                    broadcast({ type: 'ticket_updated', ticket: child, projectId: project.id, timestamp: now });
+                }
+            }
+            res.json({ ok: true, ticket: result.ticket, revision: result.revision, alreadyLive: result.alreadyLive });
+        }
+        catch (err) {
+            console.error('[project-router] ticket restore error:', err);
+            res.status(500).json({ error: 'Failed to restore ticket' });
+        }
+    });
+    // DELETE /:projectId/tickets/trash/:id — "Delete permanently" (the one confirmed step).
+    router.delete('/:projectId/tickets/trash/:id', async (req, res) => {
+        const ticketId = req.params.id;
+        if (!/^\d+$/.test(ticketId)) {
+            res.status(400).json({ error: 'Invalid ticket ID' });
+            return;
+        }
+        try {
+            const entry = (0, ticket_trash_1.purgeTrashedTicket)(ticketPath(req), Number(ticketId));
+            if (!entry) {
+                res.status(404).json({ error: 'Ticket not found in recently deleted' });
+                return;
+            }
+            await (0, ticket_trash_service_1.finalizeTrashedTicket)(trashDeps(req), entry);
+            res.json({ ok: true });
+        }
+        catch (err) {
+            console.error('[project-router] ticket permanent delete error:', err);
+            res.status(500).json({ error: 'Failed to delete ticket permanently' });
+        }
+    });
     // GET /:projectId/tickets/:id — Get single ticket
     router.get('/:projectId/tickets/:id', (req, res) => {
         const ticketId = req.params.id;
@@ -244,19 +330,11 @@ function registerTicketsRoutes(deps) {
         const projectId = project.id;
         const admission = (0, process_admission_1.captureProcessAdmission)(projectId);
         const filePath = ticketPath(req);
-        let hasAttachments = false;
-        let baseUserPrompt = `Generate a spec for the following idea:\n\n${idea.trim()}`;
-        let imageFlags = [];
-        let imagePaths = [];
+        let attachments;
         if (attachmentIds.length > 0 && pendingSpecId) {
             try {
                 const extracted = await attachment_manager_1.attachmentManager.getClaudeArgs(project.slug, pendingSpecId, attachmentIds);
-                imageFlags = extracted.imageFlags;
-                imagePaths = extracted.imagePaths;
-                if (extracted.textBlocks.length > 0) {
-                    hasAttachments = true;
-                    baseUserPrompt = `${baseUserPrompt}\n\n## Attached Resources\n\n${extracted.textBlocks.join('\n\n')}`;
-                }
+                attachments = { textBlocks: extracted.textBlocks, imageFlags: extracted.imageFlags, imagePaths: extracted.imagePaths };
             }
             catch (err) {
                 console.error('[project-router] generate-spec attachment extraction error:', err);
@@ -286,16 +364,12 @@ function registerTicketsRoutes(deps) {
             // Quick spawns from project.path, so project `.mcp.json` (the `mcp`
             // toggle) is discovered natively. `userMcp` additionally loads the
             // developer's user-scope/plugin/connector MCP servers via the claude
-            // adapter's `loadUserEnv` (see below).
+            // adapter's `loadUserEnv`.
             mcp: typeof rawScope?.mcp === 'boolean' ? rawScope.mcp : false,
             contractRefine: quickContractRefine,
             userMcp: typeof rawScope?.userMcp === 'boolean' ? rawScope.userMcp : false,
         };
-        const adapter = (0, providers_1.getAdapter)(provider);
-        const quickToolPolicy = quickScope.full
-            ? ((0, runtime_1.supportsToolPolicy)(adapter, 'read-only') ? 'read-only' : null)
-            : (0, runtime_1.pureOutputToolPolicy)(adapter);
-        if (!quickToolPolicy) {
+        if (!(0, spec_generation_1.resolveSpecGenerationToolPolicy)(provider, quickScope)) {
             res.status(409).json({
                 error: 'provider_tool_policy_unsupported',
                 provider,
@@ -305,269 +379,45 @@ function registerTicketsRoutes(deps) {
         }
         // Persist Quick mode Contract Refine choice (per-project last value).
         (0, db_1.setQuickContractRefineLast)(ctx(req).db, quickContractRefine);
-        // Relocate-artifacts: tickets read from the workspace when relocated.
-        const quickSpecRoot = (() => {
-            const e = (0, workspace_resolution_1.resolveProjectExecution)({ slug: project.slug, path: project.path });
-            return e.relocated && e.workspaceDir ? e.workspaceDir : project.path;
-        })();
-        const specsPrefix = (0, context_scope_1.buildScopedSystemPromptPrefix)(quickScope, project.path, quickSpecRoot);
-        const codebaseRule = quickScope.full
-            ? `- You MAY use Read, Grep, and Glob to inspect the project codebase. Bash is not available.`
-            : hasAttachments
-                ? `- Do NOT explore the project codebase. The resources inside <user-attachment> blocks below are pre-loaded context the user intentionally provided — read and use them freely.`
-                : `- Do NOT read any files or explore the codebase. Work purely from the user's description.`;
-        // The specrails-tickets prefix (when scope.specrails is toggled on)
-        // dumps every ticket into the prompt as informational context. Without
-        // an explicit dedup instruction the model treats it as background and
-        // still proposes a near-duplicate of something already in the backlog.
-        // Adding the rule here, gated on `quickScope.specrails`, keeps the
-        // "toggle is the only gate" contract the user asked for.
-        const dedupRule = quickScope.specrails
-            ? `- The "Specrails Tickets" section above lists every ticket already in the backlog. Do NOT propose a duplicate or a near-duplicate of any of them. If the user's idea is already covered by an existing ticket, say so in "Problem Statement" and pick a *different* angle / sub-feature / next step that builds on the existing one — do not repeat it.\n`
-            : '';
-        const backlogRecommendationRule = quickScope.specrails
-            ? `- If the user's idea asks for the "next best spec" or a backlog recommendation, use the existing tickets and OpenSpec context to choose one concrete next spec. Do not respond with generic product directions.\n`
-            : '';
-        let baseSystemPrompt = `You are a senior product engineer generating a structured spec proposal.\n\n` +
-            (specsPrefix ? `${specsPrefix}\n\n` : '') +
-            `RULES:\n` +
-            `${codebaseRule}\n` +
-            dedupRule +
-            backlogRecommendationRule +
-            `- Do NOT create files, tickets, or issues.\n` +
-            `- Output ONLY the structured markdown below. No preamble, no explanation.\n\n` +
-            `REQUIRED FORMAT:\n` +
-            `## Spec Title\n[Concise, action-oriented title]\n\n` +
-            `## Labels\n[2-4 short kebab-case tags categorising the spec — comma-separated on one line, e.g. "ui, settings, dark-mode". Lowercase, no spaces inside a tag.]\n\n` +
-            `## Problem Statement\n[2-3 sentences]\n\n` +
-            `## Proposed Solution\n[3-5 sentences]\n\n` +
-            `## Out of Scope\n[Bullet list]\n\n` +
-            `## Acceptance Criteria\n[Numbered list of testable outcomes]\n\n` +
-            `## Technical Considerations\n[Bullet list]\n\n` +
-            `## Estimated Complexity\n[Low/Medium/High/Very High + one sentence justification]\n\n` +
-            `## Short Summary\n[One or two plain-language sentences, max 120 characters total, that capture the essence of this spec for a dashboard postit. No markdown, no bullets, no headings.]`;
-        if (hasAttachments)
-            baseSystemPrompt = `${baseSystemPrompt}\n\n${attachment_manager_1.USER_ATTACHMENT_SYSTEM_NOTE}`;
-        const selectedIds = res.locals.repositoryIds;
-        if ((0, project_repositories_1.getProjectRepositories)(project).length > 1) {
-            baseSystemPrompt += `\n\nThis logical project has one shared backlog across these repositories: ${JSON.stringify((0, project_repositories_1.getProjectRepositories)(project).map(({ id, name, path, isPrimary, kind }) => ({ id, name, path, isPrimary, kind })))}.\nThis spec targets repository IDs: ${JSON.stringify(selectedIds ?? [(0, project_repositories_1.getProjectRepositories)(project).find((repo) => repo.isPrimary).id])}. Describe cross-repository contracts when selected; do not create separate tickets per repository.`;
-        }
-        const systemPrompt = baseSystemPrompt;
-        const userPrompt = baseUserPrompt;
-        // Generate-spec spawn args are adapter-driven. For Claude the `--tools`
-        // flag set comes from `toolFlagsForScope(quickScope)` which the adapter
-        // doesn't model — pass them through `extraArgs` so they slot in after
-        // the standard COMMON_FLAGS. `imageFlags` (also Claude-only) goes the
-        // same way. For codex the system prompt folds into the user prompt
-        // (no --system-prompt flag) and the extra Claude-only flags are ignored
-        // by the codex adapter (it doesn't read extraArgs that don't apply).
-        const toolFlags = provider === 'claude' ? (0, context_scope_1.toolFlagsForScope)(quickScope) : { args: [] };
-        // Full scope grants Read/Grep/Glob. The model spends turns exploring the
-        // repo before it writes the spec; 6 was too tight (a few tool calls on a
-        // sparse/empty repo hit error_max_turns → exit 1 → opaque failure). 15
-        // leaves comfortable headroom while --max-turns still bounds runaway loops.
-        const claudeMaxTurns = quickScope.full ? 15 : (hasAttachments ? 3 : 1);
-        const specGenOptions = {
-            prompt: userPrompt,
-            systemPrompt,
+        // The spec-generation use case owns the provider spawn, parsing, ticket
+        // persistence, Contract Layer scheduling and accounting; this route maps
+        // its lifecycle onto the spec_gen_* / ticket_created WebSocket contract.
+        (0, spec_generation_1.startSpecGeneration)({
+            db: ctx(req).db,
+            project,
+            ticketStorePath: filePath,
+            ticketWatcher,
+            broadcast: broadcast,
+            admission,
+        }, {
+            text: idea,
+            provider,
             model: resolvedModel,
-            toolPolicy: quickToolPolicy,
-            maxTurns: provider === 'claude' ? claudeMaxTurns : undefined,
-            extraArgs: provider === 'claude' ? [...toolFlags.args, ...imageFlags] : undefined,
-            // "My approved MCPs" (scope.userMcp) loads the developer's user-scope,
-            // plugin, and connector MCP servers (claude-only). Quick already spawns
-            // from project.path so project `.mcp.json` is discovered without a flag.
-            loadUserEnv: adapter.capabilities.userMcp === true && quickScope.userMcp,
-            imagePaths: adapter.capabilities.supportsImageInput ? imagePaths : undefined,
-        };
-        const args = adapter.buildArgs('spec-gen', specGenOptions);
-        const binary = adapter.binary;
-        // Relocate-artifacts gate: spawn from the workspace + SPECRAILS_REPO_DIR when
-        // relocated, else cwd = project.path + process.env (byte-identical legacy).
-        const specGenExec = (0, workspace_resolution_1.resolveProjectExecution)({ slug: project.slug, path: project.path });
-        let specGenEnv = process.env;
-        if (specGenExec.relocated) {
-            specGenEnv = { ...process.env, ...specGenExec.env };
-            if (adapter.id === 'gemini')
-                specGenEnv = { ...specGenEnv, GEMINI_CLI_TRUST_WORKSPACE: 'true' };
-        }
-        // spawnAiCli reroutes multi-line argv values through stdin on Windows;
-        // POSIX argv path unchanged.
-        console.log(`[project-router] spec-gen spawn: ${binary} (cwd=${specGenExec.cwd}, requestId=${requestId})`);
-        const child = (0, cli_prompt_1.spawnAiCli)(binary, args, {
-            env: (0, runtime_1.buildProviderEnv)(adapter, specGenOptions, specGenEnv),
-            stdio: ['ignore', 'pipe', 'pipe'],
-            cwd: specGenExec.cwd,
-        });
-        // Register so removeProject()/shutdown() can tree-kill this otherwise-untracked
-        // fire-and-forget child (auto-unregisters on close/error).
-        (0, transient_children_1.trackTransientChild)(projectId, child);
-        // Watchdog: unlike ai-edit, generate-spec keeps no cancellable handle, so a
-        // hung CLI (network stall, model never emitting a terminating event) would
-        // otherwise leak this child + its readline for the app's lifetime. Cap is
-        // generous — the 'full' scope can legitimately run minutes and --max-turns
-        // bounds turns, not wall-clock. Cleared on close/error.
-        const GENERATE_SPEC_TIMEOUT_MS = 8 * 60 * 1000;
-        let specGenWatchdog = setTimeout(() => {
-            specGenWatchdog = null;
-            if (child.pid) {
-                try {
-                    (0, tree_kill_1.default)(child.pid, 'SIGTERM');
-                }
-                catch { /* best-effort */ }
-            }
-            if (!admission.isCurrent())
-                return;
-            broadcast({
-                type: 'spec_gen_error', projectId, requestId,
-                error: `Spec generation timed out after ${Math.round(GENERATE_SPEC_TIMEOUT_MS / 1000)}s`,
-                timestamp: new Date().toISOString(),
-            });
-        }, GENERATE_SPEC_TIMEOUT_MS);
-        if (typeof specGenWatchdog.unref === 'function')
-            specGenWatchdog.unref();
-        const clearSpecGenWatchdog = () => {
-            if (specGenWatchdog) {
-                clearTimeout(specGenWatchdog);
-                specGenWatchdog = null;
-            }
-        };
-        // Capture stderr so failures (auth missing, model errors, etc.) surface
-        // in the server log instead of being swallowed.
-        let stderrBuf = '';
-        /* c8 ignore start -- diagnostic-only; fires only when claude writes stderr */
-        child.stderr?.on('data', (chunk) => {
-            const s = chunk.toString();
-            stderrBuf += s;
-            console.error(`[project-router] spec-gen stderr (${requestId}): ${s.trimEnd()}`);
-        });
-        /* c8 ignore stop */
-        // Without this listener, ENOENT (binary missing on PATH) propagates as
-        // an unhandled 'error' event and crashes the entire app process.
-        /* c8 ignore start -- spawn-failure path; exercised manually, not in CI */
-        child.on('error', (err) => {
-            clearSpecGenWatchdog();
-            console.error(`[project-router] spec-gen spawn failed (${binary}): ${err.message}`);
-            if (!admission.isCurrent())
-                return;
-            const errMsg = {
-                type: 'spec_gen_error', projectId, requestId,
-                error: `Failed to launch ${binary}: ${err.message}`,
-                timestamp: new Date().toISOString(),
-            };
-            broadcast(errMsg);
-        });
-        /* c8 ignore stop */
-        res.status(202).json({ requestId });
-        let buffer = '';
-        let lastResultEvent = null;
-        // Canonical adapter events feed finaliseInvocationResult on close, giving
-        // codex a real pricing-table cost estimate (+ estimated flag) and tokens,
-        // instead of the legacy hardcoded $0. Accumulated ALONGSIDE the existing
-        // buffer/delta plumbing below — never in place of it.
-        const adapterEvents = [];
-        const turnStartedAt = new Date().toISOString();
-        const stdoutReader = (0, readline_1.createInterface)({ input: child.stdout, crlfDelay: Infinity });
-        stdoutReader.on('line', (line) => {
-            if (!admission.isCurrent())
-                return;
-            const eventsForLine = (0, runtime_1.parseStreamEvents)(adapter, line);
-            adapterEvents.push(...eventsForLine);
-            let parsed = null;
-            try {
-                parsed = JSON.parse(line);
-            }
-            catch { /* skip */ }
-            if (parsed && eventsForLine.some((event) => event.kind === 'result')) {
-                lastResultEvent = parsed;
-            }
-            for (const event of eventsForLine) {
-                if (event.kind !== 'text-delta' || !event.text)
-                    continue;
-                buffer += event.text;
-                const wsMsg = {
-                    type: 'spec_gen_stream', projectId, requestId,
-                    delta: event.text, timestamp: new Date().toISOString(),
-                };
-                broadcast(wsMsg);
-            }
-        });
-        child.on('close', async (code) => {
-            clearSpecGenWatchdog();
-            if (!admission.isCurrent())
-                return;
-            let createdTicketId = null;
-            // When claude burns its whole --max-turns budget it exits non-zero with
-            // a result event of subtype:error_max_turns — but it may already have
-            // emitted a complete spec. Salvage that usable output instead of failing
-            // the whole request on an exit code.
-            const resultSubtype = lastResultEvent?.subtype ?? null;
-            const hasUsableSpec = buffer.trim().length > 0 && /##\s*Spec Title/i.test(buffer);
-            const salvageMaxTurns = code !== 0 && resultSubtype === 'error_max_turns' && hasUsableSpec;
-            if ((code === 0 && buffer.trim()) || salvageMaxTurns) {
-                if (salvageMaxTurns) {
-                    console.warn(`[project-router] spec-gen salvaged partial output after error_max_turns (${requestId}); ` +
-                        `consider raising --max-turns if this recurs`);
-                }
-                // Extract title from generated spec
-                const titleMatch = buffer.match(/##\s*Spec Title\s*\n+(.+)/);
-                const specTitle = titleMatch ? titleMatch[1].trim() : idea.trim().slice(0, 80);
-                // Extract complexity for priority mapping
-                const complexityMatch = buffer.match(/##\s*Estimated Complexity\s*\n+(\w+)/);
-                const complexity = complexityMatch ? complexityMatch[1].toLowerCase() : 'medium';
-                const priority = complexity === 'low' ? 'low' : complexity === 'high' || complexity === 'very' ? 'high' : 'medium';
-                // Extract labels from the `## Labels` section. Comma- or
-                // newline-separated tags, normalised to lowercase kebab-case.
-                // `spec-proposal` is always retained as the marker label.
-                const labelsMatch = buffer.match(/##\s*Labels\s*\n+([^\n]+(?:\n(?!##)[^\n]+)*)/);
-                const claudeLabels = labelsMatch
-                    ? labelsMatch[1]
-                        .replace(/[\[\]]/g, '')
-                        .split(/[,\n]/)
-                        .map((s) => s.trim().toLowerCase().replace(/\s+/g, '-').replace(/[^a-z0-9-]/g, ''))
-                        .filter((s) => s.length > 0 && s.length <= 32)
-                        .slice(0, 6)
-                    : [];
-                const finalLabels = Array.from(new Set(['spec-proposal', ...claudeLabels]));
-                const shortSummary = (0, ticket_store_1.clampShortSummary)((0, project_router_helpers_1.extractShortSummary)(buffer));
-                const description = (0, project_router_helpers_1.stripSpecMetadataSections)(buffer);
-                // Create ticket directly
-                try {
-                    const now = new Date().toISOString();
-                    let created;
-                    const store = (0, ticket_store_1.mutateStore)(filePath, (s) => {
-                        const id = s.next_id++;
-                        const ticket = {
-                            ...repositoryScope(req, res),
-                            id,
-                            title: specTitle,
-                            description,
-                            status: 'todo',
-                            priority: priority,
-                            labels: finalLabels,
-                            assignee: null,
-                            prerequisites: [],
-                            metadata: {},
-                            comments: [],
-                            origin_conversation_id: null,
-                            is_epic: false,
-                            parent_epic_id: null,
-                            execution_order: null,
-                            short_summary: shortSummary,
-                            created_at: now,
-                            updated_at: now,
-                            created_by: 'sr-product-engineer',
-                            source: 'propose-spec',
-                        };
-                        s.tickets[String(id)] = ticket;
-                        created = ticket;
-                    });
-                    ticketWatcher.notifyDesktopWrite(store.revision);
-                    if (created)
-                        createdTicketId = created.id;
+            scope: quickScope,
+            repositoryIds: res.locals.repositoryIds,
+            resolveRepositoryScope: () => repositoryScope(req, res),
+            attachments,
+            contractRefine: quickContractRefine ? { model: req.body?.model ?? null } : null,
+            requestId,
+            hooks: {
+                onDelta: (delta) => {
+                    const wsMsg = {
+                        type: 'spec_gen_stream', projectId, requestId,
+                        delta, timestamp: new Date().toISOString(),
+                    };
+                    broadcast(wsMsg);
+                },
+                onError: (error) => {
+                    const msg = {
+                        type: 'spec_gen_error', projectId, requestId,
+                        error, timestamp: new Date().toISOString(),
+                    };
+                    broadcast(msg);
+                },
+                onPersisted: async (created) => {
                     // Migrate attachments from pendingSpecId → real ticket id (if any were uploaded).
                     // Must complete BEFORE broadcasting ticket_created so WS listeners see the populated attachments[].
-                    if (pendingSpecId && created) {
+                    if (pendingSpecId) {
                         try {
                             const migrated = await attachment_manager_1.attachmentManager.renameTicketDir({
                                 slug: project.slug,
@@ -583,7 +433,7 @@ function registerTicketsRoutes(deps) {
                             console.error('[project-router] generate-spec attachment migration error:', err);
                         }
                         if (!admission.isCurrent())
-                            return;
+                            return 'abort';
                     }
                     const ticketMsg = {
                         type: 'ticket_created', ticket: created,
@@ -598,91 +448,10 @@ function registerTicketsRoutes(deps) {
                     // Add Spec → Jira: promote the new ticket to a Jira issue when the
                     // project is Jira-backed (unless the user opted to keep it local).
                     void maybePromoteSpecToJira(ctx(req), created.id, req.body?.createLocal === true, broadcast);
-                    // Quick mode Contract Refine runs on the same selected provider.
-                    if (quickContractRefine && created) {
-                        const refineTicketId = created.id;
-                        const refineTitle = created.title;
-                        const refineDescription = created.description;
-                        const refineModel = req.body?.model ?? null;
-                        process.nextTick(() => {
-                            if (!admission.isCurrent())
-                                return;
-                            void (0, contract_refine_runner_1.runContractRefineForQuick)({
-                                db: ctx(req).db,
-                                projectId: project.id,
-                                projectSlug: project.slug,
-                                projectPath: project.path,
-                                projectName: project.name,
-                                providerId: provider,
-                                broadcast: broadcast,
-                            }, refineTicketId, refineTitle, refineDescription, refineModel).catch((err) => {
-                                console.error('[project-router] runContractRefineForQuick error:', err);
-                            });
-                        });
-                    }
-                }
-                catch (err) {
-                    console.error('[project-router] generate-spec ticket creation error:', err);
-                    const errMsg = {
-                        type: 'spec_gen_error', projectId, requestId,
-                        error: 'Failed to create ticket', timestamp: new Date().toISOString(),
-                    };
-                    broadcast(errMsg);
-                }
-            }
-            else {
-                const reason = code === 0
-                    ? 'Empty response from AI'
-                    : resultSubtype === 'error_max_turns'
-                        ? 'AI hit its turn limit before finishing the spec. Try again, or narrow the idea / turn off full-codebase context.'
-                        : `Process exited with code ${code}`;
-                console.error(`[project-router] spec-gen failed (${requestId}): ${reason}` +
-                    (stderrBuf.trim() ? `\n  stderr: ${stderrBuf.trim()}` : '') +
-                    (buffer.trim() ? `\n  stdout-buffer: ${buffer.trim().slice(0, 500)}` : ''));
-                const msg = {
-                    type: 'spec_gen_error', projectId, requestId,
-                    error: reason,
-                    timestamp: new Date().toISOString(),
-                };
-                broadcast(msg);
-            }
-            // ai_invocations capture (surface='quick-spec'). Always emit a row, success or fail.
-            try {
-                // Adapter-driven finalisation: claude passes its native total_cost_usd
-                // through untouched; codex (nativeCostUsd:false) gets a pricing-table
-                // estimate from its captured token usage + estimated=true. This
-                // replaces the legacy normaliseResultEvent path that hardcoded codex
-                // cost to $0 and never set the estimated flag.
-                const { result: normalised, estimated } = (0, result_event_1.finaliseInvocationResult)(adapter, adapterEvents, { fallbackModel: resolvedModel });
-                // extractCodexResult does not surface duration (codex stream carries
-                // none); stamp wall-clock so the row's duration isn't lost. Claude's
-                // result event already provides duration_ms, so prefer it.
-                const wallMs = Date.now() - new Date(turnStartedAt).getTime();
-                (0, ai_invocations_1.recordInvocation)(ctx(req).db, {
-                    id: (0, crypto_1.randomUUID)(),
-                    project_id: projectId,
-                    provider: adapter.id,
-                    surface: 'quick-spec',
-                    surface_ref_id: requestId,
-                    ticket_id: createdTicketId,
-                    // A ticket was delivered — whether via the clean code===0 path OR the
-                    // error_max_turns salvage path — iff createdTicketId is set. Record
-                    // 'success' for any delivered ticket so success-scoped averages and
-                    // failureRate are not skewed by salvaged runs (LOW-13). Genuine
-                    // failures (no ticket) stay 'failed'.
-                    status: createdTicketId !== null ? 'success' : 'failed',
-                    started_at: turnStartedAt,
-                    finished_at: new Date().toISOString(),
-                    total_cost_usd_estimated: estimated,
-                    ...normalised,
-                    duration_ms: normalised.duration_ms ?? wallMs,
-                });
-                broadcast({ type: 'spending.invalidated', projectId });
-            }
-            catch (err) {
-                console.error('[project-router] generate-spec recordInvocation failed:', err);
-            }
+                },
+            },
         });
+        res.status(202).json({ requestId });
     });
     // POST /:projectId/tickets/save-as-draft — Persist an in-progress Explore session as a draft ticket
     router.post('/:projectId/tickets/save-as-draft', (req, res) => {
@@ -848,6 +617,11 @@ function registerTicketsRoutes(deps) {
                 .filter((c) => c.length > 0)
             : [];
         const priority = (0, ticket_store_1.isValidPriority)(body.priority) ? body.priority : 'medium';
+        const draftNonGoals = body.nonGoals === undefined ? null : (0, non_goals_1.validateNonGoals)(body.nonGoals);
+        if (draftNonGoals && !draftNonGoals.ok) {
+            res.status(400).json({ error: draftNonGoals.error });
+            return;
+        }
         // Optional assignee/prerequisites/metadata (same normalization as the
         // PATCH /tickets/:id route) so an MCP commit_draft is a true one-shot
         // insert — no follow-up update call needed for these fields.
@@ -858,7 +632,12 @@ function registerTicketsRoutes(deps) {
             ? body.prerequisites.filter((p) => typeof p === 'number')
             : [];
         const hasMetadata = typeof body.metadata === 'object' && body.metadata !== null;
-        const metadata = hasMetadata ? body.metadata : {};
+        const regressionCheck = (0, ticket_store_1.normalizeRegressionOfMetadata)(hasMetadata ? body.metadata : {});
+        if (!regressionCheck.ok) {
+            res.status(400).json({ error: regressionCheck.error });
+            return;
+        }
+        const metadata = hasMetadata ? regressionCheck.metadata : {};
         // A supplied conversationId must reference a REAL chat conversation in this
         // project (an Explore row in chat_conversations). Agent/desktop conversation
         // ids are NOT valid origins — stamping one would corrupt the ticket's origin
@@ -895,6 +674,13 @@ function registerTicketsRoutes(deps) {
         if (bodyShortSummary === null) {
             bodyShortSummary = (0, project_router_helpers_1.deriveFallbackShortSummary)(rawTitle, descriptionForStore);
         }
+        // Non-goals (3.2): an explicit `nonGoals` list wins; otherwise a draft's
+        // `## Out of Scope` section moves into the field. Either way the section
+        // leaves the description so the ticket shows it once, under it.
+        const outOfScope = (0, non_goals_1.extractOutOfScopeSection)(descriptionForStore);
+        const nonGoalsForStore = draftNonGoals?.ok ? draftNonGoals.nonGoals : outOfScope.nonGoals;
+        if (draftNonGoals?.ok || outOfScope.nonGoals.length > 0)
+            descriptionForStore = outOfScope.description;
         try {
             const filePath = ticketPath(req);
             const now = new Date().toISOString();
@@ -930,6 +716,8 @@ function registerTicketsRoutes(deps) {
                     flipTarget.priority = priority;
                     flipTarget.title = rawTitle;
                     flipTarget.description = descriptionForStore;
+                    if (nonGoalsForStore.length > 0 || draftNonGoals?.ok)
+                        flipTarget.nonGoals = nonGoalsForStore;
                     if (labels.length > 0)
                         flipTarget.labels = labels;
                     // PATCH-route semantics: apply only when the field was supplied;
@@ -939,8 +727,11 @@ function registerTicketsRoutes(deps) {
                         flipTarget.assignee = assignee;
                     if (hasPrerequisites)
                         flipTarget.prerequisites = prerequisites;
-                    if (hasMetadata)
+                    if (hasMetadata) {
                         flipTarget.metadata = { ...flipTarget.metadata, ...metadata };
+                        if (regressionCheck.clear)
+                            delete flipTarget.metadata.regressionOf;
+                    }
                     flipTarget.updated_at = now;
                     // Preserve prior short_summary on flip when the model/body omits one;
                     // overwrite only when a non-null value is provided.
@@ -984,6 +775,7 @@ function registerTicketsRoutes(deps) {
                     parent_epic_id: null,
                     execution_order: null,
                     short_summary: bodyShortSummary,
+                    ...(nonGoalsForStore.length ? { nonGoals: nonGoalsForStore } : {}),
                     created_at: now,
                     updated_at: now,
                     created_by: 'sr-explore-spec',
@@ -1236,6 +1028,41 @@ function registerTicketsRoutes(deps) {
             res.status(500).json({ error: 'Failed to create ticket' });
         }
     });
+    // POST /:projectId/tickets/:id/triage — Recalculate the spec triage
+    // (launch-triage). Forced: runs even when the inputs hash is unchanged. The
+    // record is stored in metadata.triage and announced as ticket_updated.
+    router.post('/:projectId/tickets/:id/triage', async (req, res) => {
+        const ticketId = String(req.params.id ?? '');
+        if (!/^\d+$/.test(ticketId)) {
+            res.status(400).json({ error: 'Invalid ticket ID' });
+            return;
+        }
+        const service = ctx(req).specTriage;
+        if (!service) {
+            res.status(503).json({ error: 'triage_unavailable' });
+            return;
+        }
+        try {
+            const outcome = await service.triageNow(Number(ticketId), { force: true });
+            if (outcome.kind === 'not_found') {
+                res.status(404).json({ error: 'Ticket not found' });
+                return;
+            }
+            if (outcome.kind === 'not_applicable') {
+                res.status(409).json({ error: 'triage_not_applicable', reason: outcome.reason });
+                return;
+            }
+            if (outcome.kind === 'stored' || outcome.kind === 'unchanged') {
+                res.json({ triage: outcome.triage });
+                return;
+            }
+            res.status(503).json({ error: 'triage_unavailable' });
+        }
+        catch (err) {
+            console.error('[project-router] ticket triage error:', err);
+            res.status(500).json({ error: 'Failed to triage ticket' });
+        }
+    });
     // POST /:projectId/tickets/:id/contract-refine — Manually re-fire refine
     router.post('/:projectId/tickets/:id/contract-refine', async (req, res) => {
         const ticketId = Number.parseInt(String(req.params.id ?? ''), 10);
@@ -1478,11 +1305,22 @@ function registerTicketsRoutes(deps) {
     });
     // POST /:projectId/tickets — Create new ticket
     router.post('/:projectId/tickets', (req, res) => {
-        const { title, description, status, priority, labels, assignee, prerequisites, metadata, source } = req.body ?? {};
+        const { title, description, status, priority, labels, assignee, prerequisites, metadata: rawMetadata, source, nonGoals: rawNonGoals } = req.body ?? {};
         if (!title || typeof title !== 'string' || !title.trim()) {
             res.status(400).json({ error: 'title is required' });
             return;
         }
+        const createNonGoals = rawNonGoals === undefined ? null : (0, non_goals_1.validateNonGoals)(rawNonGoals);
+        if (createNonGoals && !createNonGoals.ok) {
+            res.status(400).json({ error: createNonGoals.error });
+            return;
+        }
+        const createRegression = (0, ticket_store_1.normalizeRegressionOfMetadata)(typeof rawMetadata === 'object' && rawMetadata !== null ? rawMetadata : {});
+        if (!createRegression.ok) {
+            res.status(400).json({ error: createRegression.error });
+            return;
+        }
+        const metadata = typeof rawMetadata === 'object' && rawMetadata !== null ? createRegression.metadata : undefined;
         if (status !== undefined && !(0, ticket_store_1.isValidStatus)(status)) {
             res.status(400).json({ error: 'status must be one of: draft, todo, in_progress, on_review, done, cancelled' });
             return;
@@ -1517,6 +1355,7 @@ function registerTicketsRoutes(deps) {
                     parent_epic_id: null,
                     execution_order: null,
                     short_summary: null,
+                    ...(createNonGoals?.ok && createNonGoals.nonGoals.length ? { nonGoals: createNonGoals.nonGoals } : {}),
                     created_at: now,
                     updated_at: now,
                     created_by: source === 'mcp' ? 'mcp' : 'hub', // 'hub' = legacy on-disk wire value (tickets.json, shared with specrails-core) — do not rename
@@ -1575,6 +1414,8 @@ function registerTicketsRoutes(deps) {
         }
         res.status(409).json({ error: 'addendum_applied', detail: 'an applied addendum is history; reopen it or add a new one' });
     };
+    // GET /:projectId/tickets/:ticketId/timeline and /handoff — the spec lifecycle projection and its export.
+    (0, timeline_http_1.registerSpecTimelineRoutes)(router, { ctx, ticketPath });
     // GET /:projectId/tickets/:id/addenda — list a spec's addenda
     router.get('/:projectId/tickets/:id/addenda', (req, res) => {
         const ticketId = addendaTicketId(req, res);
@@ -1765,11 +1606,22 @@ function registerTicketsRoutes(deps) {
             res.status(400).json({ error: 'Invalid ticket ID' });
             return;
         }
-        const { title, description, status, priority, labels, assignee, prerequisites, metadata, acceptanceCriteria, short_summary } = req.body ?? {};
+        const { title, description, status, priority, labels, assignee, prerequisites, metadata: rawMetadata, acceptanceCriteria, short_summary, nonGoals: rawNonGoals } = req.body ?? {};
+        const patchNonGoals = rawNonGoals === undefined ? null : (0, non_goals_1.validateNonGoals)(rawNonGoals);
+        if (patchNonGoals && !patchNonGoals.ok) {
+            res.status(400).json({ error: patchNonGoals.error });
+            return;
+        }
         if (status !== undefined && !(0, ticket_store_1.isValidStatus)(status)) {
             res.status(400).json({ error: 'status must be one of: draft, todo, in_progress, on_review, done, cancelled' });
             return;
         }
+        const patchRegression = (0, ticket_store_1.normalizeRegressionOfMetadata)(typeof rawMetadata === 'object' && rawMetadata !== null ? rawMetadata : {});
+        if (!patchRegression.ok) {
+            res.status(400).json({ error: patchRegression.error });
+            return;
+        }
+        const metadata = typeof rawMetadata === 'object' && rawMetadata !== null ? patchRegression.metadata : rawMetadata;
         if (priority !== undefined && priority !== null && !(0, ticket_store_1.isValidPriority)(priority)) {
             res.status(400).json({ error: 'priority must be one of: critical, high, medium, low' });
             return;
@@ -1812,6 +1664,13 @@ function registerTicketsRoutes(deps) {
                 }
                 if (status !== undefined)
                     ticket.status = status;
+                // Non-goals (3.2): local-only (never a Jira write-back); [] / null clear.
+                if (patchNonGoals?.ok) {
+                    if (patchNonGoals.nonGoals.length)
+                        ticket.nonGoals = patchNonGoals.nonGoals;
+                    else
+                        delete ticket.nonGoals;
+                }
                 if (priority !== undefined)
                     ticket.priority = nextPriority;
                 if (labels !== undefined && Array.isArray(labels))
@@ -1822,6 +1681,8 @@ function registerTicketsRoutes(deps) {
                     ticket.prerequisites = prerequisites.filter((p) => typeof p === 'number');
                 if (metadata !== undefined && typeof metadata === 'object' && metadata !== null) {
                     ticket.metadata = { ...ticket.metadata, ...metadata };
+                    if (patchRegression.clear)
+                        delete ticket.metadata.regressionOf;
                 }
                 // Short summary: explicit non-empty overwrites; explicit null clears;
                 // omitted leaves the existing value untouched (preserves prior summary
@@ -1862,8 +1723,11 @@ function registerTicketsRoutes(deps) {
                     changes.priority = u.priority ?? null;
                 if (labels !== undefined)
                     changes.labels = u.labels;
+                // A label-only edit is undoable for a few seconds in the UI: hold its Jira
+                // write past that window so an undone change never reaches Jira.
+                const labelsOnly = Object.keys(changes).length === 1 && changes.labels !== undefined;
                 if (Object.keys(changes).length > 0)
-                    jiraSyncManager?.onSpecEdited(Number(ticketId), changes);
+                    jiraSyncManager?.onSpecEdited(Number(ticketId), changes, labelsOnly ? { holdMs: UNDO_WINDOW_HOLD_MS } : {});
             }
             catch (e) {
                 console.error('[project-router] jira write-back enqueue failed:', e);
@@ -2000,7 +1864,7 @@ function registerTicketsRoutes(deps) {
         // spawnAiCli reroutes multi-line argv values through stdin on Windows.
         console.log(`[project-router] ai-edit spawn: ${binary} (cwd=${project.path}, requestId=${requestId})`);
         const child = (0, cli_prompt_1.spawnAiCli)(binary, args, {
-            env: (0, runtime_1.buildProviderEnv)(adapter, aiEditOptions),
+            env: (0, runtime_1.buildProviderEnv)(adapter, aiEditOptions, (0, project_env_1.projectAgentSourceEnv)(ctx(req).db, (0, runtime_1.providerEnvAllowlist)(adapter))),
             stdio: ['ignore', 'pipe', 'pipe'],
             cwd: project.path,
         });
@@ -2123,6 +1987,11 @@ function registerTicketsRoutes(deps) {
         res.json({ ok: true });
     });
     // DELETE /:projectId/tickets/:id — Delete ticket
+    // DELETE /:projectId/tickets/:id — soft delete: the spec moves to "Recently
+    // deleted" (restorable for 30 days). Attachments, its Explore draft
+    // conversation and the Jira link stay untouched until the entry is purged or
+    // deleted permanently, so Undo is lossless and Jira never sees a transient
+    // delete (a spec delete has never written to Jira).
     router.delete('/:projectId/tickets/:id', (req, res) => {
         const ticketId = req.params.id;
         if (!/^\d+$/.test(ticketId)) {
@@ -2130,76 +1999,26 @@ function registerTicketsRoutes(deps) {
             return;
         }
         try {
-            const filePath = ticketPath(req);
-            let found = false;
-            let orphanedConversationId = null;
-            const orphanedChildren = [];
-            const numericId = Number(ticketId);
-            const store = (0, ticket_store_1.mutateStore)(filePath, (s) => {
-                const t = s.tickets[ticketId];
-                if (!t)
-                    return;
-                // If this is a draft and no other ticket references the same
-                // origin_conversation_id, mark it for cascade delete.
-                if (t.status === 'draft' && t.origin_conversation_id) {
-                    const otherRefs = Object.values(s.tickets).some((other) => other.id !== t.id && other.origin_conversation_id === t.origin_conversation_id);
-                    if (!otherRefs)
-                        orphanedConversationId = t.origin_conversation_id;
-                }
-                // SMASH: when deleting an épica, orphan its children (set
-                // parent_epic_id/execution_order to null) rather than cascade-delete.
-                if (t.is_epic) {
-                    const now = new Date().toISOString();
-                    for (const childId of Object.keys(s.tickets)) {
-                        const child = s.tickets[childId];
-                        if (child.parent_epic_id === numericId) {
-                            child.parent_epic_id = null;
-                            child.execution_order = null;
-                            child.updated_at = now;
-                            orphanedChildren.push(child);
-                        }
-                    }
-                }
-                delete s.tickets[ticketId];
-                found = true;
-            });
-            if (!found) {
+            const result = (0, ticket_trash_1.softDeleteTicket)(ticketPath(req), Number(ticketId));
+            if (!result) {
                 res.status(404).json({ error: 'Ticket not found' });
                 return;
             }
-            const { broadcast, ticketWatcher, db, chatManager } = ctx(req);
-            ticketWatcher.notifyDesktopWrite(store.revision);
-            // Cascade-delete attachments for this ticket
-            attachment_manager_1.attachmentManager.deleteAll(ctx(req).project.slug, ticketId).catch((e) => {
-                console.error('[project-router] attachment cascade delete failed:', e);
-            });
-            // Cascade-delete the orphaned Explore conversation, if any.
-            if (orphanedConversationId) {
-                try {
-                    const conv = (0, db_1.getConversation)(db, orphanedConversationId);
-                    if (conv && conv.kind === 'explore') {
-                        (0, db_1.deleteConversation)(db, orphanedConversationId);
-                        chatManager?.forgetSpecDraft(orphanedConversationId);
-                        chatManager?.forgetExploreLifecycle(orphanedConversationId);
-                    }
-                }
-                catch (err) {
-                    console.error('[project-router] orphan conversation cleanup failed:', err);
-                }
-            }
+            const { broadcast, ticketWatcher, project } = ctx(req);
+            ticketWatcher.notifyDesktopWrite(result.revision);
             // Broadcast ticket_updated for each orphaned child so observers see them
             // as regular tickets (no longer attached to the deleted épica).
-            for (const child of orphanedChildren) {
+            for (const child of result.orphanedChildren) {
                 broadcast({
                     type: 'ticket_updated',
                     ticket: child,
-                    projectId: ctx(req).project.id,
+                    projectId: project.id,
                     timestamp: new Date().toISOString(),
                 });
             }
-            const msg = { type: 'ticket_deleted', ticketId: Number(ticketId), projectId: ctx(req).project.id, timestamp: new Date().toISOString() };
+            const msg = { type: 'ticket_deleted', ticketId: Number(ticketId), projectId: project.id, timestamp: new Date().toISOString() };
             broadcast(msg);
-            res.json({ ok: true, revision: store.revision });
+            res.json({ ok: true, revision: result.revision, restorable: true });
         }
         catch (err) {
             console.error('[project-router] ticket delete error:', err);