@enrichlayer/el-linear 1.38.2 → 1.40.0

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

@@ -371,7 +371,7 @@ Complete ALL items before creating any issue:
 - [ ] **Assignee** — ask user if unclear (`el-linear users list --active`).
 - [ ] **Project** — always ask user, never guess (`el-linear projects list`).
 - [ ] **Labels** — exactly 1 type label + 1–2 domain labels (see Label Taxonomy below).
-- [ ] **Title** — action verb matching the type label (see Title Verb Convention), sentence case, specific scope.
+- [ ] **Title** — action verb matching the type label (see Title Verb Convention), sentence case, specific scope, **plain-language and jargon-free** (see Title Readability).
 - [ ] **Description** — 2–4 sentences with context and intent, formatted with **bold** and `inline code`.
 - [ ] **"Why we need this"** — genuine motivation, not a restatement of the title.
 
@@ -447,7 +447,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`.
+- **Body/description/content from a file** — `issues create`/`update` take `--description-file <path>`; `comments create`/`update` take `--body-file <path>`; **`projects create`/`update` take `--content-file <path>`** (the project's full markdown **content**, not its short `description` — see the two-field gotcha under *Project Management Gotchas*). 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). The inline and file flags are **mutually exclusive** (passing both errors); file-sourced bodies get the same auto-link / auto-mention treatment as inline text.
 
 ### Output format
 
@@ -497,6 +497,27 @@ Title must start with a verb that matches the type label:
 - `spike` → Research, Investigate, Explore, Evaluate, Audit, Benchmark
 - `refactor` → Refactor, Restructure, Extract, Decouple, Simplify
 
+### Title Readability — plain language, jargon in the body
+
+**The title says what problem is being solved, in words a non-author can read.** The title is the shared surface — a teammate scanning the board, a manager triaging priority, a future picker deciding what to pick up. If it only parses for the person who wrote it that week, that whole audience is locked out. This applies to **MR/PR titles too** — they front the same board.
+
+**Keep the mechanism detail — function names, env-var constants, symbol soup — in the description, not the title.** Moving it into the body doesn't lose precision; it puts precision where the reader who opens the issue actually wants it. The title carries the *problem*; the body carries the *how*.
+
+- **Lead with the problem or outcome**, not the internal symbol at the center of it.
+- **Move code identifiers, env-var constants, and file/function names into the body**, under a `## …` heading where they read as helpful context.
+- **Proper nouns that ARE the clearest name stay.** The name of a tool, service, or protocol a teammate would recognize (a CLI name, `Vault`, `CI`, `OAuth`) is not jargon — don't paraphrase it into vagueness. The test is "would a teammate recognize this?", not "does it contain a lowercase token?".
+- **Don't overcorrect into mush.** "Fix the thing that was broken" is worse than a jargon title — specificity still matters, just express it in problem terms.
+
+Before → after:
+
+| ❌ Jargon title | ✅ Plain-language title |
+|---|---|
+| `parseTokenBucket drops refill when lastRefillTs is unset` | Fix rate limiter losing its refill allowance after an idle period |
+| `AUTH_SESSION_TTL mismatch logs out users early in refreshSession` | Fix users getting logged out before their session length expires |
+| `Extract validateEntry into shared pkg (3 hand-rolled copies)` | Extract the duplicated entry validator into a shared package |
+
+The mechanism (`parseTokenBucket`, `AUTH_SESSION_TTL`, `refreshSession`, the three copies) still gets stated — in the **description**, where it reads as context instead of a barrier.
+
 ### Rules
 
 - **Create missing labels liberally** — `el-linear labels create "my-label" --team ENG`.

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

@@ -23,6 +23,9 @@ import type { LinearService } from "../../utils/linear-service.js";
 /**
  * Read description from a file path or stdin ("-").
  * Avoids shell escaping issues when descriptions contain special characters.
+ *
+ * Delegates to the shared reader so `projects --content-file` (DEV-6033), which
+ * is specified to behave identically, cannot drift from this one.
  */
 export declare function readDescriptionFile(filePath: string): string;
 /**

package/dist/commands/issues/description.js

@@ -16,27 +16,24 @@
  * Extracted from `commands/issues.ts` (ALL-938) so that file can
  * focus on commander wiring + handlers.
  */
