@specship/specship-win32-arm64 0.19.1 → 0.21.0

package/lib/dist/activation/cheatsheet.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Session cheat-sheet (CHEATSHEET-DOC).
+ *
+ * SpecShip's agent-facing guidance ships in the MCP `initialize` response, so
+ * Claude always knows how to drive the tools. The human driving the session
+ * has no equivalent. This module is the human's map — a short, static
+ * capability cheat-sheet printed at session start as a `SessionStart` hook
+ * `systemMessage` (the command is `specship cheatsheet`, installed by the
+ * installer and shipped in the plugin's `hooks/hooks.json`).
+ *
+ * Distinct from `starter-prompt` (a dynamic, self-silencing first-run flow
+ * prompt) and from the dashboard's improvement tips (`claude_tip_state`) — see
+ * the spec's scope note. Noise is bounded by the hook matcher (startup only)
+ * and the `SPECSHIP_NO_CHEATSHEET` opt-out below, not by this module.
+ */
+/**
+ * The cheat-sheet rendered to the user. Names only user-facing commands, tools,
+ * and env vars — no internal file paths, symbol names, or benchmark figures
+ * (REQ-CHEAT-002.A3), so it reads as a product map rather than engineering
+ * notes.
+ */
+export declare const CHEATSHEET_TEXT: string;
+/**
+ * Build the `SessionStart`-hook payload the `specship cheatsheet` command
+ * prints. Returns `{ systemMessage }` (user-visible only — never
+ * `additionalContext`, REQ-CHEAT-001.A2), or `null` when the user has opted
+ * out via `SPECSHIP_NO_CHEATSHEET` (REQ-CHEAT-004.A1). An unset or empty
+ * variable prints normally (REQ-CHEAT-004.A2).
+ */
+export declare function buildCheatsheetPayload(env?: NodeJS.ProcessEnv): {
+    systemMessage: string;
+} | null;
+//# sourceMappingURL=cheatsheet.d.ts.map

package/lib/dist/activation/cheatsheet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cheatsheet.d.ts","sourceRoot":"","sources":["../../src/activation/cheatsheet.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,eAAe,QAqBhB,CAAC;AAEb;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC;IAAE,aAAa,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAGlC"}

package/lib/dist/activation/cheatsheet.js

@@ -0,0 +1,60 @@
+"use strict";
+/**
+ * Session cheat-sheet (CHEATSHEET-DOC).
+ *
+ * SpecShip's agent-facing guidance ships in the MCP `initialize` response, so
+ * Claude always knows how to drive the tools. The human driving the session
+ * has no equivalent. This module is the human's map — a short, static
+ * capability cheat-sheet printed at session start as a `SessionStart` hook
+ * `systemMessage` (the command is `specship cheatsheet`, installed by the
+ * installer and shipped in the plugin's `hooks/hooks.json`).
+ *
+ * Distinct from `starter-prompt` (a dynamic, self-silencing first-run flow
+ * prompt) and from the dashboard's improvement tips (`claude_tip_state`) — see
+ * the spec's scope note. Noise is bounded by the hook matcher (startup only)
+ * and the `SPECSHIP_NO_CHEATSHEET` opt-out below, not by this module.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CHEATSHEET_TEXT = void 0;
+exports.buildCheatsheetPayload = buildCheatsheetPayload;
+/**
+ * The cheat-sheet rendered to the user. Names only user-facing commands, tools,
+ * and env vars — no internal file paths, symbol names, or benchmark figures
+ * (REQ-CHEAT-002.A3), so it reads as a product map rather than engineering
+ * notes.
+ */
+exports.CHEATSHEET_TEXT = [
+    '📦 SpecShip — code intelligence + spec-driven flow over the indexed graph',
+    '',
+    'The four doors (slash commands):',
+    '• /specship:explore  — reads door. "how does X work / reach Y", blast radius.',
+    '• /specship:spec     — intent door. list · new · fast · design · implement · review.',
+    '• /specship:check    — gate & health door (drift queue, fix, relink, health).',
+    '• /specship:learn    — lessons door. crystallize what worked into a skill proposal.',
+    '',
+    'Explore before you Read/Grep:',
+    '• specship_explore is PRIMARY — one call returns verbatim source grouped by file.',
+    '• Flow: name both ends (e.g. "mutateElement renderScene") to trace the call path.',
+    '• Locate → specship_search · impact → specship_impact · callers/callees too.',
+    '',
+    'JIRA: "my JIRA issues", "pick PROJ-123", "start it", "publish REQ-X to JIRA".',
+    'Drift & health: /specship:check · check drifted · check fix <ID> · check health.',
+    'Lessons & memory: /specship:learn; auto-memory has four types (user · feedback ·',
+    '  project · reference) that persist across sessions.',
+    'Verify: the gate runs the spec→test→verify chain; specship_link_verify closes a link.',
+    '',
+    'Silence this with SPECSHIP_NO_CHEATSHEET=1. specship_status shows index freshness.',
+].join('\n');
+/**
+ * Build the `SessionStart`-hook payload the `specship cheatsheet` command
+ * prints. Returns `{ systemMessage }` (user-visible only — never
+ * `additionalContext`, REQ-CHEAT-001.A2), or `null` when the user has opted
+ * out via `SPECSHIP_NO_CHEATSHEET` (REQ-CHEAT-004.A1). An unset or empty
+ * variable prints normally (REQ-CHEAT-004.A2).
+ */
+function buildCheatsheetPayload(env = process.env) {
+    if (env.SPECSHIP_NO_CHEATSHEET)
+        return null;
+    return { systemMessage: exports.CHEATSHEET_TEXT };
+}
+//# sourceMappingURL=cheatsheet.js.map

package/lib/dist/activation/cheatsheet.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cheatsheet.js","sourceRoot":"","sources":["../../src/activation/cheatsheet.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;GAcG;;;AAsCH,wDAKC;AAzCD;;;;;GAKG;AACU,QAAA,eAAe,GAAG;IAC7B,2EAA2E;IAC3E,EAAE;IACF,kCAAkC;IAClC,+EAA+E;IAC/E,sFAAsF;IACtF,+EAA+E;IAC/E,qFAAqF;IACrF,EAAE;IACF,+BAA+B;IAC/B,mFAAmF;IACnF,mFAAmF;IACnF,8EAA8E;IAC9E,EAAE;IACF,+EAA+E;IAC/E,kFAAkF;IAClF,kFAAkF;IAClF,sDAAsD;IACtD,uFAAuF;IACvF,EAAE;IACF,oFAAoF;CACrF,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAEb;;;;;;GAMG;AACH,SAAgB,sBAAsB,CACpC,MAAyB,OAAO,CAAC,GAAG;IAEpC,IAAI,GAAG,CAAC,sBAAsB;QAAE,OAAO,IAAI,CAAC;IAC5C,OAAO,EAAE,aAAa,EAAE,uBAAe,EAAE,CAAC;AAC5C,CAAC"}

package/lib/dist/bin/specship.js

@@ -807,6 +807,41 @@ function main() {
                     `re-assert with specship_link_assert, or run /specship:check fix ${t.specId}`);
             }
         };
