@enrichlayer/el-linear 1.18.1 → 1.20.0

package/README.md

@@ -356,6 +356,27 @@ preferences; those stay in personal config. Example team file:
 Run `el-linear config show` to see the resolved config and confirm which team
 config path is active (`teamConfig` field in the output).
 
+#### Migrating a personal-heavy config
+
+Before the team-config split, members typically carried full local copies of
+`members` / `teams` / `labels` / `statusDefaults` / `teamAliases` — and often
+a deprecated `brand: { name, reject }` key. Once a team config is in place
+those local copies just silently shadow the shared values (and silently
+*diverge* when they drift). To clean it up safely:
+
+```bash
+el-linear config migrate-from-personal           # dry-run — prints the plan per file
+el-linear config migrate-from-personal --apply   # write the slimmed files (with .bak-<ts> backups)
+```
+
+Targets the global personal config + every named profile's `config.json`. For
+each top-level shadowable key, the slim drops it **only** when the local copy
+is a strict subset of team (zero divergence, zero non-trivial personal-only
+entries); otherwise the key is left untouched and the divergence is reported
+in the plan so a human resolves it. The deprecated `brand` key is dropped
+when content-identical to a team `terms[]` entry, or converted to a personal
+`terms[]` entry when it differs (with a warning).
+
 ## Term enforcement (with brand-promotion examples)
 
 The `terms` rules let you keep a list of canonical names and the misspellings
@@ -426,6 +447,24 @@ el-linear <command> --help       # detailed help for one command
 All `list` subcommands support `-l, --limit <n>`. All commands accept the
 top-level filters: `--format <json|summary>`, `--raw`, `--jq <expr>`, `--fields <list>`.
 
+### Open by default — `issues list` and `issues search` skip terminal states
+
+`el-linear issues list` and `el-linear issues search` **exclude issues in
+terminal workflow states (`Done` / `Canceled`) by default** so triage and
+survey runs return the open set without piping through `grep`. The implicit
+filter is surfaced in `_warnings` on every invocation, so scripts notice it
+deterministically rather than silently. Three ways to opt back in:
+
+```bash
+el-linear issues list --include-closed              # everything, including Done/Canceled
+el-linear issues search "auth" --status "Done"      # explicit --status wins
+el-linear issues list --status "Todo,In Progress"   # any explicit status disables the implicit filter
+```
+
+`--include-closed` and explicit `--status` both bypass the implicit filter
+(explicit choice always wins). The change is per-command and only affects
+list-shaped reads — single-issue `issues read DEV-123` is unaffected.
+
 ## Output formats
 
 Every command accepts `--format <kind>` at the root:
@@ -514,6 +553,52 @@ el-linear read ADM-652 --field "Out of scope"
 Single-issue only — pair it with `--jq` on full JSON for batch
 extraction across many issues.
 
+### Render an issue's tree: `issues tree`
+
+`issues tree <ID>` walks the parent → children graph for an issue in a
+single GraphQL round-trip and returns either a nested JSON envelope
+(default) or an ASCII tree (`--format summary`).
+
+```bash
+el-linear issues tree DEV-100 --format summary
+# DEV-100 Migrate auth middleware
+# ├── DEV-101 Write design doc
+# │   ├── DEV-104 Survey existing auth flows [Done]
+# │   └── DEV-105 Draft RFC
+# ├── DEV-102 Build new session store (@Alice)
+# └── DEV-103 Cutover plan
+```
+
+Depth defaults to **3** (max 5 — Linear has no native depth-N recursion,
+so each level adds a `children { nodes { ... } }` block to the generated
+query). Terminal-state branches (`Done` / `Canceled`) are **kept** by
+default because the tree's value is *structural*; pass
+`--no-include-closed` to prune them.
+
+### Extract several sections in one call: `--sections`
+
+When you want multiple sections (e.g. `Done when`, `Out of scope`, and
+`Steps`), don't issue N separate `--field` calls — pass a comma-separated
+list to `--sections` instead:
+
+```bash
+el-linear issues read DEV-123 --sections "Done when,Out of scope"
+# {
+#   "identifier": "DEV-123",
+#   "sections": {
+#     "Done when": "...",
+#     "Out of scope": "..."
+#   }
+# }
+```
+
+Returns a JSON envelope `{ identifier, sections: { name → text|null } }`.
+Missing sections map to `null` and surface in `_warnings` so scripts can
+detect them deterministically. Single-issue only, mutually exclusive
+with `--field`. (Named `--sections` rather than the seemingly-obvious
+`--fields` because `--fields` is already taken at the program level for
+output-key filtering — `el-linear` is the namespace owner.)
+
 ## Wrapping Linear references in arbitrary text
 
 `el-linear refs wrap` takes plain text on stdin (or via `--file`) and rewrites