-import fs from "node:fs";
 import { loadConfig } from "../../config/config.js";
 import { UPDATE_ISSUE_MUTATION } from "../../queries/issues.js";
 import { autoLinkReferences, } from "../../utils/auto-link-references.js";
 import { normalizeInlineTextInput } from "../../utils/inline-text-input.js";
 import { extractIssueReferences } from "../../utils/issue-reference-extractor.js";
 import { wrapIssueReferencesAsLinks } from "../../utils/issue-reference-wrapper.js";
+import { readTextInputFile } from "../../utils/text-input-file.js";
 import { validateReferences } from "../../utils/validate-references.js";
 import { getWorkspaceUrlKey } from "../../utils/workspace-url.js";
 /**
  * Read description from a file path or stdin ("-").
  * Avoids shell escaping issues when descriptions contain special characters.
+ *
+ * Delegates to the shared reader so `projects --content-file` (DEV-6033), which
+ * is specified to behave identically, cannot drift from this one.
  */
 export function readDescriptionFile(filePath) {
-    if (filePath === "-") {
-        return fs.readFileSync(0, "utf8").trim();
-    }
-    if (!fs.existsSync(filePath)) {
-        throw new Error(`Description file not found: ${filePath}`);
-    }
-    return fs.readFileSync(filePath, "utf8").trim();
+    return readTextInputFile(filePath, "Description");
 }
 /**
  * Resolve the description from --description, --description-file, or

package/dist/commands/projects.d.ts

@@ -5,4 +5,28 @@ export declare function resolveProjectStateFilter(options: OptionValues): {
     states?: string[];
     excludeStates?: string[];
 };
+/**
+ * Resolve the project body from `--content <markdown>` or `--content-file <path>`
+ * (DEV-6033). The two are sources for the same field, so accepting both would
+ * silently drop one — we REJECT up front instead.
+ *
+ * That matches `comments --body-file` and `project-updates --body-file`, and it
+ * deliberately DIVERGES from `issues --description-file`, which documents a
+ * precedence (`--description-file` > `--description`) and therefore lets the file
+ * silently win when both are passed. Rejecting is the better contract — a caller
+ * who passes both has a bug, and telling them beats guessing — but do not describe
+ * this as "mirroring" issues: it is not, and a false claim about a sibling's
+ * mechanism outlives the person who wrote it.
+ *
+ * Returns `undefined` only when NEITHER flag was passed, which is what lets
+ * `projects update` keep distinguishing "leave content alone" from "clear it"
+ * (`--content ""` yields `""`, and `"" !== undefined`, so it still reaches the
+ * mutation — the same distinction `hasOption` drew before).
+ *
+ * Inline `--content` is passed through verbatim, exactly as it was before this
+ * flag existed. It is deliberately NOT run through `normalizeInlineTextInput`:
+ * that would newly rewrite `\n` inside an existing caller's `--content` string,
+ * a behavior change to a shipped flag that this issue does not ask for.
+ */
+export declare function resolveProjectContent(options: OptionValues): string | undefined;
 export declare function setupProjectsCommands(program: Command): void;

package/dist/commands/projects.js

@@ -8,6 +8,7 @@ import { logger } from "../utils/logger.js";
 import { handleAsyncCommand, outputSuccess, outputWarning, } from "../utils/output.js";
 import { effectiveOption, getRootOpts } from "../utils/root-opts.js";
 import { renderCsv, renderFixedWidthTable, renderMarkdownTable, } from "../utils/table-formatter.js";
