fix(workboard): preserve json list archive visibility

ZengWen-DT · ZengWen-DT · commit c2fec1243ff7 · 2026-06-20T18:03:36.000+08:00
diff --git a/docs/cli/workboard.md b/docs/cli/workboard.md
@@ -50,16 +50,16 @@ Columns are id prefix, status, priority, board id, optional agent id, and title.
 
 Flags:
 
-| Flag                 | Purpose                                                       |
-| -------------------- | ------------------------------------------------------------- |
-| `--board <id>`       | Limit results to one board namespace                          |
-| `--status <status>`  | Limit results to one Workboard status                         |
-| `--include-archived` | Include archived cards (hidden by default, matching the tool) |
-| `--json`             | Print the full card list as machine JSON                      |
-
-Archived cards are hidden by default so the CLI matches the `workboard_list`
-agent tool and the `/workboard list` command. Pass `--include-archived` to show
-them.
+| Flag                 | Purpose                                       |
+| -------------------- | --------------------------------------------- |
+| `--board <id>`       | Limit results to one board namespace          |
+| `--status <status>`  | Limit results to one Workboard status         |
+| `--include-archived` | Include archived cards in compact text output |
+| `--json`             | Print the full card list as machine JSON      |
+
+Compact text output hides archived cards by default so the CLI matches the
+`/workboard list` command. Pass `--include-archived` to show them. JSON output
+keeps the full card list, including archived cards, for existing automation.
 
 ## `create`
 
diff --git a/extensions/workboard/src/cli.test.ts b/extensions/workboard/src/cli.test.ts
@@ -106,26 +106,38 @@ describe("registerWorkboardCli", () => {
     expect(showOutput).toContain("[redacted]");
   });
 
-  it("hides archived cards by default and reveals them with --include-archived", async () => {
+  it("hides archived cards from text output by default and reveals them with --include-archived", async () => {
     const store = new WorkboardStore(createMemoryStore());
-    const active = await store.create({ title: "Active card" });
+    await store.create({ title: "Active card" });
     const archived = await store.create({ title: "Archived card" });
     await store.archive(archived.id, true);
     const program = createProgram(store);
 
     const defaultOutput = await captureStdout(async () => {
-      await program.parseAsync(["workboard", "list", "--json"], { from: "user" });
+      await program.parseAsync(["workboard", "list"], { from: "user" });
     });
     const includeOutput = await captureStdout(async () => {
-      await program.parseAsync(["workboard", "list", "--include-archived", "--json"], {
-        from: "user",
-      });
+      await program.parseAsync(["workboard", "list", "--include-archived"], { from: "user" });
+    });
+
+    expect(defaultOutput).toContain("Active card");
+    expect(defaultOutput).not.toContain("Archived card");
+    expect(includeOutput).toContain("Active card");
+    expect(includeOutput).toContain("Archived card");
+  });
+
+  it("preserves archived cards in JSON list output by default", async () => {
+    const store = new WorkboardStore(createMemoryStore());
+    const archived = await store.create({ title: "Archived card" });
+    await store.archive(archived.id, true);
+    const program = createProgram(store);
+
+    const output = await captureStdout(async () => {
+      await program.parseAsync(["workboard", "list", "--json"], { from: "user" });
     });
 
-    expect(defaultOutput).toContain(active.id);
-    expect(defaultOutput).not.toContain(archived.id);
-    expect(includeOutput).toContain(active.id);
-    expect(includeOutput).toContain(archived.id);
+    expect(output).toContain(archived.id);
+    expect(output).toContain("archivedAt");
   });
 
   it("does not fall back to local dispatch for explicit gateway targets", async () => {
diff --git a/extensions/workboard/src/cli.ts b/extensions/workboard/src/cli.ts
@@ -140,11 +140,12 @@ export function registerWorkboardCli(params: { program: Command; store: Workboar
           includeArchived?: boolean;
         },
       ) => {
-        // Hide archived cards by default to match the workboard_list tool and the
-        // /workboard list command; --include-archived restores the full set.
-        let cards = (await params.store.list({ boardId: options.board })).filter(
-          (card) => options.includeArchived === true || !card.metadata?.archivedAt,
-        );
+        // Text output hides archived cards like /workboard list, while --json
+        // keeps the shipped full-card contract for existing scripts.
+        let cards = await params.store.list({ boardId: options.board });
+        if (!options.json && options.includeArchived !== true) {
+          cards = cards.filter((card) => !card.metadata?.archivedAt);
+        }
         if (options.status) {
           cards = cards.filter((card) => card.status === options.status);
         }
