@fission-ai/openspec 1.9.0 → 1.11.0

package/dist/cli/index.d.ts

@@ -20,6 +20,23 @@ export declare function getCommandPath(command: Command): string;
  * non-JSON run, never lost, whereas printing it on a JSON run corrupts stdout.
  */
 export declare function isJsonRun(command: Command): boolean;
+/**
+ * True for the commands that exist to serve shell completions: the user-facing
+ * `openspec completion ...` group and the hidden `__complete` resolver that
+ * generated completion scripts call on every Tab press. Tipping either about
+ * completions is noise, and `__complete` would burn the one-shot tip invisibly.
+ */
+export declare function isCompletionRun(commandPath: string): boolean;
+/**
+ * True when the first-run completions tip must be deferred rather than shown.
+ *
+ * Deferring keeps the tip unconsumed, so it still reaches the user on a later
+ * run that can actually carry it. All three cases are runs nobody would read a
+ * hint from: JSON output, the completion machinery itself, and a stderr that is
+ * not a terminal — pipes and the agent-driven runs that dominate this CLI's
+ * usage would otherwise burn the user's one-shot tip into a log nobody opens.
+ */
+export declare function shouldDeferCompletionTip(command: Command, stderrIsTty: boolean): boolean;
 export { program };
 export declare function runCli(argv?: string[]): void;
 //# sourceMappingURL=index.d.ts.map

package/dist/cli/index.js

@@ -24,8 +24,9 @@ import { registerStoreCommand } from '../commands/store.js';
 import { registerDoctorCommand } from '../commands/doctor.js';
 import { registerContextCommand } from '../commands/context.js';
 import { registerWorksetCommand } from '../commands/workset.js';
-import { statusCommand, instructionsCommand, applyInstructionsCommand, archiveInstructionsCommand, templatesCommand, schemasCommand, newChangeCommand, DEFAULT_SCHEMA, } from '../commands/workflow/index.js';
+import { statusCommand, BATCH_STATUS_FAILURE_PAYLOAD, instructionsCommand, applyInstructionsCommand, archiveInstructionsCommand, templatesCommand, schemasCommand, newChangeCommand, DEFAULT_SCHEMA, } from '../commands/workflow/index.js';
 import { maybeShowTelemetryNotice, trackCommand, shutdown } from '../telemetry/index.js';
+import { maybeShowCompletionTip } from '../core/completion-tip.js';
 import { COMMON_FLAGS } from '../core/completions/shared-flags.js';
 import { isInteractive } from '../utils/interactive.js';
 const STORE_OPTION_DESCRIPTION = COMMON_FLAGS.store.description;
@@ -90,6 +91,27 @@ export function isJsonRun(command) {
     return (command.optsWithGlobals().json === true ||
         command.args.includes('--json'));
 }
+/**
+ * True for the commands that exist to serve shell completions: the user-facing
+ * `openspec completion ...` group and the hidden `__complete` resolver that
+ * generated completion scripts call on every Tab press. Tipping either about
+ * completions is noise, and `__complete` would burn the one-shot tip invisibly.
+ */
+export function isCompletionRun(commandPath) {
+    return commandPath.split(':')[0] === 'completion' || commandPath === '__complete';
+}
+/**
+ * True when the first-run completions tip must be deferred rather than shown.
+ *
+ * Deferring keeps the tip unconsumed, so it still reaches the user on a later
+ * run that can actually carry it. All three cases are runs nobody would read a
+ * hint from: JSON output, the completion machinery itself, and a stderr that is
+ * not a terminal — pipes and the agent-driven runs that dominate this CLI's
+ * usage would otherwise burn the user's one-shot tip into a log nobody opens.
+ */
+export function shouldDeferCompletionTip(command, stderrIsTty) {
+    return isJsonRun(command) || isCompletionRun(getCommandPath(command)) || !stderrIsTty;
+}
 program
     .name('openspec')
     .description('AI-native system for spec-driven development')