package/claude-skills/linear-operations/SKILL.md

@@ -123,7 +123,11 @@ and outreach tracked in one place.
 **Search before creating. No exceptions.**
 
 ```bash
-el-linear issues search "keywords from proposed title" 2>&1
+# --include-closed is required so previously-completed duplicates surface.
+# `issues search` defaults to open states (DEV-4478); the duplicate check
+# intentionally widens to Done/Canceled because a closed-out duplicate is
+# still a duplicate.
+el-linear issues search "keywords from proposed title" --include-closed 2>&1
 ```
 
 1. Extract 2–3 key terms from the proposed title (skip generic words).
@@ -269,6 +273,7 @@ Run `el-linear usage` for the full command reference. Non-obvious rules:
 - **Subcommand aliases** — `read`/`view`/`get`/`show`, `update`/`edit`/`set`.
 - **`--jq` for GraphQL filtering** — never pipe through `jq` directly (zsh escaping breaks `!=`).
 - **`--raw` flag** strips the `{ data, meta }` wrapper — emits just the array.
+- **Body/description from a file** — `issues create`/`update` take `--description-file <path>`; `comments create`/`update` take `--body-file <path>`. Prefer the file form for any body with backticks, fenced code, or markdown tables — it sidesteps shell-quoting traps (the same reason `el-git mr comment --body-file` exists). `--body` and `--body-file` are **mutually exclusive** (passing both errors); file-sourced bodies get the same auto-link / auto-mention treatment as inline `--body`.
 
 ### Output format
 

package/dist/commands/comments.js

