@enrichlayer/el-linear 1.23.0 → 1.25.0

package/README.md

@@ -528,11 +528,92 @@ continue to accept their per-command formats too: `table`, `md`,
 `markdown`, `csv` — those go to the per-command rendering path. The
 global `summary` value works on every read/list command.
 
-`--format summary` does not compose with `--jq` (jq is JSON-only) or
-`--fields` (fields filter the JSON shape, not the rendered text). Use
+`--format summary` does not compose with `--jq` (jq is JSON-only). Use
 `--raw` together with `--format summary` to render a list envelope as a
 bare item-list rather than an envelope.
 
+#### `--fields` on `--format summary` — project additional columns
+
+`--fields` on a summary render is a **projection request**, not a
+JSON-shape filter (DEV-4750). For list outputs it sets the column set;
+for single-resource outputs it filters the labelled field block beneath
+the headline. Order is preserved: `--fields project,identifier,title`
+renders `PROJECT  ID  TITLE`.
+
+Currently wired through:
+
+| Resource | Defaults | Extras you can request |
+|----------|----------|------------------------|
+| `issues list` | `id, title, state, assignee` | `project, cycle, milestone, labels, url, priority, estimate, createdAt, updatedAt, team` |
+| `projects list` | `name, state, progress, lead` | `teams, target, url, updatedAt` |
+| `issues read` (single) | `state, assignee, project, cycle, milestone, labels, url` | `priority, estimate, created, updated` |
+| `projects read` (single) | `state, lead, teams, target, progress, url` | (filter only — no extras) |
+
+`identifier`, `id`, `title` and `name` are headline-only on single-resource summaries and are filtered out of the labelled block (they remain on the title line above). `status` is accepted as a synonym for `state`, `owner` for `assignee`, `targetDate` for `target`.
+
+```bash
+# issues list with project column (the gap that motivated DEV-4750):
+el-linear issues list --status "In Progress" --format summary \
+  --fields identifier,title,status,assignee,project
+# ID        TITLE                          STATE        ASSIGNEE    PROJECT
+# -----------------------------------------------------------------------------
+# DEV-1     Migrate auth middleware        In Progress  Alice       Auth Refactor
+# ...
+
+# projects list with teams column:
+el-linear projects list --format summary --fields name,state,progress,lead,teams
+# NAME                STATE    PROGRESS  LEAD     TEAMS
+# ---------------------------------------------------------
+# Auth Refactor       started  65%       Alice    DEV, FE
+# ...
+```
+
+Unrecognized field names are reported as a `_warnings:` line appended after the summary block (`fields_unprojectable: --format summary on issues list does not project foo, bar; ...`) — same signal scripts get on the JSON path. Resources whose summary formatter doesn't yet wire `--fields` (cycles, milestones, comments, teams, labels, users, documents, templates, attachments, releases, search results) emit the same warning and render their default summary.
+
+### Windowed metadata (`WindowedMeta`)
+
+When a command returns less than its complete result set — because it
+windowed by time, paginated, filtered, or hit a `--limit` — it should make
+that visible in the envelope's `meta` rather than leaving the consumer to
+guess. The shared output package (`@enrichlayer/el-linear/output`) exports a
+canonical `WindowedMeta` type for exactly these fields, so every CLI built on
+it uses one set of names instead of ad-hoc `_window` / `_total` / `truncated`
+keys:
+
+| Field            | Populate when…                                                        |
+| ---------------- | --------------------------------------------------------------------- |
+| `_window`        | a time/scope window was applied — `"30d"`, `"since 2026-06-01"`.      |
+| `_limit_applied` | a cap is in effect — the caller's value, or the default when omitted. |
+| `_query`         | a search / filter expression produced `data`.                         |
+| `_total`         | the total matching rows *before* windowing / limiting / filtering.    |
+| `_fetched`       | rows in *this* response (equals `meta.count` for list envelopes).     |
+| `truncated`      | `_fetched` hit `_limit_applied` and more rows exist beyond this page. |
+| `availability`   | `{status: "complete" \| "partial" \| "degraded", detail?}` — emit `degraded` when a sub-source failed, never an empty result that reads as "no hits". |
+
+All fields are optional; a command populates only the ones that apply. The
+`meta` object still admits CLI-specific counters (`_total_hits`,
+`_source_users_total`, …) alongside these, but prefer the generic field where
+one fits so cross-CLI tooling and skills can read a single shape. Skill output
+templates that show counts MUST consume `_total` / `truncated` from `meta`
+rather than counting returned rows.
+
+This convention comes from the output-transparency audit's **"Standard
+Convention"** section (`docs/output-transparency-audit-report.md` in the
+`vertical-int/tools` repo, DEV-3810); `WindowedMeta` is the shared type that
+audit recommends promoting into the envelope (DEV-4668).
+
+```ts
+import type { WindowedMeta } from "@enrichlayer/el-linear/output";
+
+// A list command echoing what it windowed and whether it clipped:
+outputList(rows, {
+  _window: "30d",
+  _limit_applied: 100,
+  _total: 247,
+  truncated: rows.length === 100,
+} satisfies WindowedMeta);
+```
+
 ### Extract a single description section: `--field`
 
 `issues read --field <name>` extracts one named section from an issue's

