specrails-desktop 2.64.2 → 2.65.0

package/server/dist/jira/jira-clarifications.js

@@ -0,0 +1,146 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CLARIFICATION_REPLY_WINDOW_MS = void 0;
+exports.clarificationsDigest = clarificationsDigest;
+exports.clarificationsCommentMarker = clarificationsCommentMarker;
+exports.clarificationThreadKind = clarificationThreadKind;
+exports.buildClarificationsComment = buildClarificationsComment;
+exports.selectClarificationReplies = selectClarificationReplies;
+exports.clarificationAddendumInput = clarificationAddendumInput;
+exports.insertClarificationThread = insertClarificationThread;
+exports.listOpenClarificationThreads = listOpenClarificationThreads;
+exports.importedCommentIds = importedCommentIds;
+exports.recordImportedReplies = recordImportedReplies;
+// Architect clarifications on Jira (feedback-2026-10 task 3.2).
+//
+// When a run pauses with the architect's questions, or proceeds on stated
+// assumptions (Core `architectClarifications: 1`, `clarifications.json`), and
+// the project enabled `jiraPostClarifications`, Desktop posts them as ONE
+// comment on each linked issue through the durable outbox (idempotency key
+// per run, ticket and record). A human reply posted after that comment is
+// imported once as a spec addendum of kind `clarification`, so the next launch
+// of the spec carries the answer. Scope is deliberately narrow: only replies
+// that follow a Specrails clarifications comment are imported; no other Jira
+// thread is read.
+//
+// This file holds the pure text/selection rules and the thread table access.
+const node_crypto_1 = require("node:crypto");
+const jira_adf_1 = require("./jira-adf");
+/** Replies are imported for this long after the comment was posted. */
+exports.CLARIFICATION_REPLY_WINDOW_MS = 14 * 24 * 60 * 60 * 1000;
+const REPLY_BODY_CAP = 8000;
+/** Stable digest of what the comment says (a later different pause posts again). */
+function clarificationsDigest(record) {
+    const content = record.status === 'awaiting-answers'
+        ? record.blocking.map((item) => item.question)
+        : [...record.assumptions, ...record.clarifications.map((item) => `${item.question}=${item.default ?? ''}`)];
+    return (0, node_crypto_1.createHash)('sha256').update(JSON.stringify([record.status, content])).digest('hex').slice(0, 16);
+}
+function clarificationsCommentMarker(runId, ticketId, digest) {
+    return `[specrails:clarifications=${runId}:ticket=${ticketId}:${digest}]`;
+}
+function clarificationThreadKind(record) {
+    return record.status === 'awaiting-answers' ? 'questions' : 'assumptions';
+}
+/** The comment body (plain text; the ADF layer renders paragraphs). */
+function buildClarificationsComment(record) {
+    const lines = [];
+    if (record.status === 'awaiting-answers') {
+        const questions = record.blocking.length ? record.blocking : record.clarifications.filter((item) => item.impact === 'high');
+        lines.push('Specrails paused this spec before planning: the architect needs an answer to continue.');
+        lines.push('');
+        questions.forEach((item, index) => lines.push(`${index + 1}. ${item.question}`));
+        const others = record.clarifications.filter((item) => !questions.includes(item));
+        if (others.length) {
+            lines.push('');
+            lines.push('It would otherwise assume:');
+            for (const item of others)
+                lines.push(`- ${item.question} → ${item.default ?? 'no safe default'} (${item.impact} impact)`);
+        }
+        lines.push('');
+        lines.push('Reply to this comment to answer: Specrails records the reply on the spec for its next run. You can also answer in the app.');
+    }
+    else {
+        lines.push('Specrails planned this spec on the following assumptions. Reply to this comment if any of them is wrong; the reply is recorded on the spec for its next run.');
+        lines.push('');
+        const assumptions = record.assumptions.length
+            ? record.assumptions
+            : record.clarifications.map((item) => `${item.question} → ${item.default ?? 'no safe default'}`);
+        for (const line of assumptions)
+            lines.push(`- ${line.replace(/^\s*[-*]\s+/, '')}`);
+    }
+    return lines.join('\n');
+}
+/** True when the comment was written by Specrails (any marker). */
+function isSpecrailsComment(comment) {
+    if (comment.properties?.some((property) => property.key === jira_adf_1.SPECRAILS_COMMENT_PROP_KEY))
+        return true;
+    return /\[specrails:[a-z-]+=/.test((0, jira_adf_1.adfToText)(comment.body));
+}
+/**
+ * Human replies after the thread's marker comment (Jira lists comments oldest
+ * first), skipping Specrails' own comments and the already-imported ids.
+ * Empty when the marker comment is not (yet) on the issue.
+ */
+function selectClarificationReplies(comments, marker, imported) {
+    const anchor = comments.findIndex((comment) => (0, jira_adf_1.commentHasMarker)(comment, marker));
+    if (anchor < 0)
+        return [];
+    const out = [];
+    for (const comment of comments.slice(anchor + 1)) {
+        if (!comment.id || imported.has(comment.id) || isSpecrailsComment(comment))
+            continue;
+        const text = (0, jira_adf_1.adfToText)(comment.body).trim();
+        if (!text)
+            continue;
+        out.push({
+            commentId: comment.id,
+            author: typeof comment.author?.displayName === 'string' && comment.author.displayName.trim() ? comment.author.displayName.trim().slice(0, 120) : null,
+            created: typeof comment.created === 'string' ? comment.created : null,
+            text: text.slice(0, REPLY_BODY_CAP),
+        });
+    }
+    return out;
+}
+/** The addendum a reply becomes (kind `clarification`, validated by the addenda core). */
+function clarificationAddendumInput(reply, jiraKey, kind) {
+    const where = jiraKey ? `Jira ${jiraKey}` : 'Jira';
+    const title = `${kind === 'questions' ? 'Answer' : 'Correction'} from ${where}${reply.author ? ` (${reply.author})` : ''}`.slice(0, 200);
+    const body = [
+        kind === 'questions'
+            ? 'Answer to the architect\'s clarification questions, posted on the linked Jira issue. Treat it as authoritative for the questions it answers.'
+            : 'Reply to the assumptions the architect planned on, posted on the linked Jira issue. Where it contradicts an assumption, the reply wins.',
+        '',
+        reply.text,
+    ].join('\n');
+    return { kind: 'clarification', title, body };
+}
+function insertClarificationThread(db, row) {
+    const result = db.prepare(`
+    INSERT OR IGNORE INTO jira_clarification_threads (id, run_id, ticket_id, jira_issue_id, kind, marker, state, imported_comment_ids, created_at, updated_at)
+    VALUES (?, ?, ?, ?, ?, ?, 'open', '[]', ?, ?)
+  `).run(row.id, row.run_id, row.ticket_id, row.jira_issue_id, row.kind, row.marker, row.created_at, row.created_at);
+    return result.changes > 0;
+}
+/** Threads still collecting replies; older ones are closed as a side effect. */
+function listOpenClarificationThreads(db, now = Date.now()) {
+    const cutoff = new Date(now - exports.CLARIFICATION_REPLY_WINDOW_MS).toISOString();
+    db.prepare(`UPDATE jira_clarification_threads SET state = 'closed', updated_at = ? WHERE state != 'closed' AND created_at < ?`).run(new Date(now).toISOString(), cutoff);
+    return db.prepare(`SELECT * FROM jira_clarification_threads WHERE state != 'closed' ORDER BY created_at LIMIT 50`).all();
+}
+function importedCommentIds(row) {
+    try {
+        const parsed = JSON.parse(row.imported_comment_ids);
+        return new Set(Array.isArray(parsed) ? parsed.filter((id) => typeof id === 'string') : []);
+    }
+    catch {
+        return new Set();
+    }
+}
+function recordImportedReplies(db, threadId, ids, now = new Date().toISOString()) {
+    const row = db.prepare(`SELECT imported_comment_ids FROM jira_clarification_threads WHERE id = ?`).get(threadId);
+    if (!row)
+        return;
+    const merged = [...new Set([...importedCommentIds(row), ...ids])].slice(-200);
+    db.prepare(`UPDATE jira_clarification_threads SET imported_comment_ids = ?, state = 'answered', updated_at = ? WHERE id = ?`).run(JSON.stringify(merged), now, threadId);
+}

package/server/dist/jira/jira-client.js

@@ -207,7 +207,14 @@ class JiraClient {
             fields.labels = args.labels;
         if (args.priority)
             fields.priority = { name: args.priority };
-        return this.request('POST', '/issue', { fields });
+        const body = { fields };
+        if (args.properties && args.properties.length > 0)
+            body.properties = args.properties;
+        return this.request('POST', '/issue', body);
+    }
+    /** GET /issue/{id}/properties/{key} — read one entity property (404 = absent). */
+    getIssueProperty(issueIdOrKey, propertyKey) {
+        return this.request('GET', `/issue/${encodeURIComponent(issueIdOrKey)}/properties/${encodeURIComponent(propertyKey)}`);
     }
     /**
      * PUT /issue/{id} — update editable fields (summary/description/labels/

package/server/dist/jira/jira-db.js

@@ -27,6 +27,7 @@ exports.updateLinkStatusCategory = updateLinkStatusCategory;
 exports.setLinkState = setLinkState;
 exports.tombstoneLink = tombstoneLink;
 exports.enqueueOutbox = enqueueOutbox;
+exports.enqueueHeldUpdate = enqueueHeldUpdate;
 exports.enqueueMany = enqueueMany;
 exports.claimDrainable = claimDrainable;
 exports.markOutboxDone = markOutboxDone;
@@ -266,6 +267,46 @@ function enqueueOutbox(db, input) {
     const existing = db.prepare('SELECT id FROM jira_outbox WHERE idempotency_key = ?').get(input.idempotencyKey);
     return existing?.id ?? 0;
 }
+/**
+ * Enqueue a field `update` that waits `holdMs` before it may drain (the undo
+ * window of a label change). While an earlier held update for the same issue is
+ * still waiting, it is folded into this one and marked `superseded`, so an edit
+ * undone inside the window collapses to the value Jira already has — Jira never
+ * sees the transient change. Idempotent on `idempotencyKey`.
+ */
+function enqueueHeldUpdate(db, input) {
+    const now = input.now ?? new Date();
+    const nowIso = now.toISOString();
+    const dueIso = new Date(now.getTime() + input.holdMs).toISOString();
+    const tx = db.transaction(() => {
+        const existing = db.prepare('SELECT id FROM jira_outbox WHERE idempotency_key = ?').get(input.idempotencyKey);
+        if (existing)
+            return existing.id;
+        const held = db
+            .prepare(`SELECT id, payload FROM jira_outbox
+          WHERE jira_issue_id = ? AND op_type = 'update' AND state = 'pending'
+            AND next_attempt_at IS NOT NULL AND next_attempt_at > ?
+          ORDER BY id ASC`)
+            .all(input.jiraIssueId, nowIso);
+        let merged = {};
+        for (const row of held) {
+            try {
+                const payload = JSON.parse(row.payload);
+                merged = { ...merged, ...(payload.fields ?? {}) };
+            }
+            catch { /* an unreadable held payload carries nothing to merge */ }
+            db.prepare("UPDATE jira_outbox SET state = 'superseded', next_attempt_at = NULL, updated_at = ? WHERE id = ?").run(nowIso, row.id);
+        }
+        merged = { ...merged, ...input.fields };
+        const info = db
+            .prepare(`INSERT INTO jira_outbox
+          (jira_issue_id, op_type, idempotency_key, payload, state, attempts, next_attempt_at, created_at, updated_at)
+         VALUES (?, 'update', ?, ?, 'pending', 0, ?, ?, ?)`)
+            .run(input.jiraIssueId, input.idempotencyKey, JSON.stringify({ jiraIssueId: input.jiraIssueId, fields: merged }), dueIso, nowIso, nowIso);
+        return Number(info.lastInsertRowid);
+    });
+    return tx();
+}
 /** Enqueue several ops atomically (one SQLite transaction). */
 function enqueueMany(db, ops) {
     const tx = db.transaction((items) => {

package/server/dist/jira/jira-sync-manager.js

@@ -11,6 +11,7 @@
 // and stays completely inert until the project configures a Jira connection.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.JiraSyncManager = void 0;
+exports.pendingCreateIssueId = pendingCreateIssueId;
 exports.backoffMs = backoffMs;
 exports.formatJqlDate = formatJqlDate;
 exports.buildCompletionComment = buildCompletionComment;
@@ -28,6 +29,10 @@ const jira_issue_fields_1 = require("./jira-issue-fields");
 const jira_status_resolver_1 = require("./jira-status-resolver");
 const jira_db_1 = require("./jira-db");
 const workspace_resolution_1 = require("../workspace-resolution");
+const db_1 = require("../db");
+const spec_addenda_1 = require("../modules/specs/runtime/spec-addenda");
+const run_records_1 = require("../modules/delivery/runtime/run-records");
+const jira_clarifications_1 = require("./jira-clarifications");
 const POLL_INTERVAL_MS = 60_000;
 const DRAIN_INTERVAL_MS = 10_000;
 const POLL_OVERLAP_MS = 2 * 60_000;
@@ -380,22 +385,94 @@ class JiraSyncManager {
         const client = this.buildClient();
         if (!client)
             return { ok: false, error: 'no jira credentials' };
-        const file = (0, ticket_store_1.resolveTicketStoragePath)(this._artifactRoot());
-        const ticket = (0, ticket_store_1.readStore)(file).tickets[String(localId)];
-        if (!ticket)
-            return { ok: false, error: 'ticket not found' };
-        const created = await client.createIssue({
-            projectKey: conn.jiraProjectKey,
-            issueType: 'Task',
-            summary: ticket.title,
-            description: ticket.description || undefined,
-            labels: ticket.labels,
-        });
+        const created = await this.createLinkedIssue(client, conn, localId);
         if (!created.ok) {
+            if (created.reason === 'ticket_not_found')
+                return { ok: false, error: 'ticket not found' };
+            if (created.reason === 'flow_held')
+                return { ok: false, error: 'the spec is still in Flow; it reaches Jira when its Flow -> Spec rail settles' };
             if (created.code === 'auth')
                 this.onAuth401();
             return { ok: false, error: created.error || 'jira issue create failed' };
         }
+        return { ok: true, jiraKey: created.jiraKey };
+    }
+    /**
+     * Durable form of `promoteTicketToJira` (feedback-2026-10 Flow settlement):
+     * enqueue a `create` outbox op for a LOCAL ticket. The drainer creates the
+     * issue, links it to the same local id and flips the ticket to
+     * `source:'jira'` exactly as promote does, with the outbox's retry/backoff
+     * and restart replay. Idempotent: the same `idempotencyKey` never enqueues
+     * twice, and an already-linked ticket completes as a no-op at drain time.
+     * Never throws.
+     */
+    enqueuePromote(localTicketId, idempotencyKey) {
+        try {
+            if (!this.isActive())
+                return 'inactive';
+            const existing = (0, jira_db_1.getLinkByLocalId)(this.db, localTicketId);
+            if (existing && !existing.tombstoned)
+                return 'already_linked';
+            (0, jira_db_1.enqueueOutbox)(this.db, {
+                jiraIssueId: pendingCreateIssueId(localTicketId),
+                opType: 'create',
+                idempotencyKey,
+                payload: { localTicketId },
+            });
+            this.broadcastOutboxState();
+            void this.drainOnce().catch(() => undefined);
+            return 'enqueued';
+        }
+        catch (err) {
+            console.error('[jira-sync] enqueuePromote failed:', err);
+            return 'failed';
+        }
+    }
+    /**
+     * Create the Jira issue for an existing LOCAL ticket, link it to the SAME
+     * local id and flip the cached ticket to `source:'jira'` with its key/url.
+     * Shared by `promoteTicketToJira` and the outbox `create` op. Callers own
+     * the already-linked check and error policy (auth pause, retry/dead).
+     */
+    async createLinkedIssue(client, conn, localId, recovery) {
+        const file = (0, ticket_store_1.resolveTicketStoragePath)(this._artifactRoot());
+        const ticket = (0, ticket_store_1.readStore)(file).tickets[String(localId)];
+        if (!ticket)
+            return { ok: false, reason: 'ticket_not_found' };
+        // Flow placeholder specs never reach Jira while the Flow is active or paused.
+        if ((0, ticket_store_1.isFlowHeldTicket)(ticket))
+            return { ok: false, reason: 'flow_held' };
+        const marker = (0, jira_adf_1.issueCreateMarker)(this.projectId, localId);
+        let created;
+        let recovered = false;
+        // A retried durable create may follow an attempt whose issue WAS created
+        // but whose response was lost. Recover that issue by its invisible
+        // creation marker before creating; an unconfirmed search retries later
+        // rather than risking a duplicate.
+        const existing = recovery ? await this.findIssueByCreateMarker(client, conn, marker, recovery.since) : null;
+        if (existing && !existing.ok)
+            return { ok: false, reason: 'jira', ...existing.error };
+        if (existing?.ok && existing.issue) {
+            created = { ok: true, data: existing.issue };
+            recovered = true;
+        }
+        else {
+            const input = {
+                projectKey: conn.jiraProjectKey,
+                issueType: 'Task',
+                summary: ticket.title,
+                description: ticket.description || undefined,
+                labels: ticket.labels,
+            };
+            created = await client.createIssue({ ...input, properties: [{ key: jira_adf_1.SPECRAILS_ISSUE_CREATE_PROP_KEY, value: { marker } }] });
+            // Compatibility: an instance that rejects create-time entity properties
+            // still gets the issue (without the recovery marker), as before.
+            if (!created.ok && created.code === 'validation')
+                created = await client.createIssue(input);
+        }
+        if (!created.ok) {
+            return { ok: false, reason: 'jira', code: created.code, status: created.status, retryAfterMs: created.retryAfterMs, error: created.error };
+        }
         (0, jira_db_1.insertLinkWithId)(this.db, {
             localId,
             jiraIssueId: created.data.id,
@@ -418,7 +495,35 @@ class JiraSyncManager {
         if (updated) {
             this.broadcast({ type: 'ticket_updated', ticket: updated, projectId: this.projectId, timestamp: updated.updated_at });
         }
-        return { ok: true, jiraKey: created.data.key };
+        return { ok: true, jiraKey: created.data.key, ...(recovered ? { recovered: true } : {}) };
+    }
+    /**
+     * Find an issue this manager created for `marker`: recent issues the
+     * connected account created in the project, confirmed by the invisible
+     * creation property (works on Cloud and DC without property indexing).
+     */
+    async findIssueByCreateMarker(client, conn, marker, since) {
+        const sinceMs = since ? Date.parse(since.includes('T') ? since : `${since.replace(' ', 'T')}Z`) : NaN;
+        const minutes = Number.isFinite(sinceMs) ? Math.max(1, Math.ceil((Date.now() - sinceMs) / 60_000) + CREATE_RECOVERY_MARGIN_MIN) : CREATE_RECOVERY_DEFAULT_MIN;
+        const res = await client.searchJql({
+            jql: `project = "${conn.jiraProjectKey}" AND creator = currentUser() AND created >= "-${minutes}m" ORDER BY created DESC`,
+            fields: ['summary'],
+            maxResults: CREATE_RECOVERY_MAX_CANDIDATES,
+        });
+        if (!res.ok)
+            return { ok: false, error: { code: res.code, status: res.status, retryAfterMs: res.retryAfterMs, error: res.error } };
+        for (const issue of res.data.issues ?? []) {
+            const prop = await client.getIssueProperty(issue.id, jira_adf_1.SPECRAILS_ISSUE_CREATE_PROP_KEY);
+            if (prop.ok) {
+                const value = prop.data.value;
+                if (value?.marker === marker)
+                    return { ok: true, issue: { id: issue.id, key: issue.key } };
+            }
+            else if (prop.code !== 'not_found') {
+                return { ok: false, error: { code: prop.code, status: prop.status, retryAfterMs: prop.retryAfterMs, error: prop.error } };
+            }
+        }
+        return { ok: true, issue: null };
     }
     // ─── Inbound poll ──────────────────────────────────────────────────────────
     /** The set of local ids with a pending/inflight outbox op (status is frozen). */
@@ -515,8 +620,103 @@ class JiraSyncManager {
             (0, jira_db_1.setHighWater)(this.db, this.projectId, maxUpdated);
         if (totalUpserted > 0)
             this.broadcast({ type: 'jira.synced', projectId: this.projectId, upserted: totalUpserted, at: Date.now() });
+        await this.importClarificationReplies(client).catch((err) => console.error('[jira-sync] clarification replies failed:', err));
         return { upserted: totalUpserted };
     }
+    // ─── Architect clarifications (feedback-2026-10 task 3.2) ─────────────────
+    /**
+     * A run's architect clarifications (Core `clarifications.json`): when the
+     * project enabled `jiraPostClarifications`, enqueue ONE comment per linked
+     * ticket with the questions the run paused on, or the assumptions it
+     * proceeded with. Idempotent per run, ticket and record content (a second
+     * pause with different questions posts again). Never throws.
+     */
+    onRunClarifications(runId, ticketIds, record) {
+        try {
+            if (!this.isActive() || !(0, run_records_1.hasClarificationContent)(record))
+                return 0;
+            if (!(0, db_1.getProjectSettings)(this.db).jiraPostClarifications)
+                return 0;
+            const digest = (0, jira_clarifications_1.clarificationsDigest)(record);
+            const kind = (0, jira_clarifications_1.clarificationThreadKind)(record);
+            const text = (0, jira_clarifications_1.buildClarificationsComment)(record);
+            const now = new Date().toISOString();
+            const ops = [];
+            for (const localId of new Set(ticketIds)) {
+                const link = (0, jira_db_1.getLinkByLocalId)(this.db, localId);
+                if (!link || link.tombstoned)
+                    continue;
+                const marker = (0, jira_clarifications_1.clarificationsCommentMarker)(runId, localId, digest);
+                const fresh = (0, jira_clarifications_1.insertClarificationThread)(this.db, { id: `${runId}:${localId}:${digest}`, run_id: runId, ticket_id: localId, jira_issue_id: link.jiraIssueId, kind, marker, created_at: now });
+                if (!fresh)
+                    continue;
+                ops.push({
+                    jiraIssueId: link.jiraIssueId,
+                    opType: 'comment',
+                    idempotencyKey: `${runId}:${localId}:comment:clarifications:${digest}`,
+                    payload: { jiraIssueId: link.jiraIssueId, text, marker },
+                });
+            }
+            if (ops.length === 0)
+                return 0;
+            (0, jira_db_1.enqueueMany)(this.db, ops);
+            this.broadcastOutboxState();
+            void this.drainOnce().catch(() => undefined);
+            return ops.length;
+        }
+        catch (err) {
+            console.error('[jira-sync] onRunClarifications failed:', err);
+            return 0;
+        }
+    }
+    /** Import human replies to posted clarifications as `clarification` addenda. */
+    async importClarificationReplies(client) {
+        let threads;
+        try {
+            threads = (0, jira_clarifications_1.listOpenClarificationThreads)(this.db);
+        }
+        catch {
+            return 0;
+        }
+        let imported = 0;
+        for (const thread of threads) {
+            const res = await client.getComments(thread.jira_issue_id);
+            if (!res.ok)
+                continue;
+            const replies = (0, jira_clarifications_1.selectClarificationReplies)(res.data.comments, thread.marker, (0, jira_clarifications_1.importedCommentIds)(thread));
+            if (replies.length === 0)
+                continue;
+            const jiraKey = (0, jira_db_1.getLinkByLocalId)(this.db, thread.ticket_id)?.jiraKey ?? null;
+            try {
+                const file = (0, ticket_store_1.resolveTicketStoragePath)(this._artifactRoot());
+                let touched = false;
+                const store = (0, ticket_store_1.mutateStore)(file, (s) => {
+                    const ticket = s.tickets[String(thread.ticket_id)];
+                    if (!ticket)
+                        return;
+                    for (const reply of replies) {
+                        const input = (0, spec_addenda_1.parseSpecAddendumInput)((0, jira_clarifications_1.clarificationAddendumInput)(reply, jiraKey, thread.kind));
+                        (0, spec_addenda_1.appendSpecAddendum)(ticket, (0, spec_addenda_1.buildSpecAddendum)(input, { createdBy: 'jira' }));
+                        touched = true;
+                    }
+                });
+                // Recorded even when the ticket is gone, so a deleted spec is not retried forever.
+                (0, jira_clarifications_1.recordImportedReplies)(this.db, thread.id, replies.map((reply) => reply.commentId));
+                if (!touched)
+                    continue;
+                imported += replies.length;
+                this.notifyLocalWrite(store.revision);
+                const ticket = store.tickets[String(thread.ticket_id)];
+                if (ticket)
+                    this.broadcast({ type: 'ticket_updated', ticket: ticket, projectId: this.projectId, timestamp: ticket.updated_at });
+            }
+            catch (err) {
+                // A full addenda list (or a validation error) keeps the thread for a later poll.
+                console.error('[jira-sync] clarification reply import failed:', err);
+            }
+        }
+        return imported;
+    }
     // ─── Outbound write-back hooks ─────────────────────────────────────────────
     /**
      * Called from the rail-launch handler. For each Jira-linked ticket, enqueue an
@@ -599,7 +799,7 @@ class JiraSyncManager {
      * pending the id is frozen, so the inbound poll won't revert the local edit.
      * Status is intentionally NOT written here (Jira status needs a transition).
      */
-    onSpecEdited(localId, changes) {
+    onSpecEdited(localId, changes, opts = {}) {
         if (!this.isActive())
             return;
         const link = (0, jira_db_1.getLinkByLocalId)(this.db, localId);
@@ -608,18 +808,7 @@ class JiraSyncManager {
         const conn = (0, jira_db_1.getConnection)(this.db, this.projectId);
         if (!conn)
             return;
-        const fields = {};
-        if (typeof changes.title === 'string' && changes.title.trim())
-            fields.summary = changes.title.trim().slice(0, 250);
-        if (typeof changes.description === 'string')
-            fields.description = (0, jira_adf_1.bodyForDeployment)(changes.description, conn.deployment);
-        if (changes.labels !== undefined)
-            fields.labels = (changes.labels ?? []).filter((l) => typeof l === 'string');
-        if (changes.priority) {
-            const name = PRIORITY_TO_JIRA[changes.priority];
-            if (name)
-                fields.priority = { name };
-        }
+        const fields = this.specUpdateFields(changes, conn.deployment);
         if (Object.keys(fields).length === 0)
             return;
         // A random component makes two saves of the same ticket inside one wall-clock
@@ -627,6 +816,20 @@ class JiraSyncManager {
         // INSERT OR IGNORE silently drops the second edit while the local cache shows
         // it (local↔Jira divergence). randomUUID() guarantees uniqueness per op.
         const nonce = `${Date.now().toString(36)}:${(0, node_crypto_1.randomUUID)()}`;
+        if (opts.holdMs && opts.holdMs > 0) {
+            // Undo window: the write waits, and an edit undone inside the window
+            // collapses with it so Jira never sees the transient value.
+            (0, jira_db_1.enqueueHeldUpdate)(this.db, {
+                jiraIssueId: link.jiraIssueId,
+                idempotencyKey: `update:${localId}:${nonce}`,
+                fields,
+                holdMs: opts.holdMs,
+            });
+            this.broadcastOutboxState();
+            const timer = setTimeout(() => { void this.drainOnce().catch(() => undefined); }, opts.holdMs + 250);
+            timer.unref?.();
+            return;
+        }
         (0, jira_db_1.enqueueMany)(this.db, [
             {
                 jiraIssueId: link.jiraIssueId,
@@ -638,6 +841,58 @@ class JiraSyncManager {
         this.broadcastOutboxState();
         void this.drainOnce().catch(() => undefined);
     }
+    /** The editable Jira fields of a spec edit (summary, description, labels, priority). */
+    specUpdateFields(changes, deployment) {
+        const fields = {};
+        if (typeof changes.title === 'string' && changes.title.trim())
+            fields.summary = changes.title.trim().slice(0, 250);
+        if (typeof changes.description === 'string')
+            fields.description = (0, jira_adf_1.bodyForDeployment)(changes.description, deployment);
+        if (changes.labels !== undefined)
+            fields.labels = (changes.labels ?? []).filter((l) => typeof l === 'string');
+        if (changes.priority) {
+            const name = PRIORITY_TO_JIRA[changes.priority];
+            if (name)
+                fields.priority = { name };
+        }
+        return fields;
+    }
+    /**
+     * Durable, IDEMPOTENT push of a linked spec's current summary, description,
+     * labels and priority to its existing issue (Flow settlement of a spec that
+     * already had an issue: the rewritten spec updates THAT issue, never a new
+     * one). The same `idempotencyKey` never enqueues twice; the pending op
+     * freezes the id so the inbound poll cannot revert the rewrite. Never throws.
+     */
+    enqueueSpecUpdate(localTicketId, idempotencyKey) {
+        try {
+            if (!this.isActive())
+                return 'inactive';
+            const link = (0, jira_db_1.getLinkByLocalId)(this.db, localTicketId);
+            if (!link || link.tombstoned)
+                return 'not_linked';
+            const conn = (0, jira_db_1.getConnection)(this.db, this.projectId);
+            if (!conn)
+                return 'inactive';
+            const ticket = (0, ticket_store_1.readStore)((0, ticket_store_1.resolveTicketStoragePath)(this._artifactRoot())).tickets[String(localTicketId)];
+            if (!ticket)
+                return 'failed';
+            const fields = this.specUpdateFields({ title: ticket.title, description: ticket.description ?? '', labels: ticket.labels ?? [], priority: ticket.priority }, conn.deployment);
+            (0, jira_db_1.enqueueMany)(this.db, [{
+                    jiraIssueId: link.jiraIssueId,
+                    opType: 'update',
+                    idempotencyKey,
+                    payload: { jiraIssueId: link.jiraIssueId, fields },
+                }]);
+            this.broadcastOutboxState();
+            void this.drainOnce().catch(() => undefined);
+            return 'enqueued';
+        }
+        catch (err) {
+            console.error('[jira-sync] enqueueSpecUpdate failed:', err);
+            return 'failed';
+        }
+    }
     /**
      * Called from project-registry's onJobFinished AFTER the local cache mutation.
      * Enqueues the Jira status transition + completion comment per linked ticket.
@@ -1025,6 +1280,9 @@ class JiraSyncManager {
             else if (op.opType === 'update') {
                 await this.executeUpdate(client, op, payload);
             }
+            else if (op.opType === 'create') {
+                await this.executeCreate(client, conn, op, payload);
+            }
             else {
                 (0, jira_db_1.markOutboxDead)(this.db, op.id, `unsupported op type ${op.opType}`);
             }
@@ -1033,6 +1291,39 @@ class JiraSyncManager {
             this.retryOrDead(op, err instanceof Error ? err.message : String(err));
         }
     }
+    async executeCreate(client, conn, op, payload) {
+        const localId = Number(payload?.localTicketId);
+        if (!Number.isInteger(localId) || localId <= 0) {
+            (0, jira_db_1.markOutboxDead)(this.db, op.id, 'invalid create payload: localTicketId required');
+            return;
+        }
+        // Idempotency-first: a ticket linked since enqueue (promote, a replay that
+        // crashed after linking) completes without creating a second issue.
+        const existing = (0, jira_db_1.getLinkByLocalId)(this.db, localId);
+        if (existing && !existing.tombstoned) {
+            (0, jira_db_1.markOutboxDone)(this.db, op.id);
+            return;
+        }
+        // attempts > 0 ⇒ an earlier attempt may have created the issue.
+        const created = await this.createLinkedIssue(client, conn, localId, op.attempts > 0 ? { since: op.createdAt } : undefined);
+        if (created.ok) {
+            (0, jira_db_1.markOutboxDone)(this.db, op.id);
+            return;
+        }
+        if (created.reason === 'ticket_not_found') {
+            (0, jira_db_1.markOutboxDead)(this.db, op.id, 'local ticket not found');
+            return;
+        }
+        if (created.reason === 'flow_held') {
+            // Settlement marks the Flow delivered before it publishes; retry until then.
+            if (op.attempts + 1 >= MAX_OUTBOX_ATTEMPTS)
+                (0, jira_db_1.markOutboxDead)(this.db, op.id, 'the spec is still in Flow');
+            else
+                (0, jira_db_1.markOutboxRetry)(this.db, op.id, new Date(Date.now() + backoffMs(op.attempts)).toISOString(), 'the spec is still in Flow');
+            return;
+        }
+        this.handleHardError(op, created.code, created.status, created.retryAfterMs, created.error);
+    }
     async executeUpdate(client, op, payload) {
         let res = await client.updateIssue(payload.jiraIssueId, payload.fields);
         // The priority NAME may not match the instance's scheme. Don't let that lose
@@ -1380,6 +1671,18 @@ class JiraOpError extends Error {
     }
 }
 // ─── Pure helpers ──────────────────────────────────────────────────────────────
+/**
+ * Outbox serialisation key for a `create` op. The issue does not exist yet, so
+ * the op is keyed by its local ticket (`local:<id>`), which also keeps two
+ * creates for the same ticket FIFO-ordered. It never matches a real issue id.
+ */
+/** Durable-create recovery search window: since the op was enqueued, plus margin. */
+const CREATE_RECOVERY_MARGIN_MIN = 10;
+const CREATE_RECOVERY_DEFAULT_MIN = 7 * 24 * 60;
+const CREATE_RECOVERY_MAX_CANDIDATES = 50;
+function pendingCreateIssueId(localTicketId) {
+    return `local:${localTicketId}`;
+}
 function backoffMs(attempts) {
     const base = Math.min(30_000, 2000 * 2 ** attempts);
     const jitter = (attempts * 137) % 1000; // deterministic jitter (no Math.random)