@@ -18,6 +18,12 @@ import { getWorkspaceUrlKey } from "../utils/workspace-url.js";
 const BODY_DATA_ERROR_RE = /prosemirror|bodydata|invalid.*body/i;
 const ISSUE_IDENTIFIER_REGEX = /^[A-Z][A-Z0-9]*-\d+$/;
 function readBody(options) {
+    // --body and --body-file are two sources for the same field; accepting both
+    // would silently drop one. Reject up front (DEV-4450) — the same mutual-
+    // exclusivity contract resolveDescription() enforces for --template.
+    if (options.body && options.bodyFile) {
+        throw new Error("--body and --body-file are mutually exclusive — pass one or the other");
+    }
     if (options.bodyFile) {
         return readFileSync(options.bodyFile, "utf-8");
     }

package/dist/commands/config.js

@@ -2,7 +2,8 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { getActiveTeamConfigInfo, getActiveTeamConfigPath, loadConfig, loadLocalConfig, } from "../config/config.js";
-import { resolveActiveProfile } from "../config/paths.js";
+import { planMigration, } from "../config/migrate-from-personal.js";
+import { CONFIG_PATH, isSafeProfileName, PROFILES_DIR, resolveActiveProfile, } from "../config/paths.js";
 import { handleAsyncCommand, outputSuccess, outputWarning, } from "../utils/output.js";
 import { updateConfig } from "./init/shared.js";
 /**
@@ -185,4 +186,166 @@ export function setupConfigCommands(program) {
         fs.writeFileSync(localPath, `${JSON.stringify(updated, null, 2)}\n`, "utf8");
         outputSuccess({ data: updated });
     }));
+    // ── config migrate-from-personal ──────────────────────────────────
+    //
+    // Slim personal/profile configs that duplicate keys the team config now
+    // provides (DEV-4458). The companion pure logic + tests live in
+    // `src/config/migrate-from-personal.ts`. This command just discovers
+    // the target files, reads the active team config, calls planMigration
+    // for each, and on --apply backs up + atomically rewrites them.
+    config
+        .command("migrate-from-personal")
+        .description("Slim personal/profile configs against the active team config — drops duplicated members/teams/labels/statusDefaults/teamAliases entries, and migrates the deprecated 'brand' key to a 'terms[]' entry. Dry-run by default; pass --apply to write.")
+        .option("--apply", "Write the slimmed files (with timestamped .bak-<ts> backups + atomic replace). Default is dry-run — only prints the plan.")
+        .option("--file <path>", "Scope to one file. Default: ~/.config/el-linear/config.json plus every <profiles>/<name>/config.json with a safe name.")
+        .addHelpText("after", `\nThe slim only drops a shadowable top-level key when the personal copy is a strict subset of team (zero divergence and zero non-trivial personal-only entries). Anything that would silently shadow a team value, or carry a personal-only entry team doesn't have, is left untouched and reported in the plan so a human can decide.\n\nThe active team config is never a target — passing --file <team-path> is rejected, and a profile config that happens to coincide with the team path is skipped silently with a warning. The first --apply may re-format JSON to 2-space indent + trailing newline; this is harmless but the .bak-<ts> backup preserves the original byte-for-byte.\n\nUses the currently-active team config for every target. If you have profiles pointing at different team configs, run --file <path> per profile with EL_LINEAR_TEAM_CONFIG set.\n\nExamples:\n  el-linear config migrate-from-personal\n  el-linear config migrate-from-personal --apply\n  el-linear config migrate-from-personal --file ~/.config/el-linear/profiles/foo/config.json --apply`)
+        .action(handleAsyncCommand(async (opts) => {
+        const teamPath = getActiveTeamConfigPath();
+        if (!teamPath) {
+            throw new Error("No active team config found. Set one with `el-linear config team set-path <path>` (or EL_LINEAR_TEAM_CONFIG) before running migrate-from-personal — without a team layer there's nothing to dedupe against.");
+        }
+        let team;
+        try {
+            team = JSON.parse(fs.readFileSync(teamPath, "utf8"));
+        }
+        catch (err) {
+            throw new Error(`Failed to read team config at ${teamPath}: ${err.message}`);
+        }
+        const apply = opts.apply ?? false;
+        const resolvedTeamPath = path.resolve(teamPath);
+        // Self-diff guard: refuse to migrate the team config against itself
+        // (cycle-1 nit). Without this, every shadowable key in team would
+        // classify as "drop" (a key is trivially a subset of itself) and
+        // --apply would gut the team config.
+        if (opts.file &&
+            path.resolve(expandHome(opts.file)) === resolvedTeamPath) {
+            throw new Error(`--file resolves to the active team config (${resolvedTeamPath}). Refusing to migrate the team config against itself.`);
+        }
+        const targetsBeforeFilter = opts.file
+            ? [path.resolve(expandHome(opts.file))]
+            : enumerateMigrationTargets();
+        const targets = [];
+        for (const t of targetsBeforeFilter) {
+            if (path.resolve(t) === resolvedTeamPath) {
+                outputWarning(`Skipping ${t} — it resolves to the active team config; migrating it against itself would erase team-shared keys.`);
+                continue;
+            }
+            targets.push(t);
+        }
+        const results = targets.map((file) => migrateOneFile(file, team, apply));
+        // Forward per-file plan warnings to the standard _warnings envelope
+        // (cycle-1 nit) so scripters reading the stable warning channel see
+        // them without having to inspect each target.
+        for (const r of results) {
+            for (const w of r.warnings)
+                outputWarning(`${r.file}: ${w}`);
+        }
+        // --file <single>: an unreadable / unparseable target is a hard
+        // failure (cycle-1 nit). Default enumeration stays soft so one bad
+        // profile doesn't crash the run for the rest.
+        if (opts.file && results.length === 1 && results[0].error) {
+            throw new Error(results[0].error);
+        }
+        outputSuccess({
+            data: {
+                teamConfigPath: teamPath,
+                applied: apply,
+                targetCount: results.length,
+                targets: results,
+            },
+        });
+    }));
+}
+/**
+ * Enumerate every personal/profile config file the migration tool should
+ * consider by default: the global personal config, plus each profile dir
+ * whose name passes `isSafeProfileName` and whose `config.json` exists.
+ */
+function enumerateMigrationTargets() {
+    const out = [];
+    if (fs.existsSync(CONFIG_PATH))
+        out.push(CONFIG_PATH);
+    if (fs.existsSync(PROFILES_DIR)) {
+        const entries = fs.readdirSync(PROFILES_DIR);
+        for (const name of entries.sort()) {
+            if (!isSafeProfileName(name))
+                continue;
+            const p = path.join(PROFILES_DIR, name, "config.json");
+            if (fs.existsSync(p))
+                out.push(p);
+        }
+    }
+    return out;
+}
+function migrateOneFile(file, team, apply) {
+    let rawText;
+    let personal;
+    try {
+        rawText = fs.readFileSync(file, "utf8");
+        personal = JSON.parse(rawText);
+    }
+    catch (err) {
+        return {
+            file,
+            changed: false,
+            before: { sizeBytes: 0, keys: [] },
+            after: { sizeBytes: 0, keys: [] },
+            keys: [],
+            brand: { status: "absent" },
+            warnings: [],
+            error: `Could not read/parse: ${err.message}`,
+        };
+    }
+    const { slimmed, plan } = planMigration(personal, team);
+    const slimmedText = `${JSON.stringify(slimmed, null, 2)}\n`;
+    const beforeBytes = Buffer.byteLength(rawText, "utf8");
+    const afterBytes = Buffer.byteLength(slimmedText, "utf8");
+    const changed = slimmedText !== rawText;
+    const result = {
+        file,
+        changed,
+        before: { sizeBytes: beforeBytes, keys: Object.keys(personal) },
+        after: { sizeBytes: afterBytes, keys: Object.keys(slimmed) },
+        keys: plan.keys,
+        brand: plan.brand,
+        warnings: plan.warnings,
+    };
+    if (apply && changed) {
+        // Backup names include milliseconds (sub-second collisions on rapid
+        // re-apply would otherwise overwrite the original backup) AND copy
+        // with COPYFILE_EXCL so a same-millisecond collision throws instead
+        // of clobbering. Same for the temp file via `wx` flag.
+        const { backup, tmp } = acquireBackupAndTempPaths(file);
+        fs.copyFileSync(file, backup, fs.constants.COPYFILE_EXCL);
+        fs.writeFileSync(tmp, slimmedText, { encoding: "utf8", flag: "wx" });
+        fs.renameSync(tmp, file);
+        result.backup = backup;
+    }
+    return result;
+}
+function backupTimestamp() {
+    const d = new Date();
+    const pad = (n) => n.toString().padStart(2, "0");
+    const pad3 = (n) => n.toString().padStart(3, "0");
+    return (`${d.getFullYear()}${pad(d.getMonth() + 1)}${pad(d.getDate())}` +
+        `-${pad(d.getHours())}${pad(d.getMinutes())}${pad(d.getSeconds())}` +
+        `-${pad3(d.getMilliseconds())}`);
+}
+/**
+ * Pick a `.bak-<ts>` and `.tmp-<ts>` pair that don't collide with anything
+ * on disk. Millisecond resolution makes a collision extraordinarily rare,
+ * but a tight retry loop closes the remaining gap (and the `COPYFILE_EXCL`
+ * / `wx` flags at the call site fail loudly if the gap is ever crossed).
+ */
+function acquireBackupAndTempPaths(file) {
+    for (let attempt = 0; attempt < 100; attempt++) {
+        const ts = backupTimestamp();
+        const suffix = attempt === 0 ? ts : `${ts}-${attempt}`;
+        const backup = `${file}.bak-${suffix}`;
+        const tmp = `${file}.tmp-${suffix}`;
+        if (!fs.existsSync(backup) && !fs.existsSync(tmp)) {
+            return { backup, tmp };
+        }
+    }
+    throw new Error(`Could not pick a unique backup name for ${file} after 100 attempts; clean up old .bak-/.tmp- siblings and retry.`);
 }

package/dist/commands/issues/tree.d.ts

@@ -0,0 +1,22 @@
+/**
+ * `el-linear issues tree <ID>` (DEV-4480).
+ *
+ * Renders the parent-and-children tree of an issue to depth N (default 3,
+ * max 5 — see `MAX_TREE_DEPTH`). One GraphQL round-trip per invocation;
+ * the query string is generated by `buildIssueTreeQuery(depth)` at call
+ * time because the children connection has no `@include`-style depth
+ * directive.
+ *
+ * Two output modes:
+ *   - **JSON** (default): nested `IssueTreeNode` shape.
+ *   - **Summary**: ASCII tree via `formatTree`.
+ *
+ * Closed-issue filtering: `--include-closed` is on by default for `tree`
+ * because the tree's value is *structural* — knowing that a child was
+ * canceled is part of the picture. Pass `--no-include-closed` to prune
+ * terminal-state branches client-side after the fetch (Linear's children
+ * connection has no top-level state filter).
+ */
+import type { Command, OptionValues } from "commander";
+export declare function setupTreeCommand(issues: Command): void;
+export declare function handleTreeCommand(issueId: string, options: OptionValues, command: Command): Promise<void>;

package/dist/commands/issues/tree.js

@@ -0,0 +1,102 @@
+/**
+ * `el-linear issues tree <ID>` (DEV-4480).
+ *
+ * Renders the parent-and-children tree of an issue to depth N (default 3,
+ * max 5 — see `MAX_TREE_DEPTH`). One GraphQL round-trip per invocation;
+ * the query string is generated by `buildIssueTreeQuery(depth)` at call
+ * time because the children connection has no `@include`-style depth
+ * directive.
+ *
+ * Two output modes:
+ *   - **JSON** (default): nested `IssueTreeNode` shape.
+ *   - **Summary**: ASCII tree via `formatTree`.
+ *
+ * Closed-issue filtering: `--include-closed` is on by default for `tree`
+ * because the tree's value is *structural* — knowing that a child was
+ * canceled is part of the picture. Pass `--no-include-closed` to prune
+ * terminal-state branches client-side after the fetch (Linear's children
+ * connection has no top-level state filter).
+ */
+import { buildIssueTreeQuery, DEFAULT_TREE_DEPTH, MAX_TREE_DEPTH, } from "../../queries/issue-tree.js";
+import { formatTree } from "../../utils/format-tree.js";
+import { createIssuesService } from "../../utils/issues-service-bootstrap.js";
+import { handleAsyncCommand, outputSuccess } from "../../utils/output.js";
+import { getRootOpts } from "../../utils/root-opts.js";
+export function setupTreeCommand(issues) {
+    issues
+        .command("tree <issueId>")
+        .description("Render the parent-and-children tree of an issue (DEV-4480). " +
+        "One GraphQL call. Depth defaults to 3 (max 5).")
+        .option("--depth <n>", `Tree depth, integer in [1, ${MAX_TREE_DEPTH}] (default ${DEFAULT_TREE_DEPTH})`, String(DEFAULT_TREE_DEPTH))
+        .option("--no-include-closed", "Prune branches whose state is Done or Canceled. By default tree " +
+        "renders all states because the tree's value is structural.")
+        .addHelpText("after", "\nExamples:" +
+        "\n  el-linear issues tree DEV-100" +
+        "\n  el-linear issues tree DEV-100 --depth 5 --format summary" +
+        "\n  el-linear issues tree DEV-100 --no-include-closed")
+        .action(handleAsyncCommand(handleTreeCommand));
+}
+export async function handleTreeCommand(issueId, options, command) {
+    const rootOpts = getRootOpts(command);
+    const { graphQLService, linearService } = await createIssuesService(rootOpts);
+    const treeOptions = options;
+    const depth = parseDepth(treeOptions.depth);
+    // commander turns `--no-include-closed` into `includeClosed: false`; the
+    // default is true (see option declaration).
+    const includeClosed = treeOptions.includeClosed !== false;
+    const resolvedId = await linearService.resolveIssueId(issueId);
+    const result = await graphQLService.rawRequest(buildIssueTreeQuery(depth), { id: resolvedId });
+    if (!result.issue) {
+        throw new Error(`Issue "${issueId}" not found`);
+    }
+    const filtered = includeClosed
+        ? result.issue
+        : pruneTerminalStates(result.issue);
+    // `--format` is a *root-program* option (see main.ts), so commander
+    // surfaces it via `command.parent.opts()` — NOT via the subcommand
+    // action's local `options` parameter. Reading from `rootOpts` mirrors
+    // the precedent in `read-shortcut.ts`'s `--field` handling.
+    // (DEV-4480 cycle-1 blocker.)
+    if (rootOpts.format === "summary") {
+        process.stdout.write(`${formatTree(filtered)}\n`);
+        return;
+    }
+    outputSuccess(filtered);
+}
+function parseDepth(raw) {
+    if (raw === undefined) {
+        return DEFAULT_TREE_DEPTH;
+    }
+    const n = Number.parseInt(raw, 10);
+    if (!Number.isInteger(n) || n < 1 || n > MAX_TREE_DEPTH) {
+        throw new Error(`--depth must be an integer in [1, ${MAX_TREE_DEPTH}]; got "${raw}".`);
+    }
+    return n;
+}
+/**
+ * Walk the tree depth-first and drop any node whose `state.type` is
+ * `completed` or `canceled`. Pure function — does not mutate the input.
+ * A pruned child takes its entire subtree with it (consistent with how
+ * `issues list --no-include-closed` excludes closed work entirely).
+ *
+ * Assumes Linear's parent → children graph stays single-parent (a tree,
+ * not a DAG). If Linear ever ships multi-parent issues, this recursion
+ * would re-emit nodes reachable via multiple paths — at that point add
+ * a `Set<string>` of seen `id`s to the walk. Today the assumption is
+ * safe. Bounded recursion: `MAX_TREE_DEPTH=5` caps the call stack at
+ * ≤6 frames (root + 5 children levels). (Cycle-1 nit.)
+ */
+function pruneTerminalStates(root) {
+    const kids = root.children?.nodes ?? [];
+    const surviving = kids
+        .filter((c) => !isTerminalState(c))
+        .map((c) => pruneTerminalStates(c));
+    return {
+        ...root,
+        children: { nodes: surviving },
+    };
+}
+function isTerminalState(node) {
+    const t = node.state?.type;
+    return t === "completed" || t === "canceled";
+}

package/dist/commands/issues.js

@@ -21,6 +21,7 @@ import { currentGitBranch, extractIssueIdentifierFromBranch, getBranchLinearIssu
 import { maybeAutoLink, prepareAutoLinkedDescription, readDescriptionFile, resolveDescription, } from "./issues/description.js";
 import { handleLinkReferencesIssue } from "./issues/link-references.js";
 import { buildIncomingRelationEntries, buildOutgoingRelationEntries, createRelations, } from "./issues/relations.js";
+import { setupTreeCommand } from "./issues/tree.js";
 import { readIssues } from "./read-shortcut.js";
 const IMAGE_EXTENSIONS = new Set([
     ".png",
@@ -160,7 +161,12 @@ async function handleListIssues(options, command) {
     }
     const rootOpts = getRootOpts(command);
     const { issuesService } = await createIssuesService(rootOpts);
-    const hasFilters = options.team ||
+    const explicitStatus = options.status ? splitList(options.status) : undefined;
+    // DEV-4478: default-exclude terminal states (Done/Canceled) unless the
+    // user passes --include-closed OR explicit --status. Explicit status
+    // wins because the user already named the workflow states they want.
+    const excludeTerminalStates = !options.includeClosed && explicitStatus === undefined;
+    const hasOtherFilters = options.team ||
         options.labels ||
         options.status ||
         options.assignee ||
@@ -169,7 +175,14 @@ async function handleListIssues(options, command) {
         options.project === false ||
         options.priority;
     const limit = parsePositiveInt(options.limit, "--limit");
-    if (hasFilters) {
+    // Route through searchIssues whenever the CLI needs to control the GraphQL
+    // state filter: any explicit filter, the default `excludeTerminalStates`,
+    // OR an explicit `--include-closed`. The last case is load-bearing —
+    // getIssues' query hard-codes `state: { type: { neq: "completed" } }`, so
+    // falling through to it on `--include-closed --no-other-filters` would
+    // silently drop Done issues, the exact opposite of the flag's intent.
+    // (DEV-4478 cycle-1.)
+    if (hasOtherFilters || excludeTerminalStates || options.includeClosed) {
         const searchArgs = {
             teamId: options.team ? resolveTeam(options.team) : undefined,
             assigneeId: options.assignee
@@ -180,7 +193,8 @@ async function handleListIssues(options, command) {
                 : undefined,
             project: resolveProjectFlag(options.project),
             labelNames: options.labels ? splitList(options.labels) : undefined,
-            status: options.status ? splitList(options.status) : undefined,
+            status: explicitStatus,
+            excludeTerminalStates,
             priority: options.priority
                 ? parsePriorityFilter(options.priority)
                 : undefined,
@@ -188,6 +202,9 @@ async function handleListIssues(options, command) {
             limit,
         };
         const result = sortIssues(await issuesService.searchIssues(searchArgs), options.sort);
+        if (excludeTerminalStates) {
+            outputWarning("excluded terminal states (Done / Canceled) by default; pass --include-closed to include them");
+        }
         warnIfTruncated(result.length, limit);
         outputIssues(result, options.format, options.fields, {
             team: options.team,
@@ -206,6 +223,11 @@ async function handleSearchIssues(query, options, command) {
     const rootOpts = getRootOpts(command);
     const { issuesService } = await createIssuesService(rootOpts);
     const limit = parsePositiveInt(options.limit, "--limit");
+    const explicitStatus = options.status ? splitList(options.status) : undefined;
+    // DEV-4478: default-exclude terminal states (Done/Canceled) unless the
+    // user passes --include-closed OR explicit --status. Explicit status
+    // wins because the user already named the workflow states they want.
+    const excludeTerminalStates = !options.includeClosed && explicitStatus === undefined;
     const searchArgs = {
         query,
         teamId: options.team ? resolveTeam(options.team) : undefined,
@@ -216,7 +238,8 @@ async function handleSearchIssues(query, options, command) {
             ? resolveMember(options.delegate)
             : undefined,
         project: resolveProjectFlag(options.project),
-        status: options.status ? splitList(options.status) : undefined,
+        status: explicitStatus,
+        excludeTerminalStates,
         labelNames: options.labels ? splitList(options.labels) : undefined,
         priority: options.priority
             ? parsePriorityFilter(options.priority)
@@ -224,6 +247,9 @@ async function handleSearchIssues(query, options, command) {
         limit,
     };
     const result = sortIssues(await issuesService.searchIssues(searchArgs), options.sort);
+    if (excludeTerminalStates) {
+        outputWarning("excluded terminal states (Done / Canceled) by default; pass --include-closed to include them");
+    }
     warnIfTruncated(result.length, limit);
     outputIssues(result, options.format, options.fields, { query });
 }
@@ -869,6 +895,10 @@ export function setupIssuesCommands(program) {
         .alias("issue")
         .description("Issue operations");
     issues.action(() => issues.help());
+    // DEV-4480: `issues tree <ID>` lives in its own file because the
+    // recursive query builder + ASCII formatter belong together and are
+    // substantial enough to warrant the split.
+    setupTreeCommand(issues);
     issues
         .command("list")
         .description("List issues.")
@@ -881,6 +911,7 @@ export function setupIssuesCommands(program) {
         .option("--labels <labels>", "filter by labels (comma-separated names)")
         .option("--label <labels>", "alias for --labels")
         .option("--status <status>", "filter by status (comma-separated, e.g. Todo,Backlog)")
+        .option("--include-closed", "include issues in terminal states (Done / Canceled). Default is to exclude them; pass this flag to see everything. Ignored when --status is set (explicit choice wins).")
         .option("--priority <priority>", "filter by priority (comma-separated: urgent,high,medium,low,none or 0-4)")
         .option("--sort <field>", "sort results (priority, status, created, updated)")
         .option("--format <format>", "output format (json, summary, table, md, csv)", "json")
@@ -895,6 +926,7 @@ export function setupIssuesCommands(program) {
         .option("--project <project>", "filter by project name or ID")
         .option("--no-project", "filter issues with no project assigned")
         .option("--status <status>", "filter by status (comma-separated)")
+        .option("--include-closed", "include issues in terminal states (Done / Canceled). Default is to exclude them; pass this flag to see everything. Ignored when --status is set (explicit choice wins).")
         .option("--labels <labels>", "filter by labels (comma-separated names)")
         .option("--label <labels>", "alias for --labels")
         .option("--priority <priority>", "filter by priority (comma-separated: urgent,high,medium,low,none or 0-4)")
@@ -965,7 +997,10 @@ export function setupIssuesCommands(program) {
         .option("--field <name>", 'Extract a single named section from the issue description (e.g. "Done when"). ' +
         "Matches H2/H3 headers and bold pseudo-headers case-insensitively. " +
         "Outputs the section text only — no JSON envelope. Single-issue only.")
-        .addHelpText("after", '\nBoth UUID and identifiers like ABC-123 are supported.\nMultiple IDs: el-linear issue get DEV-123 DEV-456 DEV-789\nExtract a section: el-linear issue read DEV-123 --field "Done when"')
+        .option("--sections <names>", 'Extract multiple named description sections in one call (comma-separated, e.g. "Done when,Out of scope"). ' +
+        "Single-issue only. Returns a JSON envelope { identifier, sections: { name -> text|null } }; missing sections appear as null + a _warnings entry. " +
+        "Sibling of --field (singular). Named --sections rather than --fields because the program already has a global --fields for output-key filtering.")
+        .addHelpText("after", '\nBoth UUID and identifiers like ABC-123 are supported.\nMultiple IDs: el-linear issue get DEV-123 DEV-456 DEV-789\nExtract a section: el-linear issue read DEV-123 --field "Done when"\nMulti-section: el-linear issue read DEV-123 --sections "Done when,Out of scope"')
         .action(handleAsyncCommand(readIssues));
     issues
         .command("update <issueId>")