fix(lifecycle): sync returns its report — exit codes live at the CLI edge

Programmatic callers read the returned SyncReport instead of sniffing
process.exitCode; a new silent option suppresses output for reuse as a
gate. Unreadable metadata on a named sync now yields the same conflict
entry the no-arg sweep reports, so CI parses one shape either way, and
list rejects an unknown --status value instead of printing an empty
list that reads as success.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: ixxie

src/cli/index.ts

@@ -461,7 +461,10 @@ program
   .option('--json', 'Output as JSON (non-interactive)')
   .action(async (changeName?: string, options?: { check?: boolean; json?: boolean }) => {
     try {
-      await new SyncCommand().execute(changeName, '.', options ?? {});
+      const report = await new SyncCommand().execute(changeName, '.', options ?? {});
+      if (!report.clean) {
+        process.exitCode = 1;
+      }
     } catch (error) {
       failWithError(error);
       process.exit(1);
@@ -476,7 +479,10 @@ program
   .option('--json', 'Output as JSON (non-interactive)')
   .action(async (changeName: string, options?: { json?: boolean }) => {
     try {
-      await new ShipCommand().execute(changeName, '.', options ?? {});
+      const report = await new ShipCommand().execute(changeName, '.', options ?? {});
+      if (!report.clean) {
+        process.exitCode = 1;
+      }
     } catch (error) {
       failWithError(error);
       process.exit(1);

src/core/list.ts

@@ -118,6 +118,12 @@ export class ListCommand {
   async execute(targetPath: string = '.', mode: 'changes' | 'specs' = 'changes', options: ListOptions = {}): Promise<void> {
     const { sort = 'recent', json = false, root } = options;
 
+    if (options.status && !LIFECYCLE_STATES.has(options.status)) {
+      throw new Error(
+        `Unknown status '${options.status}' — expected one of: ${[...LIFECYCLE_STATES].join(', ')}.`
+      );
+    }
+
     if (mode === 'changes') {
       const changesDir = path.join(targetPath, 'openspec', 'changes');
 

src/core/sync.ts

@@ -17,6 +17,8 @@ import { resolveLifecycle } from './project-config.js';
 export interface SyncOptions {
   check?: boolean;
   json?: boolean;
+  /** Suppress all output — programmatic callers read the returned report. */
+  silent?: boolean;
 }
 
 type PendingFold = {
@@ -57,22 +59,25 @@ export class SyncCommand {
     changeName: string | undefined,
     targetPath: string = '.',
     options: SyncOptions = {}
-  ): Promise<void> {
+  ): Promise<SyncReport> {
     const mode = resolveLifecycle(targetPath);
     const report: SyncReport = { mode, changes: [], clean: true };
 
     if (mode !== 'status') {
       // Mode-aware by contract: under `lifecycle: archive` the archive command
       // owns the fold and there is no status field to gate on. Report and exit
       // 0 rather than misfiring on the default layout.
+      if (options.silent) {
+        return report;
+      }
       if (options.json) {
         console.log(JSON.stringify(report, null, 2));
       } else {
         console.log(
           "This project uses `lifecycle: archive` (the default) — nothing to sync or gate. `openspec sync` applies under `lifecycle: status`; see openspec/config.yaml."
         );
       }
-      return;
+      return report;
     }
 
     const changesDir = path.join(targetPath, 'openspec', 'changes');
@@ -95,23 +100,23 @@ export class SyncCommand {
       if (!options.check && state.report.state === 'unfolded') {
         for (const fold of state.folds) {
           await writeUpdatedSpec(fold.update, fold.rebuilt, fold.counts, {
-            silent: options.json,
+            silent: options.json || options.silent,
           });
         }
         state.report.state = 'folded';
         report.clean = report.changes.every((c) => c.state === 'folded');
       }
     }
 
-    if (options.json) {
-      console.log(JSON.stringify(report, null, 2));
-    } else {
-      this.print(report, options);
+    if (!options.silent) {
+      if (options.json) {
+        console.log(JSON.stringify(report, null, 2));
+      } else {
+        this.print(report, options);
+      }
     }
 
-    if (!report.clean) {
-      process.exitCode = 1;
-    }
+    return report;
   }
 
   private async shippedChanges(
@@ -166,7 +171,22 @@ export class SyncCommand {
 
     // An explicitly named change must be shipped before its deltas may touch
     // specs/. In check mode a non-shipped change is simply not gated.
-    const metadata = readChangeMetadata(changeDir, projectRoot);
+    // Unreadable metadata is the same conflict entry the no-arg sweep reports,
+    // so CI sees one shape either way.
+    let metadata;
+    try {
+      metadata = readChangeMetadata(changeDir, projectRoot);
+    } catch (err) {
+      return {
+        report: {
+          change: name,
+          state: 'conflict',
+          pending: [],
+          error: err instanceof ChangeMetadataError ? err.message : String(err),
+        },
+        folds: [],
+      };
+    }
     if (metadata?.status !== 'shipped') {
       if (options.check) {
         return null;
@@ -240,7 +260,7 @@ export class ShipCommand {
     changeName: string,
     targetPath: string = '.',
     options: { json?: boolean } = {}
-  ): Promise<void> {
+  ): Promise<SyncReport> {
     const mode = resolveLifecycle(targetPath);
     if (mode !== 'status') {
       throw new Error(
@@ -265,6 +285,6 @@ export class ShipCommand {
       console.log(`  ${changeName}: already shipped`);
     }
 
-    await new SyncCommand().execute(changeName, targetPath, { json: options.json });
+    return new SyncCommand().execute(changeName, targetPath, { json: options.json });
   }
 }

test/core/list.test.ts

@@ -48,6 +48,17 @@ describe('ListCommand', () => {
       expect(logOutput).toEqual(['No active changes found.']);
     });
 
+    it('rejects an unknown --status value instead of silently matching nothing', async () => {
+      const changesDir = path.join(tempDir, 'openspec', 'changes');
+      await fs.mkdir(changesDir, { recursive: true });
+
+      const listCommand = new ListCommand();
+
+      await expect(
+        listCommand.execute(tempDir, 'changes', { status: 'bogus' })
+      ).rejects.toThrow(/Unknown status 'bogus'/);
+    });
+
     it('should not report a malformed openspec/changes path as empty', async () => {
       await fs.mkdir(path.join(tempDir, 'openspec'), { recursive: true });
       await fs.writeFile(path.join(tempDir, 'openspec', 'changes'), 'not a directory\n');

test/core/sync.test.ts

@@ -71,44 +71,72 @@ describe('SyncCommand', () => {
 
   it('reports nothing to gate under lifecycle: archive', async () => {
     await scaffold({ lifecycle: 'archive', status: 'shipped' });
-    await new SyncCommand().execute(undefined, tempDir, { check: true });
-    expect(process.exitCode).toBeUndefined();
+    const report = await new SyncCommand().execute(undefined, tempDir, { check: true });
+    expect(report.clean).toBe(true);
+    expect(report.mode).toBe('archive');
     expect(logs.join('\n')).toContain('lifecycle: archive');
   });
 
   it('check fails on a shipped change whose delta is not folded', async () => {
     await scaffold({ lifecycle: 'status', status: 'shipped' });
-    await new SyncCommand().execute(undefined, tempDir, { check: true });
-    expect(process.exitCode).toBe(1);
+    const report = await new SyncCommand().execute(undefined, tempDir, { check: true });
+    expect(report.clean).toBe(false);
     expect(logs.join('\n')).toContain('add-oauth');
     expect(logs.join('\n')).toContain('auth');
   });
 
   it('ignores proposed changes: their deltas stay out of specs/', async () => {
     await scaffold({ lifecycle: 'status', status: 'proposed' });
-    await new SyncCommand().execute(undefined, tempDir, { check: true });
-    expect(process.exitCode).toBeUndefined();
+    const report = await new SyncCommand().execute(undefined, tempDir, { check: true });
+    expect(report.clean).toBe(true);
     await expect(fs.access(targetSpec())).rejects.toThrow();
   });
 
   it('folds a shipped change, then check passes and a re-run is a no-op', async () => {
     await scaffold({ lifecycle: 'status', status: 'shipped' });
 
-    await new SyncCommand().execute(undefined, tempDir, {});
-    expect(process.exitCode).toBeUndefined();
+    const fold = await new SyncCommand().execute(undefined, tempDir, {});
+    expect(fold.clean).toBe(true);
     const folded = await fs.readFile(targetSpec(), 'utf-8');
     expect(folded).toContain('OAuth login');
 
-    process.exitCode = undefined;
     logs = [];
-    await new SyncCommand().execute(undefined, tempDir, { check: true });
-    expect(process.exitCode).toBeUndefined();
+    const check = await new SyncCommand().execute(undefined, tempDir, { check: true });
+    expect(check.clean).toBe(true);
 
     await new SyncCommand().execute(undefined, tempDir, {});
     const refolded = await fs.readFile(targetSpec(), 'utf-8');
     expect(refolded).toBe(folded);
   });
 
+  it('silent mode emits nothing and still returns the report', async () => {
+    await scaffold({ lifecycle: 'status', status: 'shipped' });
+    const report = await new SyncCommand().execute(undefined, tempDir, {
+      check: true,
+      silent: true,
+    });
+    expect(report.clean).toBe(false);
+    expect(logs).toEqual([]);
+  });
+
+  it('reports unreadable metadata as the same conflict entry named or swept', async () => {
+    await scaffold({ lifecycle: 'status', status: 'shipped' });
+    await fs.writeFile(
+      path.join(tempDir, 'openspec', 'changes', 'add-oauth', '.openspec.yaml'),
+      'status: [unclosed\n'
+    );
+
+    const swept = await new SyncCommand().execute(undefined, tempDir, { check: true, silent: true });
+    const named = await new SyncCommand().execute('add-oauth', tempDir, { check: true, silent: true });
+
+    for (const report of [swept, named]) {
+      expect(report.clean).toBe(false);
+      expect(report.changes).toHaveLength(1);
+      expect(report.changes[0].state).toBe('conflict');
+      expect(report.changes[0].error).toBeTruthy();
+    }
+  });
+
   it('refuses to fold an explicitly named change that is not shipped', async () => {
     await scaffold({ lifecycle: 'status', status: 'proposed' });
     await expect(
@@ -119,8 +147,8 @@ describe('SyncCommand', () => {
   it('ship flips status and folds in one step; re-ship is a no-op', async () => {
     await scaffold({ lifecycle: 'status', status: 'proposed' });
 
-    await new ShipCommand().execute('add-oauth', tempDir, {});
-    expect(process.exitCode).toBeUndefined();
+    const shipped = await new ShipCommand().execute('add-oauth', tempDir, {});
+    expect(shipped.clean).toBe(true);
     const metadata = await fs.readFile(
       path.join(tempDir, 'openspec', 'changes', 'add-oauth', '.openspec.yaml'),
       'utf-8'
@@ -129,9 +157,8 @@ describe('SyncCommand', () => {
     const folded = await fs.readFile(targetSpec(), 'utf-8');
     expect(folded).toContain('OAuth login');
 
-    process.exitCode = undefined;
-    await new ShipCommand().execute('add-oauth', tempDir, {});
-    expect(process.exitCode).toBeUndefined();
+    const reshipped = await new ShipCommand().execute('add-oauth', tempDir, {});
+    expect(reshipped.clean).toBe(true);
     expect(await fs.readFile(targetSpec(), 'utf-8')).toBe(folded);
   });