+import { readTextInputFile } from "../utils/text-input-file.js";
 import { isUuid } from "../utils/uuid.js";
 import { parsePositiveInt, splitList } from "../utils/validators.js";
 const VALID_PROJECT_STATES = new Set([
@@ -232,6 +233,43 @@ function formatTeamsOutput(projectUpdate) {
 function hasOption(options, key) {
     return options[key] !== undefined;
 }
+/**
+ * Resolve the project body from `--content <markdown>` or `--content-file <path>`
+ * (DEV-6033). The two are sources for the same field, so accepting both would
+ * silently drop one — we REJECT up front instead.
+ *
+ * That matches `comments --body-file` and `project-updates --body-file`, and it
+ * deliberately DIVERGES from `issues --description-file`, which documents a
+ * precedence (`--description-file` > `--description`) and therefore lets the file
+ * silently win when both are passed. Rejecting is the better contract — a caller
+ * who passes both has a bug, and telling them beats guessing — but do not describe
+ * this as "mirroring" issues: it is not, and a false claim about a sibling's
+ * mechanism outlives the person who wrote it.
+ *
+ * Returns `undefined` only when NEITHER flag was passed, which is what lets
+ * `projects update` keep distinguishing "leave content alone" from "clear it"
+ * (`--content ""` yields `""`, and `"" !== undefined`, so it still reaches the
+ * mutation — the same distinction `hasOption` drew before).
+ *
+ * Inline `--content` is passed through verbatim, exactly as it was before this
+ * flag existed. It is deliberately NOT run through `normalizeInlineTextInput`:
+ * that would newly rewrite `\n` inside an existing caller's `--content` string,
+ * a behavior change to a shipped flag that this issue does not ask for.
+ */
+export function resolveProjectContent(options) {
+    const hasInline = typeof options.content === "string";
+    const hasFile = typeof options.contentFile === "string";
+    if (hasInline && hasFile) {
+        throw new Error("--content and --content-file are mutually exclusive — pass one or the other");
+    }
+    if (hasFile) {
+        return readTextInputFile(options.contentFile, "Content");
+    }
+    if (hasInline) {
+        return options.content;
+    }
+    return undefined;
+}
 function flattenProjectUpdate(projectUpdate) {
     if (!projectUpdate.project) {
         throw new Error("Failed to update project");
@@ -345,6 +383,11 @@ async function handleRemoveTeam(projectNameOrId, teamInput, options, command) {
     });
 }
 async function handleCreateProject(name, options, command) {
+    // Resolve the body BEFORE the create mutation. An unreadable --content-file
+    // (or --content alongside it) must fail while nothing has been created yet —
+    // resolving after the create would leave an orphan project behind and then
+    // throw, which is the worst of both outcomes.
+    const content = resolveProjectContent(options);
     const rootOpts = getRootOpts(command);
     const graphQLService = await createGraphQLService(rootOpts);
     // Step 1: Check for duplicate projects (case-insensitive)
@@ -376,10 +419,10 @@ async function handleCreateProject(name, options, command) {
     }
     const project = createResult.projectCreate.project;
     // Step 4: Set content if provided (separate mutation — Linear API quirk)
-    if (options.content) {
+    if (content) {
         await graphQLService.rawRequest(UPDATE_PROJECT_MUTATION, {
             id: project.id,
-            input: { content: options.content },
+            input: { content },
         });
     }
     const teamList = project.teams.nodes.map((t) => t.key).join(", ");
@@ -465,11 +508,15 @@ async function handleUpdateProject(projectNameOrId, options, command) {
     if (hasOption(options, "description")) {
         input.description = options.description;
     }
-    if (hasOption(options, "content")) {
-        input.content = options.content;
+    // `undefined` means neither --content nor --content-file was passed. An
+    // explicit `--content ""` resolves to "" and still lands here, so clearing a
+    // project's body keeps working exactly as it did under `hasOption`.
+    const content = resolveProjectContent(options);
+    if (content !== undefined) {
+        input.content = content;
     }
     if (Object.keys(input).length === 0) {
-        throw new Error("Nothing to update. Pass at least one of --name, --description, or --content.");
+        throw new Error("Nothing to update. Pass at least one of --name, --description, --content, or --content-file.");
     }
     const rootOpts = getRootOpts(command);
     const graphQLService = await createGraphQLService(rootOpts);
@@ -494,6 +541,7 @@ export function setupProjectsCommands(program) {
         .option("--team <teams>", "comma-separated team keys (e.g., FE,DEV)")
         .option("-d, --description <text>", "short summary (max 255 chars, shown in lists)")
         .option("--content <markdown>", "full markdown body (shown in project panel)")
+        .option("--content-file <path>", "read the markdown body from a file (or '-' for stdin); mutually exclusive with --content")
         .option("--force", "create even if a project with the same name exists")
         .action(handleAsyncCommand(handleCreateProject));
     projects
@@ -514,6 +562,7 @@ export function setupProjectsCommands(program) {
         .option("--name <name>", "project name")
         .option("-d, --description <text>", "short summary (max 255 chars, shown in lists)")
         .option("--content <markdown>", "full markdown body (shown in project panel)")
+        .option("--content-file <path>", "read the markdown body from a file (or '-' for stdin); mutually exclusive with --content")
         .action(handleAsyncCommand(handleUpdateProject));
     projects
         .command("list")

package/dist/utils/text-input-file.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Read the body for a `--*-file` flag: a path on disk, or `-` for stdin.
+ *
+ * These flags exist to keep large markdown bodies away from the shell. The
+ * workaround they replace — `--content "$(cat body.md)"` — hands the file's
+ * bytes to the shell first, so backticks, `$`, and nested quotes inside the
+ * markdown get interpolated before the CLI ever sees them. Reading the path
+ * ourselves means the bytes arrive exactly as authored.
+ *
+ * For the same reason the content is used verbatim: no escape-sequence
+ * normalization. That is `normalizeInlineTextInput`'s job for the *inline*
+ * flags, where a user typing `\n` at a shell prompt means a newline. In a file,
+ * a literal `\n` inside a fenced code block is content, and rewriting it would
+ * corrupt the document.
+ *
+ * `label` names the subject in the not-found error, so each flag reports itself
+ * ("Description file not found: …", "Content file not found: …").
+ *
+ * Single source of truth for `issues --description-file` and `projects
+ * --content-file` (DEV-6033) — the two are specified to behave identically, so
+ * they share one implementation rather than two that drift.
+ */
+export declare function readTextInputFile(filePath: string, label: string): string;

package/dist/utils/text-input-file.js

@@ -0,0 +1,32 @@
+import fs from "node:fs";
+/**
+ * Read the body for a `--*-file` flag: a path on disk, or `-` for stdin.
+ *
+ * These flags exist to keep large markdown bodies away from the shell. The
+ * workaround they replace — `--content "$(cat body.md)"` — hands the file's
+ * bytes to the shell first, so backticks, `$`, and nested quotes inside the
+ * markdown get interpolated before the CLI ever sees them. Reading the path
+ * ourselves means the bytes arrive exactly as authored.
+ *
+ * For the same reason the content is used verbatim: no escape-sequence
+ * normalization. That is `normalizeInlineTextInput`'s job for the *inline*
+ * flags, where a user typing `\n` at a shell prompt means a newline. In a file,
+ * a literal `\n` inside a fenced code block is content, and rewriting it would
+ * corrupt the document.
+ *
+ * `label` names the subject in the not-found error, so each flag reports itself
+ * ("Description file not found: …", "Content file not found: …").
+ *
+ * Single source of truth for `issues --description-file` and `projects
+ * --content-file` (DEV-6033) — the two are specified to behave identically, so
+ * they share one implementation rather than two that drift.
+ */
+export function readTextInputFile(filePath, label) {
+    if (filePath === "-") {
+        return fs.readFileSync(0, "utf8").trim();
+    }
+    if (!fs.existsSync(filePath)) {
+        throw new Error(`${label} file not found: ${filePath}`);
+    }
+    return fs.readFileSync(filePath, "utf8").trim();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enrichlayer/el-linear",
-  "version": "1.38.2",
+  "version": "1.40.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",