package/dist/commands/issue-id.js

@@ -21,7 +21,20 @@ import { handleAsyncCommand, outputSuccess } from "../utils/output.js";
 // Branch naming conventions — kept in sync with branch-name validators
 // elsewhere in the workspace. Any addition here is the single point of
 // truth that all skills rely on.
-const BRANCH_RE = /^(?:feature|fix|chore|refactor|dev)[-/]([A-Z]{2,4})-(\d+)(?:[-/](.*))?$/i;
+//
+// Accepted prefixes (DEV-4777 adds bug/spike; DEV-4660 added codex; both
+// mirror tools-repo DEV-4417):
+//   feature | fix | chore | refactor | dev   — SOP-canonical + Linear-CLI direct
+//   bug | spike                              — sanctioned Linear type labels
+//   codex                                    — Codex-authored branches (codex/<TEAM>-<N>-slug)
+// New authoring surfaces (Codex, future agent prefixes) and sanctioned Linear
+// type labels (bug, spike) get first-class issue detection so commit guards,
+// MR descriptions, and session handoff don't go dark on a branch a human
+// wouldn't even notice was prefixed differently.
+//
+// Mirror of cli/el-git/src/commands/context.ts:BRANCH_RE in the
+// vertical-int/tools repo. If you change one, change the other.
+const BRANCH_RE = /^(?:feature|fix|chore|refactor|bug|spike|dev|codex)[-/]([A-Z]{2,4})-(\d+)(?:[-/](.*))?$/i;
 export function parseBranchName(branch) {
     const m = branch.match(BRANCH_RE);
     if (!m) {

package/dist/output.d.ts

@@ -79,4 +79,4 @@
  *   redactor of its own; coupling token redaction to the output layer
  *   would make this API surface stickier than it needs to be.
  */
-export { type CliListEnvelope, getOutputFormat, handleAsyncCommand, type ListExtraMeta, type ListMeta, outputList, outputSingle, outputSuccess, outputWarning, resetWarnings, setFieldsFilter, setJqFilter, setOutputFormat, setRawMode, warnIfTruncated, } from "./utils/output.js";
+export { type CliListEnvelope, getOutputFormat, handleAsyncCommand, type ListExtraMeta, type ListMeta, outputList, outputSingle, outputSuccess, outputWarning, resetWarnings, setFieldsFilter, setJqFilter, setOutputFormat, setRawMode, type WindowedMeta, warnIfTruncated, } from "./utils/output.js";

package/dist/utils/formatters/summary.d.ts

@@ -14,10 +14,16 @@
  * pretty-print. Field ordering and labels should not change across
  * patch releases without a CHANGELOG entry.
  */
-export declare function formatIssueSummary(issue: Record<string, unknown>): string;
-export declare function formatIssueList(issues: unknown[]): string;
-export declare function formatProjectSummary(project: Record<string, unknown>): string;
-export declare function formatProjectList(projects: unknown[]): string;
+/**
+ * Drain the formatter-level `_warnings` buffer. Returns the collected
+ * warnings and resets the queue. Called by `outputSuccess` after every
+ * summary render to surface unprojectable-field hints to scripts.
+ */
+export declare function drainSummaryFieldWarnings(): string[];
+export declare function formatIssueSummary(issue: Record<string, unknown>, fields?: string[]): string;
+export declare function formatIssueList(issues: unknown[], fields?: string[]): string;
+export declare function formatProjectSummary(project: Record<string, unknown>, fields?: string[]): string;
+export declare function formatProjectList(projects: unknown[], fields?: string[]): string;
 export declare function formatCommentSummary(comment: Record<string, unknown>): string;
 export declare function formatCommentList(comments: unknown[]): string;
 export declare function formatCycleSummary(cycle: Record<string, unknown>): string;
@@ -55,11 +61,19 @@ export type ResourceKind = "issue" | "issue-list" | "project" | "project-list" |
  */
 export declare function inferKindFromPayload(value: unknown): ResourceKind;
 /**
- * Central dispatch: given a resource kind and payload, return the
- * formatted string. The payload for list kinds may be either the raw
- * array or a `{ data: [...] }` envelope — both are handled.
+ * Central dispatch: given a resource kind, payload, and optional `--fields`
+ * projection list, return the formatted string. The payload for list kinds
+ * may be either the raw array or a `{ data: [...] }` envelope — both are
+ * handled.
+ *
+ * `fields` is forwarded to formatters that wire `--fields` projection
+ * (issues, projects). For other kinds it's an opt-out path: we emit a
+ * `fields_unprojectable` warning and render defaults. The eventual
+ * direction is to wire projection through every list formatter; until
+ * then the warning gives consumers a deterministic signal instead of
+ * silently ignoring their flag.
  */
-export declare function dispatch(kind: ResourceKind, payload: unknown): string;
+export declare function dispatch(kind: ResourceKind, payload: unknown, fields?: string[]): string;
 /**
  * One-line confirmation render for the `--quiet` write path.
  *

package/dist/utils/formatters/summary.js

@@ -116,6 +116,109 @@ function joinLabels(v) {
         .filter((x) => x && x !== "—")
         .join(", ");
 }
+/**
+ * Select the ordered column set for a `--fields` request. Returns
+ * `{ columns, unprojectable }` so the caller can render and warn.
+ *
+ * Resolution order per requested name (case-insensitive):
+ *
+ * 1. Synonym lookup (`status` → `state`, `id` → `identifier`).
+ * 2. Match against a `defaults` column header.
+ * 3. Match against an `extras` entry.
+ * 4. Otherwise → `unprojectable`.
+ *
+ * The returned columns preserve the order the user requested. This is the
+ * contract: `--fields project,identifier,title` renders `PROJECT  ID  TITLE`.
+ */
+function selectColumns(projection, requested) {
+    const columns = [];
+    const unprojectable = [];
+    const synonyms = projection.synonyms ?? {};
+    const extras = projection.extras ?? {};
+    // Build a lowercased default-header lookup once.
+    const defaultByHeader = new Map();
+    for (const col of projection.defaults) {
+        defaultByHeader.set(col.header.toLowerCase(), col);
+    }
+    for (const raw of requested) {
+        const name = raw.trim().toLowerCase();
+        if (!name)
+            continue;
+        const canonical = synonyms[name] ?? name;
+        const fromDefaults = defaultByHeader.get(canonical);
+        if (fromDefaults) {
+            columns.push(fromDefaults);
+            continue;
+        }
+        const fromExtras = extras[canonical];
+        if (fromExtras) {
+            columns.push(fromExtras);
+            continue;
+        }
+        unprojectable.push(raw);
+    }
+    return { columns, unprojectable };
+}
+/**
+ * Filter the single-resource HeaderField list by user-requested field
+ * names (DEV-4750). Matches each requested name against the field's
+ * lowercased label and an optional synonym map. Unknown names are
+ * reported in `unprojectable[]`.
+ *
+ * Order of the returned fields preserves the user's request order. The
+ * implicit headline (identifier line for issues, name for projects) is
+ * the caller's responsibility — `--fields` only filters the labelled
+ * key/value block beneath it.
+ */
+function selectHeaderFields(defaults, requested, synonyms = {}) {
+    const byLabel = new Map();
+    for (const f of defaults) {
+        byLabel.set(f.label.toLowerCase(), f);
+    }
+    const fields = [];
+    const unprojectable = [];
+    for (const raw of requested) {
+        const name = raw.trim().toLowerCase();
+        if (!name)
+            continue;
+        const canonical = synonyms[name] ?? name;
+        const match = byLabel.get(canonical);
+        if (match) {
+            fields.push(match);
+        }
+        else {
+            unprojectable.push(raw);
+        }
+    }
+    return { fields, unprojectable };
+}
+/**
+ * Module-level sink for unprojectable `--fields` names surfaced from the
+ * summary formatters. The output dispatcher (`outputSuccess` in
+ * `utils/output.ts`) drains this between renders and forwards them to
+ * `outputWarning` so they ride out on the next JSON envelope's
+ * `_warnings`. Kept here rather than in output.ts so the formatter stays
+ * the single source of truth on what is and isn't projectable.
+ *
+ * Internal — consumers should call `drainSummaryFieldWarnings()`.
+ */
+const summaryFieldWarnings = [];
+function recordUnprojectable(resource, names) {
+    if (names.length === 0)
+        return;
+    summaryFieldWarnings.push(`fields_unprojectable: --format summary on ${resource} does not project ${names.join(", ")}; ` +
+        `use --format json --fields ${names.join(",")} or omit the field(s).`);
+}
+/**
+ * Drain the formatter-level `_warnings` buffer. Returns the collected
+ * warnings and resets the queue. Called by `outputSuccess` after every
+ * summary render to surface unprojectable-field hints to scripts.
+ */
+export function drainSummaryFieldWarnings() {
+    const out = [...summaryFieldWarnings];
+    summaryFieldWarnings.length = 0;
+    return out;
+}
 /**
  * Render a list of rows as a fixed-width text table with a header,
  * separator, body, and "<N> <noun>s" footer.
@@ -164,62 +267,219 @@ function renderHeader(fields) {
         .join("\n");
 }
 // ── issues ─────────────────────────────────────────────────────
-export function formatIssueSummary(issue) {
-    const identifier = s(issue.identifier);
-    const title = s(issue.title);
-    const headerLine = `${identifier}  ${title}`;
-    const fields = [
+/**
+ * Map a user-requested field name → the canonical lookup key used by
+ * `selectColumns` for the issues *list* formatter. Canonical keys are
+ * the lowercased column header (`id`, `title`, `state`, `assignee`)
+ * for defaults; extras are looked up by their key in
+ * `ISSUE_LIST_EXTRAS`.
+ *
+ * `identifier` (the JSON key) → `id` (the column header). `status` and
+ * `owner` are natural-language aliases for `state` and `assignee`.
+ *
+ * `prioritylabel` / `projectmilestone` are the raw JSON-field spellings a
+ * script author might reach for; they map to the `priority` / `milestone`
+ * column keys so the list formatter accepts the same names the
+ * single-resource formatter does (`ISSUE_SUMMARY_SYNONYMS`) — keeping the
+ * two surfaces in sync.
+ */
+const ISSUE_LIST_SYNONYMS = {
+    identifier: "id",
+    status: "state",
+    owner: "assignee",
+    prioritylabel: "priority",
+    projectmilestone: "milestone",
+};
+/**
+ * Map a user-requested field name → the canonical lowercased label used
+ * by the single-resource issue formatter. Single-resource labels are
+ * full words (`Created`, `Updated`), so `createdat` / `updatedat`
+ * (JSON-field spellings) need mapping. `status` / `owner` carry over.
+ */
+const ISSUE_SUMMARY_SYNONYMS = {
+    status: "state",
+    owner: "assignee",
+    createdat: "created",
+    updatedat: "updated",
+    prioritylabel: "priority",
+    projectmilestone: "milestone",
+};
+function buildIssueHeaderFields(issue) {
+    return [
         { label: "State", value: getName(issue.state) },
         { label: "Assignee", value: getName(issue.assignee) },
         { label: "Project", value: getName(issue.project) },
         { label: "Cycle", value: getName(issue.cycle) },
         { label: "Milestone", value: getName(issue.projectMilestone) },
         { label: "Labels", value: joinLabels(issue.labels) },
+        { label: "Priority", value: s(issue.priorityLabel ?? issue.priority) },
+        { label: "Estimate", value: s(issue.estimate) },
+        { label: "Created", value: s(issue.createdAt) },
+        { label: "Updated", value: s(issue.updatedAt) },
         { label: "URL", value: s(issue.url) },
     ];
-    const header = renderHeader(fields);
+}
+export function formatIssueSummary(issue, fields) {
+    const identifier = s(issue.identifier);
+    const title = s(issue.title);
+    const headerLine = `${identifier}  ${title}`;
+    const allFields = buildIssueHeaderFields(issue);
+    let headerFields;
+    if (fields && fields.length > 0) {
+        // `identifier` / `title` make up the implicit headline above —
+        // strip them from the user's request so a `--fields title,state`
+        // doesn't try to render "Title:" inside the labelled block.
+        const filtered = fields.filter((f) => {
+            const name = f.trim().toLowerCase();
+            return name !== "identifier" && name !== "id" && name !== "title";
+        });
+        const selected = selectHeaderFields(allFields, filtered, ISSUE_SUMMARY_SYNONYMS);
+        recordUnprojectable("issue", selected.unprojectable);
+        headerFields = selected.fields;
+    }
+    else {
+        // Default issue summary historically omits priority / estimate / dates —
+        // keep that surface stable unless the caller asks for those columns.
+        const defaultLabels = new Set([
+            "state",
+            "assignee",
+            "project",
+            "cycle",
+            "milestone",
+            "labels",
+            "url",
+        ]);
+        headerFields = allFields.filter((f) => defaultLabels.has(f.label.toLowerCase()));
+    }
+    const header = renderHeader(headerFields);
     const body = clipDescription(issue.description);
     const parts = [headerLine, header];
     if (body)
         parts.push("", body);
     return parts.filter((p) => p !== "").join("\n");
 }
-export function formatIssueList(issues) {
-    return renderTable(issues.map((raw) => asObj(raw) ?? {}), [
-        { header: "ID", minWidth: 2, extract: (i) => s(i.identifier) },
-        {
-            header: "TITLE",
-            minWidth: 5,
-            maxWidth: TITLE_TRUNC,
-            extract: (i) => s(i.title),
-        },
-        { header: "STATE", minWidth: 5, extract: (i) => getName(i.state) },
-        {
-            header: "ASSIGNEE",
-            minWidth: 8,
-            extract: (i) => getName(i.assignee),
+const ISSUE_LIST_DEFAULTS = [
+    { header: "ID", minWidth: 2, extract: (i) => s(i.identifier) },
+    {
+        header: "TITLE",
+        minWidth: 5,
+        maxWidth: TITLE_TRUNC,
+        extract: (i) => s(i.title),
+    },
+    { header: "STATE", minWidth: 5, extract: (i) => getName(i.state) },
+    {
+        header: "ASSIGNEE",
+        minWidth: 8,
+        extract: (i) => getName(i.assignee),
+    },
+];
+const ISSUE_LIST_EXTRAS = {
+    project: {
+        header: "PROJECT",
+        minWidth: 7,
+        maxWidth: 40,
+        extract: (i) => getName(i.project),
+    },
+    cycle: {
+        header: "CYCLE",
+        minWidth: 5,
+        maxWidth: 20,
+        extract: (i) => getName(i.cycle),
+    },
+    milestone: {
+        header: "MILESTONE",
+        minWidth: 9,
+        maxWidth: 30,
+        extract: (i) => getName(i.projectMilestone),
+    },
+    labels: {
+        header: "LABELS",
+        minWidth: 6,
+        maxWidth: 40,
+        extract: (i) => joinLabels(i.labels),
+    },
+    url: {
+        header: "URL",
+        minWidth: 3,
+        maxWidth: 60,
+        extract: (i) => s(i.url),
+    },
+    priority: {
+        header: "PRIORITY",
+        minWidth: 8,
+        extract: (i) => s(i.priorityLabel ?? i.priority),
+    },
+    estimate: {
+        header: "ESTIMATE",
+        minWidth: 8,
+        extract: (i) => s(i.estimate),
+    },
+    createdat: {
+        header: "CREATED",
+        minWidth: 7,
+        extract: (i) => s(i.createdAt).slice(0, 10),
+    },
+    updatedat: {
+        header: "UPDATED",
+        minWidth: 7,
+        extract: (i) => s(i.updatedAt).slice(0, 10),
+    },
+    team: {
+        header: "TEAM",
+        minWidth: 4,
+        extract: (i) => {
+            // issues carry team as either {key, name} or a bare key string.
+            const team = i.team;
+            const o = asObj(team);
+            if (o)
+                return s(o.key ?? o.name);
+            return s(team);
         },
-    ], { emptyText: "(no issues)", itemNoun: "issue" });
+    },
+};
+export function formatIssueList(issues, fields) {
+    const rows = issues.map((raw) => asObj(raw) ?? {});
+    let columns = ISSUE_LIST_DEFAULTS;
+    if (fields && fields.length > 0) {
+        const selected = selectColumns({
+            defaults: ISSUE_LIST_DEFAULTS,
+            extras: ISSUE_LIST_EXTRAS,
+            synonyms: ISSUE_LIST_SYNONYMS,
+        }, fields);
+        recordUnprojectable("issues list", selected.unprojectable);
+        // If every requested name was unprojectable, fall back to defaults
+        // so the user still sees something useful with the warning attached.
+        columns =
+            selected.columns.length > 0 ? selected.columns : ISSUE_LIST_DEFAULTS;
+    }
+    return renderTable(rows, columns, {
+        emptyText: "(no issues)",
+        itemNoun: "issue",
+    });
 }
 // ── projects ───────────────────────────────────────────────────
-export function formatProjectSummary(project) {
+const PROJECT_SYNONYMS = {
+    targetdate: "target",
+};
+function joinTeamKeys(value) {
+    if (!Array.isArray(value) || value.length === 0)
+        return "";
+    return value
+        .map((team) => {
+        const o = asObj(team);
+        return o ? s(o.key ?? o.name) : s(team);
+    })
+        .filter((x) => x && x !== "—")
+        .join(", ");
+}
+export function formatProjectSummary(project, fields) {
     const name = s(project.name);
     const headerLine = name;
-    const teams = (() => {
-        const t = project.teams;
-        if (!Array.isArray(t) || t.length === 0)
-            return "";
-        return t
-            .map((team) => {
-            const o = asObj(team);
-            return o ? s(o.key ?? o.name) : s(team);
-        })
-            .join(", ");
-    })();
+    const teams = joinTeamKeys(project.teams);
     const progress = typeof project.progress === "number"
         ? `${Math.round(project.progress * 100)}%`
         : "";
-    const fields = [
+    const allFields = [
         { label: "State", value: s(project.state) },
         { label: "Lead", value: getName(project.lead) },
         { label: "Teams", value: teams },
@@ -227,7 +487,20 @@ export function formatProjectSummary(project) {
         { label: "Progress", value: progress },
         { label: "URL", value: s(project.url) },
     ];
-    const header = renderHeader(fields);
+    let headerFields;
+    if (fields && fields.length > 0) {
+        // `name` is the implicit headline above; drop it from the request
+        // so a user passing `--fields name,teams` doesn't render "Name:" in
+        // the labelled block beneath.
+        const filtered = fields.filter((f) => f.trim().toLowerCase() !== "name");
+        const selected = selectHeaderFields(allFields, filtered, PROJECT_SYNONYMS);
+        recordUnprojectable("project", selected.unprojectable);
+        headerFields = selected.fields;
+    }
+    else {
+        headerFields = allFields;
+    }
+    const header = renderHeader(headerFields);
     const body = clipDescription(project.description);
     const parts = [headerLine, header];
     if (body)
@@ -237,18 +510,58 @@ export function formatProjectSummary(project) {
 function pct(value) {
     return typeof value === "number" ? `${Math.round(value * 100)}%` : "—";
 }
-export function formatProjectList(projects) {
-    return renderTable(projects.map((raw) => asObj(raw) ?? {}), [
-        {
-            header: "NAME",
-            minWidth: 4,
-            maxWidth: TITLE_TRUNC,
-            extract: (p) => s(p.name),
-        },
-        { header: "STATE", minWidth: 5, extract: (p) => s(p.state) },
-        { header: "PROGRESS", minWidth: 8, extract: (p) => pct(p.progress) },
-        { header: "LEAD", minWidth: 4, extract: (p) => getName(p.lead) },
-    ], { emptyText: "(no projects)", itemNoun: "project" });
+const PROJECT_LIST_DEFAULTS = [
+    {
+        header: "NAME",
+        minWidth: 4,
+        maxWidth: TITLE_TRUNC,
+        extract: (p) => s(p.name),
+    },
+    { header: "STATE", minWidth: 5, extract: (p) => s(p.state) },
+    { header: "PROGRESS", minWidth: 8, extract: (p) => pct(p.progress) },
+    { header: "LEAD", minWidth: 4, extract: (p) => getName(p.lead) },
+];
+const PROJECT_LIST_EXTRAS = {
+    teams: {
+        header: "TEAMS",
+        minWidth: 5,
+        maxWidth: 30,
+        extract: (p) => joinTeamKeys(p.teams),
+    },
+    target: {
+        header: "TARGET",
+        minWidth: 6,
+        extract: (p) => s(p.targetDate),
+    },
+    url: {
+        header: "URL",
+        minWidth: 3,
+        maxWidth: 60,
+        extract: (p) => s(p.url),
+    },
+    updatedat: {
+        header: "UPDATED",
+        minWidth: 7,
+        extract: (p) => s(p.updatedAt).slice(0, 10),
+    },
+};
+export function formatProjectList(projects, fields) {
+    const rows = projects.map((raw) => asObj(raw) ?? {});
+    let columns = PROJECT_LIST_DEFAULTS;
+    if (fields && fields.length > 0) {
+        const selected = selectColumns({
+            defaults: PROJECT_LIST_DEFAULTS,
+            extras: PROJECT_LIST_EXTRAS,
+            synonyms: PROJECT_SYNONYMS,
+        }, fields);
+        recordUnprojectable("projects list", selected.unprojectable);
+        columns =
+            selected.columns.length > 0 ? selected.columns : PROJECT_LIST_DEFAULTS;
+    }
+    return renderTable(rows, columns, {
+        emptyText: "(no projects)",
+        itemNoun: "project",
+    });
 }
 // ── comments ───────────────────────────────────────────────────
 export function formatCommentSummary(comment) {
@@ -694,11 +1007,30 @@ function inferListKind(items) {
     return "generic";
 }
 /**
- * Central dispatch: given a resource kind and payload, return the
- * formatted string. The payload for list kinds may be either the raw
- * array or a `{ data: [...] }` envelope — both are handled.
+ * Resources where `--fields` projection is wired through to the formatter
+ * (DEV-4750). For any other kind, passing `--fields` records a
+ * deterministic unprojectable warning and renders the default summary.
  */
-export function dispatch(kind, payload) {
+const FIELDS_PROJECTED = new Set([
+    "issue",
+    "issue-list",
+    "project",
+    "project-list",
+]);
+/**
+ * Central dispatch: given a resource kind, payload, and optional `--fields`
+ * projection list, return the formatted string. The payload for list kinds
+ * may be either the raw array or a `{ data: [...] }` envelope — both are
+ * handled.
+ *
+ * `fields` is forwarded to formatters that wire `--fields` projection
+ * (issues, projects). For other kinds it's an opt-out path: we emit a
+ * `fields_unprojectable` warning and render defaults. The eventual
+ * direction is to wire projection through every list formatter; until
+ * then the warning gives consumers a deterministic signal instead of
+ * silently ignoring their flag.
+ */
+export function dispatch(kind, payload, fields) {
     const obj = asObj(payload);
     const list = (() => {
         if (Array.isArray(payload))
@@ -707,15 +1039,19 @@ export function dispatch(kind, payload) {
             return obj.data;
         return null;
     })();
+    const hasFields = Boolean(fields && fields.length > 0);
+    if (hasFields && !FIELDS_PROJECTED.has(kind)) {
+        recordUnprojectable(kind === "generic" ? "this resource" : kind, fields);
+    }
     switch (kind) {
         case "issue":
-            return formatIssueSummary((obj ?? {}));
+            return formatIssueSummary((obj ?? {}), fields);
         case "issue-list":
-            return formatIssueList(list ?? []);
+            return formatIssueList(list ?? [], fields);
         case "project":
-            return formatProjectSummary((obj ?? {}));
+            return formatProjectSummary((obj ?? {}), fields);
         case "project-list":
-            return formatProjectList(list ?? []);
+            return formatProjectList(list ?? [], fields);
         case "comment":
             return formatCommentSummary((obj ?? {}));
         case "comment-list":

package/dist/utils/output.d.ts

@@ -11,6 +11,65 @@ export declare function setFieldsFilter(fields: string[] | null): void;
 export declare function setOutputFormat(format: OutputFormat): void;
 /** @internal Test seam — consumers should not depend on the format state. */
 export declare function getOutputFormat(): OutputFormat;
+/**
+ * Standard windowing / pagination / truncation metadata for any command
+ * that does not return its complete result set in one response.
+ *
+ * This is the canonical `WindowedMeta` type referenced by the
+ * output-transparency audit (DEV-3810 → DEV-4668). It promotes the
+ * `el-user usage` reference convention into the shared envelope so every
+ * consuming CLI uses the same field names instead of inventing ad-hoc
+ * `_window` / `_total` / `truncated` keys. The motivating principle:
+ * **every piece of data between a database and a decision-maker (human or
+ * LLM) should make its scope, limits, and assumptions visible in the
+ * output** — a consumer should never have to read source to interpret
+ * data correctly.
+ *
+ * All fields are optional: a command populates only the ones that apply.
+ * Because `ListMeta` / `ListExtraMeta` still carry an open
+ * `Record<string, unknown>` index, a CLI may also add its own
+ * domain-specific counters (`_total_hits`, `_indices_queried`,
+ * `_source_users_total`, …) alongside these — but where a generic field
+ * fits, prefer it so cross-CLI tooling and skills can read one shape.
+ *
+ * When to populate each field:
+ * - `_window` — the time/scope window applied, e.g. `"30d"`, `"12 months"`,
+ *   `"since 2026-06-01"`.
+ * - `_limit_applied` — the cap actually in effect (the value the caller
+ *   passed, or the command's default when they passed nothing).
+ * - `_query` — the search / filter expression applied to produce `data`.
+ * - `_total` — total matching rows *before* windowing / limiting /
+ *   filtering. Lets a consumer report "showing N of `_total`".
+ * - `_fetched` — how many rows are in *this* response (distinct from
+ *   `_total`). For list envelopes this equals `meta.count`.
+ * - `truncated` — `true` when `_fetched` hit `_limit_applied` and more
+ *   rows exist beyond this page. Skills MUST consume this rather than
+ *   counting returned rows to decide whether output is complete.
+ * - `availability` — per-response (or per-source) completeness signal.
+ *   Emit `{status: "degraded", detail}` when a sub-source failed (e.g. a
+ *   Slack timeout in an aggregator) rather than collapsing to an empty
+ *   result indistinguishable from "no hits".
+ */
+export interface WindowedMeta {
+    /** Time/scope window applied, e.g. `"30d"`, `"since 2026-06-01"`. */
+    _window?: string;
+    /** The cap actually in effect (caller's value, or the default). */
+    _limit_applied?: number;
+    /** The search / filter expression applied to produce `data`. */
+    _query?: string;
+    /** Total matching rows before windowing / limiting / filtering. */
+    _total?: number;
+    /** Rows in this response (equals `meta.count` for list envelopes). */
+    _fetched?: number;
+    /** `true` when `_fetched` hit `_limit_applied` — more rows exist. */
+    truncated?: boolean;
+    /** Per-response completeness signal; mirrors the `el-user` convention. */
+    availability?: {
+        status: "complete" | "partial" | "degraded";
+        /** Human-readable reason, e.g. `"result reached row cap 100"`. */
+        detail?: string;
+    };
+}
 /**
  * Resource-specific extra metadata that may be added to a list response
  * alongside the canonical `count` (e.g. `query` on search, `team` on
@@ -18,12 +77,16 @@ export declare function getOutputFormat(): OutputFormat;
  * accidentally pass a string `count` and have it silently overridden;
  * the only way to set `count` is via `data.length` inside `outputList`.
  *
+ * Intersected with {@link WindowedMeta} so the standard windowing fields
+ * (`_total`, `truncated`, `_window`, …) are typed when present, while the
+ * open `Record<string, unknown>` index still admits CLI-specific keys.
+ *
  * Implementation note: `count?: never` together with `Record<string, unknown>`
  * lets TypeScript accept any other key while disallowing the literal
  * `count` key. The `never`-typed property is impossible to assign, which
  * is what we want for the "no count here" contract.
  */
-export type ListExtraMeta = Record<string, unknown> & {
+export type ListExtraMeta = Record<string, unknown> & WindowedMeta & {
     count?: never;
 };
 /**
@@ -34,6 +97,10 @@ export type ListExtraMeta = Record<string, unknown> & {
  * read it both for emptiness checks (`.meta.count == 0`) and for the
  * actual magnitude (e.g. logging "found N issues"). A boolean isEmpty
  * would lose the magnitude signal, so `count: number` stays.
+ *
+ * The open `Record<string, unknown>` index admits the {@link WindowedMeta}
+ * fields a windowed list echoes (`_total`, `truncated`, `_window`, …);
+ * those are typed at the write site via {@link ListExtraMeta}.
  */
 export interface ListMeta extends Record<string, unknown> {
     count: number;

package/dist/utils/output.js

@@ -1,5 +1,5 @@
 import { execFileSync } from "node:child_process";
-import { dispatch as dispatchSummary, formatLine, inferKindFromPayload, } from "./formatters/summary.js";
+import { dispatch as dispatchSummary, drainSummaryFieldWarnings, formatLine, inferKindFromPayload, } from "./formatters/summary.js";
 import { logger } from "./logger.js";
 import { sanitizeForLog } from "./sanitize-for-log.js";
 const warningBuffer = [];
@@ -56,9 +56,14 @@ function filterFields(obj, fields) {
  * the heuristic would fall through to "generic", silently breaking
  * the issue-list table. Caching the pre-filter shape keeps the
  * formatter accurate regardless of how the user pared the JSON.
+ *
+ * `fields` (when set) is forwarded to the formatter as a projection
+ * request (DEV-4750). For summary the JSON-shape `filterFields` is a
+ * no-op — the formatter needs the full object to extract nested values
+ * like `project.name` or `teams[].key`.
  */
-function emitSummary(payload, kind) {
-    logger.info(dispatchSummary(kind, payload));
+function emitSummary(payload, kind, fields) {
+    logger.info(dispatchSummary(kind, payload, fields ?? undefined));
 }
 /**
  * Typed wrapper around `outputSuccess` for list responses — builds the
@@ -95,17 +100,7 @@ export function outputSingle(data) {
     outputSuccess(data);
 }
 export function outputSuccess(data) {
-    const warnings = drainWarnings();
-    let output;
-    if (warnings.length > 0 &&
-        data !== null &&
-        typeof data === "object" &&
-        !Array.isArray(data)) {
-        output = { ...data, _warnings: warnings };
-    }
-    else {
-        output = data;
-    }
+    let output = data;
     // Capture the kind from the original envelope shape BEFORE --raw /
     // --fields stripping. Otherwise filtering away signature fields (e.g.
     // `title` on an issue) breaks shape inference and the summary
@@ -115,9 +110,13 @@ export function outputSuccess(data) {
     // precedence on the write path and independent of --raw / --fields / --jq
     // (those reshape the payload the flag exists to avoid) — so we emit from
     // the full pre-filter object, otherwise `--fields identifier` would strip
-    // the state/url formatLine needs and break shape inference.
+    // the state/url formatLine needs and break shape inference. Drain any
+    // buffered warnings to preserve pre-DEV-4750 behavior (they were
+    // silently dropped on the quiet path; the contract is "one line only").
     if (quietMode) {
         logger.info(formatLine(output));
+        drainWarnings();
+        drainSummaryFieldWarnings();
         return;
     }
     // --raw: unwrap { data: [...] } to just the array
@@ -130,8 +129,12 @@ export function outputSuccess(data) {
             output = obj.data;
         }
     }
-    // --fields: filter object keys (applies to array items or flat objects)
-    if (fieldsFilter) {
+    // --fields on summary format is a *projection request* — the formatter
+    // consumes it directly to extend/replace its column set (DEV-4750). The
+    // JSON-shape `filterFields` step would otherwise strip nested values
+    // (project.name, teams[].key) the formatter needs to render. Skip the
+    // JSON filter when summary is active and let the formatter do the work.
+    if (fieldsFilter && outputFormat !== "summary") {
         if (Array.isArray(output)) {
             output = filterFields(output, fieldsFilter);
         }
@@ -145,13 +148,35 @@ export function outputSuccess(data) {
             }
         }
     }
-    // summary format takes the post-raw / post-fields value and renders it
-    // as a human-readable block. We bypass the jq path because jq is a
-    // JSON-shape filter — it doesn't compose with text output.
+    // summary format takes the post-raw value and renders it as a
+    // human-readable block. We bypass the jq path because jq is a
+    // JSON-shape filter — it doesn't compose with text output. The
+    // formatter records any unprojectable `--fields` names; we drain
+    // them after dispatch and append them as `_warnings: …` lines so
+    // the signal is visible without breaking the text contract.
     if (outputFormat === "summary") {
-        emitSummary(output, inferredKind);
+        emitSummary(output, inferredKind, fieldsFilter);
+        const summaryWarnings = [
+            ...drainWarnings(),
+            ...drainSummaryFieldWarnings(),
+        ];
+        if (summaryWarnings.length > 0) {
+            for (const w of summaryWarnings) {
+                logger.info(`_warnings: ${w}`);
+            }
+        }
         return;
     }
+    // JSON path: drain buffered warnings (including any
+    // fields_unprojectable surfaced from a prior dispatch) and embed
+    // them as `_warnings` on the envelope.
+    const warnings = [...drainWarnings(), ...drainSummaryFieldWarnings()];
+    if (warnings.length > 0 &&
+        output !== null &&
+        typeof output === "object" &&
+        !Array.isArray(output)) {
+        output = { ...output, _warnings: warnings };
+    }
     if (jqFilter) {
         const json = JSON.stringify(output);
         // Normalize common shell-escape artifacts (zsh history expansion)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enrichlayer/el-linear",
-  "version": "1.23.0",
+  "version": "1.25.0",
   "description": "A pragmatic CLI for Linear.app — deterministic team/label/member resolution, structured issue validation, configurable term enforcement, and a GraphQL escape hatch.",
   "main": "dist/main.js",
   "types": "dist/main.d.ts",