@@ -105,16 +127,32 @@ program.hook('preAction', async (thisCommand, actionCommand) => {
     if (opts.color === false) {
         process.env.NO_COLOR = '1';
     }
-    // Show first-run telemetry notice (if not seen). Suppress it whenever the run
-    // asked for JSON so stdout stays a single valid JSON document (see isJsonRun).
+    // Show first-run telemetry notice (if not seen). It's written to stderr, so it
+    // never pollutes stdout — but --json runs still defer it (see isJsonRun) so the
+    // very first invocation stays free of any incidental output on either stream.
     await maybeShowTelemetryNotice({ silent: isJsonRun(actionCommand) });
     // Track command execution (use actionCommand to get the actual subcommand)
     const commandPath = getCommandPath(actionCommand);
     await trackCommand(commandPath, version);
 });
 // Shutdown telemetry after command completes
-program.hook('postAction', async () => {
-    await shutdown();
+program.hook('postAction', async (_thisCommand, actionCommand) => {
+    // Show the first-run shell-completions tip (on stderr, so piped stdout stays
+    // clean). postAction, not preAction: the tip trails the command's own output
+    // instead of pushing an error message or `init`'s setup summary down the
+    // screen. Deferred — not consumed — whenever nobody would read it: JSON runs,
+    // `openspec completion ...`, and a stderr that is not a terminal (agents and
+    // pipes would otherwise silently burn the user's one-shot tip).
+    try {
+        await maybeShowCompletionTip({
+            silent: shouldDeferCompletionTip(actionCommand, Boolean(process.stderr.isTTY)),
+        });
+    }
+    finally {
+        // The flush runs even if the hint throws: parse() is synchronous, so a
+        // rejection here has no catch anywhere above it.
+        await shutdown();
+    }
 });
 const availableToolIds = AI_TOOLS
     .filter((tool) => tool.skillsDir || tool.globalSkillsDir)
@@ -127,6 +165,7 @@ program
     .command('init [path]')
     .description('Initialize OpenSpec in your project')
     .option('--tools <tools>', toolsOptionDescription)
+    .option('--language <language>', 'Write new OpenSpec artifacts in this language')
     .option('--force', 'Auto-cleanup legacy files without prompting')
     .option('--profile <profile>', 'Override global config profile (core or custom)')
     .option('--no-animation', 'Show a static welcome screen instead of the animated one')
@@ -157,6 +196,7 @@ program
         const { InitCommand } = await import('../core/init.js');
         const initCommand = new InitCommand({
             tools: options?.tools,
+            language: options?.language,
             force: options?.force,
             profile: options?.profile,
             animation: options?.animation,
@@ -326,6 +366,7 @@ changeCmd
     .option('--json', 'Output as JSON')
     .option('--deltas-only', 'Show only deltas (JSON only)')
     .option('--requirements-only', 'Alias for --deltas-only (deprecated)')
+    .option('--diff', 'Show per-requirement diffs for delta specs')
     .option('--no-interactive', 'Disable interactive prompts')
     .action(async (changeName, options) => {
     try {
@@ -362,10 +403,12 @@ changeCmd
     .action(async (changeName, options) => {
     try {
         const changeCommand = new ChangeCommand();
+        // validate() already sets process.exitCode, and Node honours it at
+        // natural exit. Calling process.exit() here would skip commander's
+        // postAction hook — the same trap called out for `update` below — which
+        // kills the telemetry flush and the first-run completions tip on what is
+        // a routine outcome, not an error: a change that fails validation.
         await changeCommand.validate(changeName, options);
-        if (typeof process.exitCode === 'number' && process.exitCode !== 0) {
-            process.exit(process.exitCode);
-        }
     }
     catch (error) {
         console.error(`Error: ${error.message}`);
@@ -433,6 +476,7 @@ program
     // change-only flags
     .option('--deltas-only', 'Show only deltas (JSON only, change)')
     .option('--requirements-only', 'Alias for --deltas-only (deprecated, change)')
+    .option('--diff', 'Show per-requirement diffs for delta specs (change)')
     // spec-only flags
     .option('--requirements', 'JSON only: Show only requirements (exclude scenarios)')
     .option('--no-scenarios', 'JSON only: Exclude scenario content')
@@ -535,6 +579,7 @@ program
     .command('status')
     .description('Display artifact completion status for a change')
     .option('--change <id>', 'Change name to show status for')
+    .option('--all', 'Show status for all active changes')
     .option('--schema <name>', 'Schema override (auto-detected from config.yaml)')
     .option('--json', 'Output as JSON')
     .option('--store <id>', STORE_OPTION_DESCRIPTION)
@@ -544,7 +589,13 @@ program
         await statusCommand(options);
     }
     catch (error) {
-        failWithError(error, { enabled: options.json, fallbackCode: 'change_error' });
+        failWithError(error, {
+            enabled: options.json,
+            // The batch null-shape; the single-change failure shape is
+            // pre-existing contract and stays payload-free.
+            payload: options.all ? BATCH_STATUS_FAILURE_PAYLOAD : undefined,
+            fallbackCode: 'change_error',
+        });
         process.exit(1);
     }
 });

package/dist/commands/change.d.ts

@@ -4,19 +4,43 @@ export declare class ChangeCommand {
     private rootPath?;
     constructor(rootPath?: string);
     private getChangesPath;
+    private getSpecsPath;
     /**
      * Show a change proposal.
      * - Text mode: raw markdown passthrough (no filters)
      * - JSON mode: minimal object with deltas; --deltas-only returns same object with filtered deltas
      *   Note: --requirements-only is deprecated alias for --deltas-only
+     * - --diff: per-requirement diffs of the delta specs against the main specs,
+     *   appended in text mode and attached to MODIFIED deltas in JSON mode
      */
     show(changeName?: string, options?: {
         json?: boolean;
         requirementsOnly?: boolean;
         deltasOnly?: boolean;
+        diff?: boolean;
         noInteractive?: boolean;
         rootOutput?: RootOutput;
     }): Promise<void>;
+    /**
+     * Read every delta spec under the change and pair each requirement with its
+     * counterpart in the main spec. Text mode and JSON mode both render from this
+     * one pass, so the two surfaces cannot drift apart.
+     */
+    private collectSpecDiffs;
+    /**
+     * Attach `diff` (or `warning`) to every MODIFIED delta in the JSON payload.
+     * Mutates the deltas array in place.
+     *
+     * The parsed Delta objects carry the requirement body in `description`, not
+     * the header name, so they are matched to parsed blocks by capability and
+     * source order: ChangeParser emits one Delta per MODIFIED block in that order.
+     */
+    private enrichDeltasWithDiffs;
+    /**
+     * Text mode: per-requirement diffs of the delta specs against the main specs.
+     */
+    private showSpecDiffs;
+    private printDiffText;
     /**
      * List active changes.
      * - Text default: IDs only; --long prints minimal details (title, counts)

package/dist/commands/change.js

@@ -1,5 +1,6 @@
 import { promises as fs } from 'fs';
 import path from 'path';
+import chalk from 'chalk';
 import { JsonConverter } from '../core/converters/json-converter.js';
 import { Validator } from '../core/validation/validator.js';
 import { VALIDATION_MESSAGES } from '../core/validation/constants.js';
@@ -8,6 +9,9 @@ import { isInteractive } from '../utils/interactive.js';
 import { getActiveChangeIds } from '../utils/item-discovery.js';
 import { getTaskProgressForChange } from '../utils/task-progress.js';
 import { FileSystemUtils } from '../utils/file-system.js';
+import { discoverSpecFiles } from '../utils/spec-discovery.js';
+import { foldRequirementName, parseDeltaSpec, } from '../core/parsers/requirement-blocks.js';
+import { extractRequirementBlock, diffRequirementBlock, buildRenameMap, } from '../utils/requirement-diff.js';
 /**
  * True only when `target` is definitively absent. An EACCES or I/O failure
  * means existence cannot be determined, so callers fall through to their
@@ -39,11 +43,18 @@ export class ChangeCommand {
     getChangesPath() {
         return path.join(this.rootPath ?? process.cwd(), 'openspec', 'changes');
     }
+    // Main specs resolve against the same root as changes, so `--diff` reads the
+    // selected store's specs rather than whatever sits under the cwd.
+    getSpecsPath() {
+        return path.join(this.rootPath ?? process.cwd(), 'openspec', 'specs');
+    }
     /**
      * Show a change proposal.
      * - Text mode: raw markdown passthrough (no filters)
      * - JSON mode: minimal object with deltas; --deltas-only returns same object with filtered deltas
      *   Note: --requirements-only is deprecated alias for --deltas-only
+     * - --diff: per-requirement diffs of the delta specs against the main specs,
+     *   appended in text mode and attached to MODIFIED deltas in JSON mode
      */
     async show(changeName, options) {
         const changesPath = this.getChangesPath();
@@ -109,6 +120,9 @@ export class ChangeCommand {
             const title = this.extractTitle(contentForTitle, changeName);
             const id = parsed.name;
             const deltas = parsed.deltas || [];
+            if (options.diff) {
+                await this.enrichDeltasWithDiffs(deltas, changeName, changesPath);
+            }
             const output = {
                 id,
                 title,
@@ -122,6 +136,215 @@ export class ChangeCommand {
             FileSystemUtils.assertPathWithin(changeDir, proposalPath);
             const content = await fs.readFile(proposalPath, 'utf-8');
             console.log(content);
+            if (options?.diff) {
+                await this.showSpecDiffs(changeName, changesPath);
+            }
+        }
+    }
+    /**
+     * Read every delta spec under the change and pair each requirement with its
+     * counterpart in the main spec. Text mode and JSON mode both render from this
+     * one pass, so the two surfaces cannot drift apart.
+     */
+    async collectSpecDiffs(changeName, changesPath) {
+        const specsDir = path.join(changesPath, changeName, 'specs');
+        const mainSpecsDir = this.getSpecsPath();
+        // Same discovery ChangeParser uses, so a nested capability (specs/<area>/<id>)
+        // is diffed rather than silently skipped, and the ids here match the `spec`
+        // field of the JSON deltas.
+        const discovered = await discoverSpecFiles(specsDir);
+        const capabilities = discovered.map(spec => spec.id);
+        const results = [];
+        for (const { id: capability, specFile: deltaSpecPath } of discovered) {
+            const deltaContent = await fs.readFile(deltaSpecPath, 'utf-8');
+            const mainSpecPath = path.join(mainSpecsDir, ...capability.split('/'), 'spec.md');
+            let mainContent = null;
+            try {
+                FileSystemUtils.assertPathWithin(mainSpecsDir, mainSpecPath);
+                mainContent = await fs.readFile(mainSpecPath, 'utf-8');
+            }
+            catch (error) {
+                if (error?.code !== 'ENOENT')
+                    throw error;
+                // No main spec on disk. For ADDED requirements that is the ordinary new
+                // capability case; MODIFIED requirements are handled as a mismatch below.
+            }
+            const plan = parseDeltaSpec(deltaContent);
+            const renameMap = buildRenameMap(plan.renamed);
+            for (const block of plan.added) {
+                results.push({ capability, operation: 'ADDED', requirementName: block.name, raw: block.raw });
+            }
+            // Prefer the authored REMOVED block so its Reason/Migration text reaches
+            // the reader; the bullet-list form carries a name and nothing else.
+            const removedBlocks = new Map(plan.removedBlocks.map(block => [foldRequirementName(block.name), block.raw]));
+            for (const name of plan.removed) {
+                const raw = removedBlocks.get(foldRequirementName(name));
+                results.push({
+                    capability,
+                    operation: 'REMOVED',
+                    requirementName: name,
+                    raw: raw ?? `### Requirement: ${name}`,
+                });
+            }
+            for (const rename of plan.renamed) {
+                results.push({ capability, operation: 'RENAMED', requirementName: rename.to, raw: '', rename });
+            }
+            for (const block of plan.modified) {
+                const entry = {
+                    capability,
+                    operation: 'MODIFIED',
+                    requirementName: block.name,
+                    raw: block.raw,
+                };
+                // A requirement renamed and modified in the same delta still lives in
+                // the main spec under its old name, so look it up there.
+                const oldName = renameMap.get(foldRequirementName(block.name));
+                const lookupName = oldName ?? block.name;
+                const match = mainContent ? extractRequirementBlock(mainContent, lookupName) : null;
+                if (match) {
+                    entry.diff = diffRequirementBlock(match.raw, block.raw, `${capability}/${block.name}`);
+                    if (!match.exact) {
+                        // Archive matches requirement names exactly, so a header that
+                        // differs only in case or spacing will not merge. Show the diff the
+                        // author meant, and name the mismatch while it is still cheap to fix.
+                        entry.warning =
+                            `Header differs from the main spec's "${match.name}" only in case or spacing; ` +
+                                `archive matches names exactly, so reconcile them before archiving`;
+                    }
+                }
+                else if (mainContent) {
+                    entry.warning = `No matching main requirement found for "${lookupName}" in ${capability}`;
+                }
+                else {
+                    // A MODIFIED requirement names a block that should already exist, so a
+                    // missing main spec is an authoring error, not a new capability.
+                    // Rendering it as all-additions would hide what archive will reject.
+                    entry.warning =
+                        `No main spec at openspec/specs/${capability}/spec.md, ` +
+                            `so MODIFIED requirement "${block.name}" has nothing to diff against`;
+                }
+                results.push(entry);
+            }
+        }
+        return { capabilities, results };
+    }
+    /**
+     * Attach `diff` (or `warning`) to every MODIFIED delta in the JSON payload.
+     * Mutates the deltas array in place.
+     *
+     * The parsed Delta objects carry the requirement body in `description`, not
+     * the header name, so they are matched to parsed blocks by capability and
+     * source order: ChangeParser emits one Delta per MODIFIED block in that order.
+     */
+    async enrichDeltasWithDiffs(deltas, changeName, changesPath) {
+        const modifiedDeltasBySpec = new Map();
+        for (const delta of deltas) {
+            if (!delta.spec || delta.operation !== 'MODIFIED')
+                continue;
+            const list = modifiedDeltasBySpec.get(delta.spec) ?? [];
+            list.push(delta);
+            modifiedDeltasBySpec.set(delta.spec, list);
+        }
+        if (modifiedDeltasBySpec.size === 0)
+            return;
+        const { results } = await this.collectSpecDiffs(changeName, changesPath);
+        const modifiedEntriesBySpec = new Map();
+        for (const entry of results) {
+            if (entry.operation !== 'MODIFIED')
+                continue;
+            const list = modifiedEntriesBySpec.get(entry.capability) ?? [];
+            list.push(entry);
+            modifiedEntriesBySpec.set(entry.capability, list);
+        }
+        for (const [capability, modifiedDeltas] of modifiedDeltasBySpec) {
+            const entries = modifiedEntriesBySpec.get(capability) ?? [];
+            for (let i = 0; i < modifiedDeltas.length && i < entries.length; i++) {
+                const entry = entries[i];
+                if (entry.diff !== undefined) {
+                    modifiedDeltas[i].diff = entry.diff;
+                }
+                if (entry.warning !== undefined) {
+                    modifiedDeltas[i].warning = entry.warning;
+                }
+            }
+        }
+    }
+    /**
+     * Text mode: per-requirement diffs of the delta specs against the main specs.
+     */
+    async showSpecDiffs(changeName, changesPath) {
+        const { capabilities, results } = await this.collectSpecDiffs(changeName, changesPath);
+        console.log();
+        if (capabilities.length === 0 || results.length === 0) {
+            // Not an error: a change can be proposal-only. Saying so beats printing a
+            // heading with nothing under it.
+            console.log(`No delta specs to diff for change "${changeName}".`);
+            return;
+        }
+        console.log(chalk.bold('Specifications Changed (diffs)'));
+        console.log();
+        this.printDiffText(results);
+    }
+    printDiffText(results) {
+        let currentCap = '';
+        for (const r of results) {
+            if (r.capability !== currentCap) {
+                if (currentCap)
+                    console.log();
+                currentCap = r.capability;
+                console.log(chalk.bold.underline(currentCap));
+                console.log();
+            }
+            switch (r.operation) {
+                case 'ADDED':
+                    console.log(chalk.green.bold(`  ADDED: ${r.requirementName}`));
+                    for (const line of r.raw.split('\n')) {
+                        console.log(chalk.green(`    ${line}`));
+                    }
+                    console.log();
+                    break;
+                case 'REMOVED':
+                    console.log(chalk.red.bold(`  REMOVED: ${r.requirementName}`));
+                    for (const line of r.raw.split('\n')) {
+                        console.log(chalk.red(`    ${line}`));
+                    }
+                    console.log();
+                    break;
+                case 'RENAMED':
+                    console.log(chalk.cyan.bold(`  RENAMED: ${r.rename?.from} → ${r.rename?.to}`));
+                    console.log();
+                    break;
+                case 'MODIFIED':
+                    console.log(chalk.yellow.bold(`  MODIFIED: ${r.requirementName}`));
+                    if (r.warning) {
+                        console.log(chalk.yellow(`    ⚠ ${r.warning}`));
+                    }
+                    // A near-miss header carries both: the warning about the mismatch and
+                    // the diff against the block it almost matched.
+                    if (r.diff === undefined) {
+                        for (const line of r.raw.split('\n')) {
+                            console.log(`    ${line}`);
+                        }
+                    }
+                    else if (r.diff === '') {
+                        console.log(chalk.dim('    (no textual changes)'));
+                    }
+                    else {
+                        for (const line of r.diff.split('\n')) {
+                            if (line.startsWith('+')) {
+                                console.log(chalk.green(`    ${line}`));
+                            }
+                            else if (line.startsWith('-')) {
+                                console.log(chalk.red(`    ${line}`));
+                            }
+                            else {
+                                console.log(`    ${line}`);
+                            }
+                        }
+                    }
+                    console.log();
+                    break;
+            }
         }
     }
     /**

package/dist/commands/config.js

@@ -453,6 +453,7 @@ export function registerConfigCommand(program) {
                 delivery: currentState.delivery,
                 workflows: [...currentState.workflows],
             };
+            let workflowSelectionChanged = false;
             if (action === 'both' || action === 'delivery') {
                 const deliveryChoices = [
                     {
@@ -497,8 +498,11 @@ export function registerConfigCommand(program) {
                     };
                 };
                 const selectedWorkflows = await checkbox({
+                    // The `instructions` option was removed in @inquirer/checkbox v5.
+                    // Its replacement, the built-in keys help tip, renders
+                    // "↑↓ navigate • space select • ⏎ submit" by default — a superset of
+                    // the hint this used to pass — so no theme override is needed here.
                     message: 'Select workflows to make available:',
-                    instructions: 'Space to toggle, Enter to confirm',
                     pageSize: ALL_WORKFLOWS.length,
                     theme: {
                         icon: {
@@ -509,7 +513,12 @@ export function registerConfigCommand(program) {
                     choices: ALL_WORKFLOWS.map(formatWorkflowChoice),
                 });
                 nextState.workflows = selectedWorkflows;
-                nextState.profile = deriveProfileFromWorkflowSelection(selectedWorkflows);
+                workflowSelectionChanged =
+                    selectedWorkflows.length !== currentState.workflows.length ||
+                        selectedWorkflows.some((workflow) => !currentState.workflows.includes(workflow));
+                nextState.profile = workflowSelectionChanged
+                    ? deriveProfileFromWorkflowSelection(selectedWorkflows)
+                    : currentState.profile;
             }
             const diff = diffProfileState(currentState, nextState);
             if (!diff.hasChanges) {
@@ -524,7 +533,9 @@ export function registerConfigCommand(program) {
             console.log();
             config.profile = nextState.profile;
             config.delivery = nextState.delivery;
-            config.workflows = nextState.workflows;
+            if (currentState.profile !== 'custom' || workflowSelectionChanged) {
+                config.workflows = nextState.workflows;
+            }
             saveGlobalConfig(config);
             // Check if inside an OpenSpec project
             const projectDir = process.cwd();

package/dist/commands/feedback.js

@@ -2,6 +2,8 @@ import { execSync, execFileSync } from 'child_process';
 import { createRequire } from 'module';
 import os from 'os';
 const require = createRequire(import.meta.url);
+const MAX_TITLE_LENGTH = 72;
+const TITLE_PREFIX = 'Feedback: ';
 /**
  * Check if gh CLI is installed and available in PATH
  * Uses platform-appropriate command: 'where' on Windows, 'which' on Unix/macOS
@@ -69,18 +71,37 @@ Submitted via OpenSpec CLI
  * Format the feedback title
  */
 function formatTitle(message) {
-    return `Feedback: ${message}`;
+    const normalizedMessage = message.replace(/\s+/g, ' ').trim();
+    const title = `${TITLE_PREFIX}${normalizedMessage}`;
+    if (Array.from(title).length <= MAX_TITLE_LENGTH) {
+        return title;
+    }
+    const availableLength = MAX_TITLE_LENGTH - TITLE_PREFIX.length - 1;
+    let candidate = '';
+    let candidateLength = 0;
+    const segments = new Intl.Segmenter(undefined, { granularity: 'grapheme' }).segment(normalizedMessage);
+    for (const { segment } of segments) {
+        const segmentLength = Array.from(segment).length;
+        if (candidateLength + segmentLength > availableLength) {
+            break;
+        }
+        candidate += segment;
+        candidateLength += segmentLength;
+    }
+    candidate = candidate.trimEnd();
+    const lastSpace = candidate.lastIndexOf(' ');
+    const summary = lastSpace > 0 ? candidate.slice(0, lastSpace) : candidate;
+    return `${TITLE_PREFIX}${summary}…`;
 }
 /**
  * Format the full feedback body
  */
-function formatBody(bodyText) {
-    const parts = [];
+function formatBody(message, bodyText) {
+    const parts = ['## Summary', '', message];
     if (bodyText) {
-        parts.push(bodyText);
-        parts.push(''); // Empty line before metadata
+        parts.push('', '## Details', '', bodyText);
     }
-    parts.push(generateMetadata());
+    parts.push('', generateMetadata());
     return parts.join('\n');
 }
 /**
@@ -216,7 +237,7 @@ export class FeedbackCommand {
     async execute(message, options) {
         // Format title and body once for all code paths
         const title = formatTitle(message);
-        const body = formatBody(options?.body);
+        const body = formatBody(message, options?.body);
         // Check if gh CLI is installed
         if (!isGhInstalled()) {
             handleFallback(title, body, 'missing');

package/dist/commands/schema.d.ts

@@ -1,4 +1,9 @@
 import { Command } from 'commander';
+import * as fs from 'node:fs';
+/** @internal File-operation seam for transactional failure tests. */
+export declare const schemaInitFileOperations: {
+    renameSync: typeof fs.renameSync;
+};
 /**
  * Register the schema command and all its subcommands.
  */