+        // JIRA push (REQ-JIRAPUB-006): a genuine drift transition on a JIRA-backed
+        // spec is commented onto its issue — best-effort, transition events only
+        // (so an ongoing drift never repeats a comment), never blocks the sync.
+        const pushJiraDriftComments = async (cg, result) => {
+            const transitions = result.driftedTransitions ?? [];
+            if (transitions.length === 0)
+                return;
+            try {
+                const { loadJiraConfig, resolveJiraCredentials } = await Promise.resolve().then(() => __importStar(require('../jira/config')));
+                if (!loadJiraConfig())
+                    return; // not configured → no JIRA calls at all
+                const { readSpecJiraKey } = await Promise.resolve().then(() => __importStar(require('../jira/spec-writer')));
+                const { JiraClient } = await Promise.resolve().then(() => __importStar(require('../jira/client')));
+                const { commentDriftTransitionsOnJira } = await Promise.resolve().then(() => __importStar(require('../jira/publish')));
+                const notes = await commentDriftTransitionsOnJira({
+                    transitions,
+                    specPathFor: (specId) => {
+                        const rootId = specId.replace(/\.A\d+$/, '');
+                        const spec = cg.getSpecQueries().getSpecById(rootId);
+                        if (!spec)
+                            return null;
+                        return path.isAbsolute(spec.sourcePath)
+                            ? spec.sourcePath
+                            : path.join(projectPath, spec.sourcePath);
+                    },
+                    readKey: readSpecJiraKey,
+                    makeClient: () => new JiraClient(resolveJiraCredentials()),
+                });
+                for (const note of notes)
+                    console.log(`JIRA: ${note}`);
+            }
+            catch {
+                /* a JIRA fault must never fail a sync */
+            }
+        };
         // One-line drift-queue summary, only when non-empty (REQ-DRIFT-PUSH-002).
         const pushDriftSummary = (cg) => {
             if (!options.driftSummary)
@@ -828,6 +863,7 @@ function main() {
             if (options.quiet) {
                 const result = await cg.sync();
                 pushDriftNotices(result);
+                await pushJiraDriftComments(cg, result);
                 pushDriftSummary(cg);
                 cg.destroy();
                 return;
@@ -856,6 +892,7 @@ function main() {
                 clack.log.info(`${details.join(', ')} ${(0, glyphs_1.getGlyphs)().dash} ${formatNumber(result.nodesUpdated)} nodes in ${formatDuration(result.durationMs)}`);
             }
             pushDriftNotices(result);
+            await pushJiraDriftComments(cg, result);
             pushDriftSummary(cg);
             clack.outro('Done');
             cg.destroy();
@@ -1356,6 +1393,195 @@ function main() {
             process.exit(1);
         }
     });
+    /**
+     * specship memory — capture lessons to memory and review/manage stored items
+     * (MEMLESSON-DOC). `capture` turns a stated mistake into a human-gated
+     * memory_rule proposal (REQ-MEMLESSON-001); nothing is written until it is
+     * applied (dashboard Improvements / `specship reflect`).
+     */
+    const memory = program
+        .command('memory')
+        .description('Capture lessons to memory and review/manage stored memory items.');
+    memory
+        .command('capture')
+        .description('Capture a lesson/anti-pattern as a human-gated memory rule (lesson text on stdin).')
+        .requiredOption('--title <title>', 'short title for the lesson')
+        .option('--target <target>', 'where apply would write it: "memory" (portable ~/.claude note, default) or "claude-md" (project CLAUDE.md)', 'memory')
+        .option('--path <projectRoot>', 'project root (default: cwd)')
+        .option('-j, --json', 'output the created proposal as JSON')
+        .action(async (options) => {
+        const projectPath = resolveProjectPath(options.path);
+        const target = options.target === 'claude-md' ? 'claude-md' : 'memory';
+        try {
+            if (!(0, directory_1.isInitialized)(projectPath)) {
+                error(`SpecShip not initialized in ${projectPath}`);
+                process.exit(1);
+            }
+            // Lesson content on stdin so a multi-line "mistake + rule to avoid it"
+            // survives shell quoting (mirrors `specship reflect --capture`).
+            const chunks = [];
+            for await (const c of process.stdin)
+                chunks.push(c);
+            const content = Buffer.concat(chunks).toString('utf-8').trim();
+            if (!content) {
+                error('memory capture expects the lesson on stdin (pipe or heredoc): the mistake + the rule to avoid repeating it.');
+                process.exit(1);
+            }
+            const { SpecShip } = await loadSpecShip();
+            const cg = await SpecShip.open(projectPath);
+            const p = cg.reflectCaptureLesson({ title: options.title, content, target });
+            if (options.json) {
+                // eslint-disable-next-line no-console
+                console.log(JSON.stringify(p, null, 2));
+            }
+            else {
+                info(`Captured lesson as proposal ${p.contentHash.slice(0, 12)} (${p.state}): ${p.title}`);
+                info(`Target: ${p.targetKind === 'claude_md' ? 'project CLAUDE.md' : 'portable ~/.claude memory note'} — nothing written yet.`);
+                info('Review + apply from the dashboard Improvements page (preview-diff → confirm), or `specship reflect`.');
+            }
+            cg.destroy();
+        }
+        catch (err) {
+            error(`memory capture failed: ${err instanceof Error ? err.message : String(err)}`);
+            process.exit(1);
+        }
+    });
+    // Body text of a memory_rule proposal's payload (the note or the CLAUDE.md block).
+    function memoryRuleBody(p) {
+        if (p.payload.kind === 'memory_note')
+            return p.payload.note ?? '';
+        if (p.payload.kind === 'claude_md')
+            return p.payload.block ?? '';
+        return '';
+    }
+    memory
+        .command('list')
+        .description('List the memory rules SpecShip has applied (reflect-managed store).')
+        .option('--path <projectRoot>', 'project root (default: cwd)')
+        .option('-j, --json', 'output as JSON')
+        .action(async (options) => {
+        const projectPath = resolveProjectPath(options.path);
+        try {
+            if (!(0, directory_1.isInitialized)(projectPath)) {
+                error(`SpecShip not initialized in ${projectPath}`);
+                process.exit(1);
+            }
+            const { SpecShip } = await loadSpecShip();
+            const cg = await SpecShip.open(projectPath);
+            const items = cg.reflectList('applied').filter((p) => p.type === 'memory_rule');
+            if (options.json) {
+                // eslint-disable-next-line no-console
+                console.log(JSON.stringify(items, null, 2));
+                cg.destroy();
+                return;
+            }
+            if (items.length === 0) {
+                info('No memory items yet — capture one with `specship memory capture`.');
+                cg.destroy();
+                return;
+            }
+            for (const p of items) {
+                const target = p.targetKind === 'claude_md' ? 'CLAUDE.md' : 'memory note';
+                success(`${p.contentHash.slice(0, 12)}  [${target}]  ${p.title}`);
+            }
+            cg.destroy();
+        }
+        catch (err) {
+            error(`memory list failed: ${err instanceof Error ? err.message : String(err)}`);
+            process.exit(1);
+        }
+    });
+    memory
+        .command('remove <id>')
+        .description('Remove a SpecShip-managed memory rule by id (previewed; pass --yes to write).')
+        .option('--yes', 'actually remove it (without this it is a dry-run preview)')
+        .option('--path <projectRoot>', 'project root (default: cwd)')
+        .action(async (id, options) => {
+        const projectPath = resolveProjectPath(options.path);
+        try {
+            if (!(0, directory_1.isInitialized)(projectPath)) {
+                error(`SpecShip not initialized in ${projectPath}`);
+                process.exit(1);
+            }
+            const { SpecShip } = await loadSpecShip();
+            const cg = await SpecShip.open(projectPath);
+            const p = cg.reflectGet(id) ??
+                cg.reflectList().find((x) => x.type === 'memory_rule' && x.contentHash.startsWith(id));
+            if (!p || p.type !== 'memory_rule') {
+                error(`No SpecShip-managed memory rule found for "${id}".`);
+                cg.destroy();
+                process.exit(1);
+            }
+            info(`Will remove from ${p.targetPath}:`);
+            // eslint-disable-next-line no-console
+            console.log(memoryRuleBody(p));
+            if (!options.yes) {
+                info('Dry-run — nothing changed. Re-run with --yes to remove.');
+                cg.destroy();
+                return;
+            }
+            const outcome = cg.reflectUndo(p.contentHash);
+            if (outcome === 'undone')
+                success(`Removed ${p.contentHash.slice(0, 12)}: ${p.title}`);
+            else
+                info(`Nothing on disk to remove for ${p.contentHash.slice(0, 12)} (already gone).`);
+            cg.destroy();
+        }
+        catch (err) {
+            error(`memory remove failed: ${err instanceof Error ? err.message : String(err)}`);
+            process.exit(1);
+        }
+    });
+    memory
+        .command('edit <id>')
+        .description("Replace a memory rule's body with new content on stdin (previewed; pass --yes to write).")
+        .option('--yes', 'actually apply the update (without this it is a dry-run before→after preview)')
+        .option('--path <projectRoot>', 'project root (default: cwd)')
+        .action(async (id, options) => {
+        const projectPath = resolveProjectPath(options.path);
+        try {
+            if (!(0, directory_1.isInitialized)(projectPath)) {
+                error(`SpecShip not initialized in ${projectPath}`);
+                process.exit(1);
+            }
+            const chunks = [];
+            for await (const c of process.stdin)
+                chunks.push(c);
+            const content = Buffer.concat(chunks).toString('utf-8').trim();
+            if (!content) {
+                error('memory edit expects the new body on stdin (pipe or heredoc).');
+                process.exit(1);
+            }
+            const { SpecShip } = await loadSpecShip();
+            const cg = await SpecShip.open(projectPath);
+            const old = cg.reflectGet(id) ??
+                cg.reflectList().find((x) => x.type === 'memory_rule' && x.contentHash.startsWith(id));
+            if (!old || old.type !== 'memory_rule') {
+                error(`No SpecShip-managed memory rule found for "${id}".`);
+                cg.destroy();
+                process.exit(1);
+            }
+            const title = old.title.replace(/^Lesson:\s*/, '');
+            const target = old.targetKind === 'claude_md' ? 'claude-md' : 'memory';
+            const next = cg.reflectCaptureLesson({ title, content, target });
+            info(`Update ${old.contentHash.slice(0, 12)} — before → after:`);
+            // eslint-disable-next-line no-console
+            console.log('--- before ---\n' + memoryRuleBody(old) + '\n--- after ---\n' + memoryRuleBody(next));
+            if (!options.yes) {
+                info('Dry-run — nothing changed. Re-run with --yes to apply the update.');
+                cg.destroy();
+                return;
+            }
+            cg.reflectUndo(old.contentHash);
+            const outcome = cg.reflectApply(next.contentHash);
+            success(`Updated: removed ${old.contentHash.slice(0, 12)}, applied ${next.contentHash.slice(0, 12)} (${outcome}).`);
+            cg.destroy();
+        }
+        catch (err) {
+            error(`memory edit failed: ${err instanceof Error ? err.message : String(err)}`);
+            process.exit(1);
+        }
+    });
     /**
      * specship maintainability
      *
@@ -2363,6 +2589,23 @@ function main() {
             // Index unreadable / FTS5 missing → print nothing (REQ-ACTIVATION-004.A1).
         }
     });
+    /**
+     * specship cheatsheet — print the user-facing session cheat-sheet
+     * (CHEATSHEET-DOC). Installed as a startup-only `SessionStart` hook; emits a
+     * `{ systemMessage }` payload the harness renders to the human. Silent when
+     * `SPECSHIP_NO_CHEATSHEET` is set (REQ-CHEAT-004). Distinct from
+     * `starter-prompt` (dynamic first-run flow) — this is the static capability map.
+     */
+    program
+        .command('cheatsheet')
+        .description('Print the SpecShip session cheat-sheet (used by the SessionStart hook).')
+        .action(async () => {
+        const { buildCheatsheetPayload } = await Promise.resolve().then(() => __importStar(require('../activation/cheatsheet')));
+        const payload = buildCheatsheetPayload();
+        if (payload)
+            process.stdout.write(JSON.stringify(payload) + '\n');
+        process.exit(0);
+    });
     /**
      * specship spec-nudge  (internal — installed as a UserPromptSubmit hook)
      *
@@ -3098,6 +3341,7 @@ function main() {
         .option('--deployment <kind>', 'Deployment kind: "cloud" or "datacenter" (inferred if omitted)')
         .option('--ca-cert <pem>', 'Path to a PEM CA bundle for a corporate/self-signed certificate (Data Center)')
         .option('--insecure-tls', 'Disable TLS certificate verification for JIRA requests only (last resort)')
+        .option('--project <key>', 'Default project for spec→JIRA publishing (interactive setup offers your accessible projects)')
         .action(async (opts) => {
         const { saveJiraConfig, resolveJiraCredentials, inferDeployment, jiraConfigPath, JiraClient, JiraAuthError, } = await Promise.resolve().then(() => __importStar(require('../jira')));
         const clack = await importESM('@clack/prompts');
@@ -3197,7 +3441,40 @@ function main() {
             // Probe the connection so the user knows immediately whether it works.
             const client = new JiraClient(resolveJiraCredentials());
             const result = await client.testConnection();
-            clack.outro(`Connected as ${result.displayName ?? 'unknown user'}.`);
+            clack.log.success(`Connected as ${result.displayName ?? 'unknown user'}.`);
+            // Publish project (REQ-JIRAPUB-009.A3): an explicit --project saves
+            // directly; otherwise the interactive path offers the projects this
+            // account can actually browse, so the user picks instead of typing.
+            if (opts.project) {
+                config.project = opts.project.trim().toUpperCase();
+                saveJiraConfig(config);
+                clack.log.success(`Default publish project: ${config.project}.`);
+            }
+            else if (!flagged) {
+                try {
+                    const projects = await client.listProjects();
+                    if (projects.length > 0) {
+                        const NONE = '__none__';
+                        const chosen = await clack.select({
+                            message: 'Default project for spec→JIRA publishing (specship_jira_publish)',
+                            options: [
+                                ...projects.map((p) => ({ value: p.key, label: `${p.key} — ${p.name}` })),
+                                { value: NONE, label: 'Skip — choose per publish' },
+                            ],
+                        });
+                        if (!cancelled(chosen) && chosen !== NONE) {
+                            config.project = String(chosen);
+                            saveJiraConfig(config);
+                            clack.log.success(`Default publish project: ${config.project}.`);
+                        }
+                    }
+                }
+                catch {
+                    // Listing projects is a convenience — a fault here never fails
+                    // an otherwise-successful configure.
+                }
+            }
+            clack.outro('JIRA is configured.');
         }
         catch (err) {
             // Messages from the jira module are already scrubbed of the secret.
@@ -3219,6 +3496,24 @@ function main() {
             const kind = creds.deployment === 'cloud' ? 'JIRA Cloud' : 'JIRA Data Center';
             // Never print the credential — only the resolved identity.
             success(`Connected to ${kind} as ${result.displayName ?? 'unknown user'}.`);
+            // Validate the configured lifecycle transition names against a live
+            // workflow so a name the workflow can't fire is visible now, not a
+            // silent skip at completion time (REQ-JIRATRANS-002).
+            const { validateConfiguredTransitions } = await Promise.resolve().then(() => __importStar(require('../mcp/jira-tools')));
+            const v = await validateConfiguredTransitions(client, creds.transitions ?? {});
+            if (!v.verified) {
+                info('Configured transitions: could not verify (no accessible issue to sample).');
+            }
+            else {
+                info(`Configured transitions (checked against ${v.sampleKey}; available from its ` +
+                    `current state: ${v.available.join(', ') || 'none'}):`);
+                for (const c of v.checks) {
+                    if (c.found)
+                        info(`  ✓ ${c.role} "${c.configured}"`);
+                    else
+                        warn(`  ✗ ${c.role} "${c.configured}" — not offered from ${v.sampleKey}'s current state`);
+                }
+            }
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
@@ -3227,6 +3522,41 @@ function main() {
             process.exit(1);
         }
     });
+    /**
+     * specship jira transition — move a tracked issue to a target state, or list
+     * the transitions it currently offers (REQ-JIRATRANS-001). Reuses the client's
+     * skip-tolerant transition: a target the workflow doesn't offer is reported
+     * with the available states and nothing is written.
+     */
+    jira
+        .command('transition <key> [state]')
+        .description('Transition a JIRA issue to <state>, or list its available transitions when <state> is omitted (or with --list).')
+        .option('--list', 'list the available transitions instead of applying one')
+        .action(async (key, state, options) => {
+        const { resolveJiraCredentials, JiraClient } = await Promise.resolve().then(() => __importStar(require('../jira')));
+        try {
+            const creds = resolveJiraCredentials();
+            const client = new JiraClient(creds);
+            if (options.list || !state) {
+                const names = (await client.listTransitions(key)).map((t) => t.name);
+                success(names.length
+                    ? `${key} can transition to: ${names.join(', ')}.`
+                    : `${key} has no available transitions from its current state.`);
+                return;
+            }
+            const res = await client.transitionIssue(key, state);
+            if ('transitioned' in res) {
+                success(`Moved ${key} to "${res.transitioned}".`);
+            }
+            else {
+                warn(`Did not transition ${key} — ${res.reason}.`);
+            }
+        }
+        catch (err) {
+            error(`JIRA transition failed: ${err instanceof Error ? err.message : String(err)}`);
+            process.exit(1);
+        }
+    });
     /**
      * specship jira track — read-only tracking view (REQ-JIRA-008). Joins each
      * picked issue's SpecShip work-state (from its workflow run) with its LIVE JIRA
@@ -3247,7 +3577,7 @@ function main() {
         const { handleSpecshipJiraTrack } = await Promise.resolve().then(() => __importStar(require('../mcp/jira-tools')));
         const cg = await SpecShip.open(projectRoot);
         try {
-            const result = await handleSpecshipJiraTrack({ project: options.project }, { specQueries: cg.getSpecQueries() });
+            const result = await handleSpecshipJiraTrack({ project: options.project }, { specQueries: cg.getSpecQueries(), projectRoot });
             const out = result.content.map((c) => c.text).join('\n');
             // eslint-disable-next-line no-console
             console.log(out);
@@ -3258,6 +3588,67 @@ function main() {
             cg.close();
         }
     });
+    /**
+     * specship jira release — stamp a released version onto issues
+     * (REQ-JIRAPUB-007): ensure the project version exists, add it as fixVersion
+     * on each issue, and add one shipped-in comment. Idempotent — a re-run
+     * creates no duplicate version, fixVersion, or comment.
+     */
+    jira
+        .command('release <version>')
+        .description('Set <version> as fixVersion on JIRA issues (creating the project version if missing) with a shipped-in comment.')
+        .option('--keys <keys>', 'comma-separated issue keys (e.g., "PROJ-1,PROJ-2"); default: every published spec\'s jira_issue key')
+        .option('--project <key>', 'JIRA project key the version belongs to (default: the configured publish project)')
+        .option('--path <projectRoot>', 'project root whose specs/ supplies the default keys (default: cwd)')
+        .action(async (version, options) => {
+        const { resolveJiraCredentials, JiraClient } = await Promise.resolve().then(() => __importStar(require('../jira')));
+        const { releaseIssues } = await Promise.resolve().then(() => __importStar(require('../jira/publish')));
+        const { readSpecJiraKey } = await Promise.resolve().then(() => __importStar(require('../jira/spec-writer')));
+        try {
+            const creds = resolveJiraCredentials();
+            const projectKey = options.project ?? creds.project;
+            if (!projectKey) {
+                error('No JIRA project configured. Pass --project, set SPECSHIP_JIRA_PROJECT, or add "project" to your jira config.');
+                process.exit(1);
+            }
+            let keys = (options.keys ?? '')
+                .split(',')
+                .map((k) => k.trim())
+                .filter(Boolean);
+            if (keys.length === 0) {
+                // Default: every spec under <root>/specs with a jira_issue key.
+                const projectRoot = path.resolve(options.path ?? process.cwd());
+                const specsDir = path.join(projectRoot, 'specs');
+                try {
+                    for (const name of fs.readdirSync(specsDir)) {
+                        if (!name.toLowerCase().endsWith('.md'))
+                            continue;
+                        const key = readSpecJiraKey(path.join(specsDir, name));
+                        if (key)
+                            keys.push(key);
+                    }
+                }
+                catch {
+                    /* no specs dir → empty keys, handled below */
+                }
+                keys = [...new Set(keys)];
+            }
+            if (keys.length === 0) {
+                error('No issue keys to release — pass --keys or publish specs first (specship_jira_publish).');
+                process.exit(1);
+            }
+            const client = new JiraClient(creds);
+            const result = await releaseIssues(client, projectKey, version, keys);
+            const stamped = result.issues.filter((i) => i.fixVersionAdded).length;
+            const commented = result.issues.filter((i) => i.commented).length;
+            success(`Version ${version}${result.versionCreated ? ' created' : ' already existed'} in ${projectKey}; ` +
+                `fixVersion added to ${stamped}/${keys.length} issue(s), shipped-in comment added to ${commented}.`);
+        }
+        catch (err) {
+            error(`JIRA release failed: ${err instanceof Error ? err.message : String(err)}`);
+            process.exit(1);
+        }
+    });
     // Parse and run
     program.parse();
 } // end main()