@enrichlayer/el-linear 1.38.0 → 1.38.1

package/README.md

@@ -271,8 +271,11 @@ itself: `el-linear teams list --raw | jq '.[] | {key, id}'`, etc.
 
 ### Gate telemetry (optional)
 
-`issues create` has a duplicate-detection gate (on by default) and an opt-in
-[SOP-label parent gate](./docs/configuration.md#sop-label-parent-gate-validationsoplabelparentgate).
+`issues create` has a duplicate-detection gate (on by default), an opt-in
+[SOP-label parent gate](./docs/configuration.md#sop-label-parent-gate-validationsoplabelparentgate),
+and an opt-in
+[goal-completion gate](./docs/configuration.md#goal-completion-gate-validationgoalcompletiongate)
+(requires a falsifiable "Done when" / acceptance-criteria section).
 el-linear can record each gate's fire/override decision to a local JSONL file so
 you can measure its **override-rate** and tell whether it's too aggressive. It is
 **off by default** and writes nothing unless you opt in (e.g.

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

@@ -121,6 +121,20 @@ el-linear comments list DEV-123 --format json 2>&1 | python3 -c "import json,sys
 `#comment-<hash>`. `comments list --format summary` includes each comment id
 so you can copy it straight into `comments read`.
 
+### Attachment reads and downloads
+
+List attachments first, then use the attachment ID or exact title. Text files
+can be streamed directly; binary files require an explicit download path.
+
+```bash
+el-linear attachments list DEV-123 --format summary
+el-linear attachments read DEV-123 <attachment-id>
+el-linear attachments download DEV-123 <attachment-id> --output /tmp/report.pdf
+```
+
+Do not reconstruct authenticated `curl` commands from attachment URLs. The
+attachment commands use the active Linear profile and reject binary stdout.
+
 ### Terse write confirmations: `-q, --quiet`
 
 `issues create|update` and `comments create|update` accept `-q, --quiet`, which prints a single machine-stable confirmation line instead of the full JSON envelope — no need to `grep` the result for the identifier / state / url:

package/dist/commands/attachments.js

@@ -1,9 +1,28 @@
+import { basename } from "node:path";
 import { createFileService } from "../utils/file-service.js";
 import { createGraphQLAttachmentsService } from "../utils/graphql-attachments-service.js";
 import { createLinearService } from "../utils/linear-service.js";
 import { handleAsyncCommand, outputSuccess } from "../utils/output.js";
 import { getRootOpts } from "../utils/root-opts.js";
 import { parsePositiveInt } from "../utils/validators.js";
+function selectAttachment(attachments, selector) {
+    const idMatch = attachments.find((attachment) => attachment.id === selector);
+    if (idMatch)
+        return idMatch;
+    const matches = attachments.filter((attachment) => attachment.title === selector || attachment.url === selector);
+    if (matches.length === 1)
+        return matches[0];
+    if (matches.length > 1) {
+        throw new Error(`Multiple attachments are titled "${selector}"; select one by attachment ID.`);
+    }
+    throw new Error(`Attachment "${selector}" was not found. Run attachments list <issueId> to see attachment IDs and titles.`);
+}
+async function resolveAttachment(issueId, selector, rootOpts) {
+    const linearService = await createLinearService(rootOpts);
+    const resolvedIssueId = await linearService.resolveIssueId(issueId);
+    const attachmentsService = await createGraphQLAttachmentsService(rootOpts);
+    return selectAttachment(await attachmentsService.listAttachments(resolvedIssueId), selector);
+}
 export function setupAttachmentsCommands(program) {
     const attachments = program
         .command("attachments")
@@ -45,6 +64,47 @@ export function setupAttachmentsCommands(program) {
         const data = allAttachments.slice(0, limit);
         outputSuccess({ data, meta: { count: data.length } });
     }));
+    attachments
+        .command("read <issueId> <attachment>")
+        .description("Write a text attachment to stdout by ID, title, or URL.")
+        .action(handleAsyncCommand(async (issueId, selector, _options, command) => {
+        const rootOpts = getRootOpts(command);
+        const attachment = await resolveAttachment(issueId, selector, rootOpts);
+        const fileService = await createFileService(rootOpts);
+        const result = await fileService.readTextFile(attachment.url);
+        if (!result.success)
+            throw new Error(result.error);
+        process.stdout.write(result.content);
+        if (!result.content.endsWith("\n"))
+            process.stdout.write("\n");
+    }));
+    attachments
+        .command("download <issueId> <attachment>")
+        .description("Download an attachment by ID, title, or URL.")
+        .option("--output <path>", "output file path")
+        .option("--overwrite", "overwrite existing file", false)
+        .action(handleAsyncCommand(async (issueId, selector, options, command) => {
+        const rootOpts = getRootOpts(command);
+        const attachment = await resolveAttachment(issueId, selector, rootOpts);
+        const fileService = await createFileService(rootOpts);
+        const titleBasename = attachment.title
+            ? basename(attachment.title)
+            : undefined;
+        const defaultOutput = titleBasename && ![".", ".."].includes(titleBasename)
+            ? titleBasename
+            : undefined;
+        const result = await fileService.downloadFile(attachment.url, {
+            output: options.output ?? defaultOutput,
+            overwrite: options.overwrite,
+        });
+        if (!result.success)
+            throw new Error(result.error);
+        outputSuccess({
+            success: true,
+            filePath: result.filePath,
+            message: `Attachment downloaded to ${result.filePath}`,
+        });
+    }));
     attachments
         .command("delete <attachmentId>")
         .description("Delete an attachment.")

package/dist/commands/issues.js

@@ -1,6 +1,7 @@
 import { execFileSync } from "node:child_process";
 import { loadConfig } from "../config/config.js";
 import { enrichProjectResolverError, enrichValidationErrors, } from "../config/error-enrichment.js";
+import { evaluateGoalCompletion, formatGoalCompletionBlock, getGoalCompletionGateConfig, } from "../config/goal-completion-validation.js";
 import { enforceValidation, validateIssueCreation, } from "../config/issue-validation.js";
 import { resolveAssignee, resolveLabels, resolveMemberWithRegistry, resolveTeam, } from "../config/resolver.js";
 import { formatSopParentBlock, getSopLabelGateConfig, hasSopLabel, isUnresolvableReferenceError, } from "../config/sop-label-validation.js";
@@ -340,7 +341,12 @@ async function withProjectResolverEnrichment(fn, options, services) {
         throw err;
     }
 }
-async function resolveCreateInputs(title, options, rootOpts) {
+async function resolveCreateInputs(title, options, rootOpts, 
+// Pre-resolved description, threaded in so this validation path does NOT
+// call resolveDescription() itself — on the `--description-file -` (stdin)
+// path a second read drains the pipe to "" (DEV-5920 cycle-2). Resolve
+// happens exactly once in handleCreateIssue and the value flows here.
+resolvedDescription) {
     const config = loadConfig();
     enforceTerms([title, options.description], { strict: options.strict });
     // Effective assignee: explicit --assignee wins; --no-assignee (commander
@@ -369,10 +375,9 @@ async function resolveCreateInputs(title, options, rootOpts) {
     const hasFromTemplate = typeof options.fromTemplate === "string" && options.fromTemplate;
     if (!options.skipValidation && !hasFromTemplate) {
         const rawLabels = options.labels ? splitList(options.labels) : null;
-        const description = resolveDescription(options);
         const validationResult = validateIssueCreation({
             labels: rawLabels,
-            description: description || undefined,
+            description: resolvedDescription || undefined,
             title,
             assignee: effectiveAssignee,
             project: options.project,
@@ -699,11 +704,84 @@ async function enforceSopLabelParent(labels, options, issuesService) {
     // any unresolvable refs so a typo reads differently from a real non-SOP parent.
     await decide("no-sop-parent", unresolvableRefs.length > 0 ? unresolvableRefs : undefined);
 }
+/**
+ * DEV-5920: create-time goal-completion gate. Checks the description for a
+ * "Done when" (or equivalent) section containing at least one falsifiable
+ * criterion — the deterministic form of the concrete-goals rule (RFC-0027
+ * discussion): a goal a later session can't mechanically verify has no
+ * terminal state to converge on.
+ *
+ * OPT-IN and two-mode: dormant unless `validation.goalCompletionGate` is
+ * `"warn"` (stderr warning, creation proceeds — recorded as `advisory`) or
+ * `"block"` (throws — recorded as `blocked`), mirroring the DEV-5378 SOP gate
+ * on config plumbing and the DEV-5590 advisory tier on outcomes. Bypassed by
+ * `--skip-validation` (blanket, emits nothing) and the narrow
+ * `--allow-vague-goal` (which records an `overridden` gate event on a
+ * would-fire, mirroring `--allow-duplicate`). Purely local — no network, so it
+ * runs before the service-backed gates and has no fail-open branch.
+ */
+async function enforceGoalCompletion(description, options) {
+    if (options.skipValidation) {
+        return;
+    }
+    const { mode, headers } = getGoalCompletionGateConfig();
+    if (mode === "off") {
+        return;
+    }
+    const evaluation = evaluateGoalCompletion(description, headers);
+    if (evaluation.ok) {
+        return;
+    }
+    // Record the decision so `el-telemetry gates` can compute override-rate,
+    // mirroring the dup gate (DEV-4834): `overridden` when the caller passed
+    // --allow-vague-goal, `advisory` in warn mode, `blocked` when we stop.
+    const gateEvent = { gate: "issues-create-goal-completion" };
+    if (options.allowVagueGoal) {
+        await emitGateEvent("el-linear", "issues create", {
+            ...gateEvent,
+            outcome: "overridden",
+        });
+        return;
+    }
+    const message = formatGoalCompletionBlock({
+        reason: evaluation.reason,
+        headers,
+        sectionHeader: evaluation.reason === "vague-section" ? evaluation.header : undefined,
+    });
+    if (mode === "warn") {
+        await emitGateEvent("el-linear", "issues create", {
+            ...gateEvent,
+            outcome: "advisory",
+        });
+        outputWarning(message);
+        return;
+    }
+    await emitGateEvent("el-linear", "issues create", {
+        ...gateEvent,
+        outcome: "blocked",
+    });
+    throw new Error(`Issue creation blocked: ${message}`);
+}
 async function handleCreateIssue(title, options, command) {
     const rootOpts = getRootOpts(command);
-    const { teamInput, teamId, assigneeId, delegateId, labelIds, status, subscriberIds, priority, } = await resolveCreateInputs(title ?? "", options, rootOpts);
+    // DEV-5920 (cycle-2): resolve the description exactly ONCE, before anything
+    // else. On create, resolveDescription would otherwise run three times —
+    // field validation (inside resolveCreateInputs), the body build, and the
+    // goal-completion gate. With `--description-file -` each call does
+    // fs.readFileSync(fd 0), and a stdin pipe only yields data on the FIRST
+    // read — later reads drain to "". That silently dropped a piped body and
+    // made the gate see an empty description (spurious block/warn). Resolving
+    // once here and threading the value through fixes all three reads. This
+    // single resolve also enforces the --template / --description-file
+    // mutual-exclusivity guard (it lives in resolveDescription). Kept as a lone
+    // resolve rather than round-tripping through options.description because
+    // resolveDescription returns file bodies verbatim (no inline-escape
+    // normalization) — re-resolving an inline copy would corrupt a file that
+    // intentionally contains backslash sequences.
+    const rawDescription = resolveDescription(options);
+    const { teamInput, teamId, assigneeId, delegateId, labelIds, status, subscriberIds, priority, } = await resolveCreateInputs(title ?? "", options, rootOpts, rawDescription);
     const uploadResults = await uploadAttachmentsIfNeeded(options, rootOpts);
-    const descriptionWithAttachments = buildDescriptionWithAttachments(resolveDescription(options) || "", uploadResults);
+    const descriptionWithAttachments = buildDescriptionWithAttachments(rawDescription ?? "", uploadResults);
     // Append messageFooter (config or --footer flag) so auto-link picks up any
     // issue refs in the footer too. --no-footer skips both flag and config.
     // Commander parses --no-footer as `options.footer === false`.
@@ -713,6 +791,21 @@ async function handleCreateIssue(title, options, command) {
         footer: explicitFooter,
         noFooter,
     }) ?? "";
+    // DEV-5920: goal-completion gate. Opt-in (dormant unless
+    // validation.goalCompletionGate is "warn"/"block"). Runs on the raw resolved
+    // description — not the composed one — so an attachment link or a configured
+    // messageFooter (which routinely carries digits/URLs) can't satisfy the
+    // falsifiability check on the author's behalf. Purely local, so it runs
+    // before the service-backed gates. Skipped on the --from-template path when
+    // no local description override is present: the description is instantiated
+    // server-side from the template, invisible to a client-side check (same gap
+    // as the dup gate on a template-resolved title).
+    {
+        const hasFromTemplate = typeof options.fromTemplate === "string" && options.fromTemplate;
+        if (!hasFromTemplate || rawDescription) {
+            await enforceGoalCompletion(rawDescription ?? "", options);
+        }
+    }
     const { graphQLService, linearService, issuesService } = await createIssuesService(rootOpts);
     // DEV-4823: deterministic duplicate-detection gate. Runs before the create
     // POST, searches the title's salient keywords (including closed issues),
@@ -1308,9 +1401,10 @@ export function setupIssuesCommands(program) {
         .option("--due-date <date>", "due date (YYYY-MM-DD)")
         .option("--checkout", "create and checkout a git branch named after the issue")
         .option("--no-claim", "with --checkout, skip assigning the issue to the current Linear user and moving it to the first started state")
-        .option("--skip-validation", "skip all validation (labels, description, assignee, project, duplicate detection, SOP-parent gate)")
+        .option("--skip-validation", "skip all validation (labels, description, assignee, project, duplicate detection, SOP-parent gate, goal-completion gate)")
         .option("--allow-duplicate", "silence the duplicate-detection hard block and create even if a near-identical issue already exists (DEV-5590: only matters at/above the hard-block threshold — below it the gate is advisory-only and never blocks)")
         .option("--allow-unparented-sop", "skip the SOP-label parent gate and create an SOP-labeled issue without a parent SOP")
+        .option("--allow-vague-goal", 'skip the goal-completion gate and create even without a falsifiable "Done when" / acceptance-criteria section')
         .option("--no-auto-link", "skip auto-linking issue references found in the description")
         .option("--footer <text>", "text appended to the description (overrides config.messageFooter)")
         .option("--no-footer", "skip the configured messageFooter for this issue")

package/dist/config/config.d.ts

@@ -95,6 +95,26 @@ export interface ElLinearConfig {
          * for the `sopLabelParentGate` check. Defaults to `["SOP"]`.
          */
         sopLabels?: string[];
+        /**
+         * OPT-IN goal-completion gate (DEV-5920). When `"warn"` or `"block"`,
+         * `issues create` checks the description for a goal-completion section
+         * ("Done when" / "Acceptance criteria" / … — see `goalSectionHeaders`)
+         * containing at least one falsifiable criterion (a command, a threshold
+         * number, an artifact path, an exit-code assertion, or a "verifiable
+         * via X" phrase). `"warn"` prints a stderr warning; `"block"` stops
+         * creation. Defaults to off (absent/`false`) — el-linear is
+         * MIT/open-source and a fresh install must not be surprised by a new
+         * refusal (the EL shared team config opts in). Bypass a single create
+         * with `--allow-vague-goal`.
+         */
+        goalCompletionGate?: false | "warn" | "block";
+        /**
+         * Section header names (matched case-insensitively, `##`/`###`/bold
+         * pseudo-header forms) accepted as the goal-completion section for the
+         * `goalCompletionGate` check. Defaults to `["Done when", "Done-when",
+         * "Acceptance criteria", "Success criteria"]`.
+         */
+        goalSectionHeaders?: string[];
     };
     /**
      * Optional override for the Linear workspace URL key (the part after

package/dist/config/goal-completion-validation.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Goal-completion ("Done when") validation — DEV-5920.
+ *
+ * A create-time gate that checks the issue description for a goal-completion
+ * section ("Done when", "Acceptance criteria", "Success criteria", …) that
+ * contains at least one FALSIFIABLE criterion — something a later session can
+ * mechanically verify (a command with an expected result, a threshold number,
+ * a named artifact path, an exit-code/status assertion, or an explicit
+ * "verifiable via X" phrase). A section made only of bare quality adjectives
+ * ("improved", "better", "cleaner", "faster") gives the implementing agent no
+ * terminal state to converge on, which is the concrete-goals failure mode this
+ * gate encodes (RFC-0027 discussion). Mirrors the DEV-4823 duplicate-detection
+ * gate and the DEV-5378 SOP-label parent gate.
+ *
+ * OPT-IN by design. el-linear is MIT and published on npm; most installs are
+ * not Enrich Layer and must not be surprised by a new refusal. The gate is
+ * dormant unless `validation.goalCompletionGate` is set to `"warn"` or
+ * `"block"` (the EL workspace flips it on in its shared team config). Section
+ * matching reuses the `extractField` header semantics (`##`/`###` ATX headers
+ * and `**bold**` pseudo-headers, case-insensitive, trailing colons stripped)
+ * so the gate accepts exactly what `issues read --field "Done when"` can later
+ * extract.
+ */
+/**
+ * Default section headers accepted as the goal-completion section, matched
+ * with `extractField` semantics (case-insensitive, `##`/`###`/`**bold**`
+ * forms, trailing colons stripped). Overridable via
+ * `config.validation.goalSectionHeaders`.
+ */
+export declare const DEFAULT_GOAL_SECTION_HEADERS: string[];
+/** Gate mode: dormant, stderr warning, or hard block. */
+export type GoalCompletionGateMode = "off" | "warn" | "block";
+export interface GoalCompletionGateConfig {
+    /**
+     * The mode in effect. OPT-IN: `"off"` unless validation is not turned off
+     * AND `goalCompletionGate` is explicitly `"warn"` or `"block"`.
+     */
+    mode: GoalCompletionGateMode;
+    /** The section headers in effect (config override or {@link DEFAULT_GOAL_SECTION_HEADERS}). */
+    headers: string[];
+}
+/**
+ * Resolve the goal-completion-gate config from the merged el-linear config.
+ *
+ * The gate is dormant by default. It activates only when validation isn't
+ * disabled (`validation.enabled !== false`) AND the operator has explicitly
+ * set `validation.goalCompletionGate` to `"warn"` or `"block"`. Any other
+ * value (absent, `false`, a typo) resolves to `"off"` — a misconfigured gate
+ * must fail dormant, never blocking. An absent or empty `goalSectionHeaders`
+ * falls back to {@link DEFAULT_GOAL_SECTION_HEADERS}.
+ */
+export declare function getGoalCompletionGateConfig(): GoalCompletionGateConfig;
+/**
+ * Does the section text contain at least one falsifiable criterion?
+ * See {@link FALSIFIABLE_PROXY_RES} for what counts. An empty/whitespace
+ * section trivially fails — a bare header is not a criterion.
+ */
+export declare function hasFalsifiableCriterion(sectionText: string): boolean;
+export type GoalCompletionEvaluation = {
+    ok: true;
+    header: string;
+} | {
+    ok: false;
+    reason: "no-section";
+} | {
+    ok: false;
+    reason: "vague-section";
+    header: string;
+};
+/**
+ * Evaluate a description against the goal-completion rule. Headers are tried
+ * in **configured list order**, not document order — the first header in
+ * `headers` that is present in the description decides the outcome, even if a
+ * later-listed header appears earlier in the body. This is intentional: the
+ * list order encodes the operator's preferred canonical header, so the block
+ * message names the header they'd rather authors use. A present-but-vague
+ * section is reported as `vague-section` with the header that matched, so the
+ * error can point at the exact section rather than a generic "missing".
+ */
+export declare function evaluateGoalCompletion(description: string, headers?: string[]): GoalCompletionEvaluation;
+/**
+ * Render the human/agent-facing block emitted when the gate fires. `reason`
+ * distinguishes "no goal-completion section at all" from "section present but
+ * nothing falsifiable in it", so the message points at the exact fix. Names
+ * the rule and the `--allow-vague-goal` escape hatch.
+ */
+export declare function formatGoalCompletionBlock(opts: {
+    reason: "no-section" | "vague-section";
+    headers: string[];
+    /** The header that matched, when reason is `vague-section`. */
+    sectionHeader?: string;
+}): string;

package/dist/config/goal-completion-validation.js

@@ -0,0 +1,158 @@
+/**
+ * Goal-completion ("Done when") validation — DEV-5920.
+ *
+ * A create-time gate that checks the issue description for a goal-completion
+ * section ("Done when", "Acceptance criteria", "Success criteria", …) that
+ * contains at least one FALSIFIABLE criterion — something a later session can
+ * mechanically verify (a command with an expected result, a threshold number,
+ * a named artifact path, an exit-code/status assertion, or an explicit
+ * "verifiable via X" phrase). A section made only of bare quality adjectives
+ * ("improved", "better", "cleaner", "faster") gives the implementing agent no
+ * terminal state to converge on, which is the concrete-goals failure mode this
+ * gate encodes (RFC-0027 discussion). Mirrors the DEV-4823 duplicate-detection
+ * gate and the DEV-5378 SOP-label parent gate.
+ *
+ * OPT-IN by design. el-linear is MIT and published on npm; most installs are
+ * not Enrich Layer and must not be surprised by a new refusal. The gate is
+ * dormant unless `validation.goalCompletionGate` is set to `"warn"` or
+ * `"block"` (the EL workspace flips it on in its shared team config). Section
+ * matching reuses the `extractField` header semantics (`##`/`###` ATX headers
+ * and `**bold**` pseudo-headers, case-insensitive, trailing colons stripped)
+ * so the gate accepts exactly what `issues read --field "Done when"` can later
+ * extract.
+ */
+import { extractField } from "../utils/extract-field.js";
+import { loadConfig } from "./config.js";
+/**
+ * Default section headers accepted as the goal-completion section, matched
+ * with `extractField` semantics (case-insensitive, `##`/`###`/`**bold**`
+ * forms, trailing colons stripped). Overridable via
+ * `config.validation.goalSectionHeaders`.
+ */
+export const DEFAULT_GOAL_SECTION_HEADERS = [
+    "Done when",
+    "Done-when",
+    "Acceptance criteria",
+    "Success criteria",
+];
+/**
+ * Resolve the goal-completion-gate config from the merged el-linear config.
+ *
+ * The gate is dormant by default. It activates only when validation isn't
+ * disabled (`validation.enabled !== false`) AND the operator has explicitly
+ * set `validation.goalCompletionGate` to `"warn"` or `"block"`. Any other
+ * value (absent, `false`, a typo) resolves to `"off"` — a misconfigured gate
+ * must fail dormant, never blocking. An absent or empty `goalSectionHeaders`
+ * falls back to {@link DEFAULT_GOAL_SECTION_HEADERS}.
+ */
+export function getGoalCompletionGateConfig() {
+    const validation = loadConfig().validation;
+    const raw = validation?.goalCompletionGate;
+    const mode = validation?.enabled !== false && (raw === "warn" || raw === "block")
+        ? raw
+        : "off";
+    const headers = validation?.goalSectionHeaders && validation.goalSectionHeaders.length > 0
+        ? validation.goalSectionHeaders
+        : DEFAULT_GOAL_SECTION_HEADERS;
+    return { mode, headers };
+}
+/**
+ * Falsifiability proxies — any single match makes the section pass. Each is a
+ * cheap textual stand-in for "a later session can mechanically check this":
+ *
+ * - **command** — inline code or a fenced block (`` `pnpm test` `` and its
+ *   expected output live in code spans by Markdown convention).
+ * - **number** — a digit anywhere in the section: thresholds ("under 200ms",
+ *   "95%"), counts ("all 12 tests"), issue/artifact ids. Deliberately
+ *   permissive — the failure mode this gate targets is a section with NO
+ *   number/command/artifact at all, not a weak number.
+ * - **artifact path** — a bare filename with a code-adjacent extension
+ *   (`foo.ts`, `report.json` — this also matches the file segment inside a
+ *   longer path like `src/utils/foo.ts`), or an ANCHORED slash-path (leading
+ *   `./`, `../`, `/`, or `~/`) for extension-less dirs like `./scripts/run`.
+ *   The anchor requirement is deliberate: an un-anchored two-segment
+ *   `a/b` pattern over-fires on English prose ("and/or", "read/write",
+ *   "client/server"), so a real relative artifact path must either carry a
+ *   file extension or start with a path anchor to count.
+ * - **exit/status assertion** — "exits non-zero", "exit code 0", "tests
+ *   pass", "CI green", "returns nonzero".
+ * - **verifiable-via phrase** — "verifiable via/by/with/through X".
+ */
+const FALSIFIABLE_PROXY_RES = [
+    // Inline code span or a fenced code block opener.
+    /`[^`\n]+`/,
+    /^ {0,3}(?:`{3,}|~{3,})/m,
+    // Threshold number / percentage / count.
+    /\d/,
+    // Artifact path — a filename with a code-adjacent extension (also fires on
+    // the file segment of a longer path), OR an anchored slash-path for
+    // extension-less dirs. The anchor (`./` `../` `/` `~/`) is required so a
+    // bare `a/b` doesn't over-fire on prose like "and/or" / "read/write".
+    /\b[\w-]+\.(?:ts|tsx|js|jsx|mjs|cjs|json|md|mdx|ya?ml|sh|css|html|txt|csv|toml|sql|py|go|rs|lock)\b/i,
+    /(?:^|[\s("'[])(?:\.{1,2}\/|~\/|\/)[\w.-]+(?:\/[\w.-]+)*/m,
+    // Exit-code / status assertion.
+    /\bexit(?:s|ed)?\s+(?:code\s+|status\s+)?(?:non-?zero|zero|\d+)\b/i,
+    /\bexit\s+(?:code|status)\b/i,
+    /\breturns?\s+non-?zero\b/i,
+    /\b(?:test|tests|suite|ci|pipeline|lint|typecheck|build|check|checks)\s+(?:is\s+|are\s+|stays?\s+|go(?:es)?\s+)?(?:pass(?:es|ing)?|green|fail(?:s|ing)?|red)\b/i,
+    // Explicit "verifiable via X" escape phrase.
+    /\bverifi(?:able|ed)\s+(?:via|by|with|through)\b/i,
+];
+/**
+ * Does the section text contain at least one falsifiable criterion?
+ * See {@link FALSIFIABLE_PROXY_RES} for what counts. An empty/whitespace
+ * section trivially fails — a bare header is not a criterion.
+ */
+export function hasFalsifiableCriterion(sectionText) {
+    if (!sectionText || sectionText.trim().length === 0) {
+        return false;
+    }
+    return FALSIFIABLE_PROXY_RES.some((re) => re.test(sectionText));
+}
+/**
+ * Evaluate a description against the goal-completion rule. Headers are tried
+ * in **configured list order**, not document order — the first header in
+ * `headers` that is present in the description decides the outcome, even if a
+ * later-listed header appears earlier in the body. This is intentional: the
+ * list order encodes the operator's preferred canonical header, so the block
+ * message names the header they'd rather authors use. A present-but-vague
+ * section is reported as `vague-section` with the header that matched, so the
+ * error can point at the exact section rather than a generic "missing".
+ */
+export function evaluateGoalCompletion(description, headers = DEFAULT_GOAL_SECTION_HEADERS) {
+    for (const header of headers) {
+        const section = extractField(description, header);
+        if (section !== null) {
+            return hasFalsifiableCriterion(section)
+                ? { ok: true, header }
+                : { ok: false, reason: "vague-section", header };
+        }
+    }
+    return { ok: false, reason: "no-section" };
+}
+/**
+ * Render the human/agent-facing block emitted when the gate fires. `reason`
+ * distinguishes "no goal-completion section at all" from "section present but
+ * nothing falsifiable in it", so the message points at the exact fix. Names
+ * the rule and the `--allow-vague-goal` escape hatch.
+ */
+export function formatGoalCompletionBlock(opts) {
+    const headerList = opts.headers.join(", ");
+    let head;
+    if (opts.reason === "no-section") {
+        head =
+            `Issue description has no goal-completion section (looked for: ${headerList}).\n` +
+                `  Add a "${opts.headers[0]}" section stating how completion will be verified.\n`;
+    }
+    else {
+        head =
+            `The "${opts.sectionHeader}" section contains no falsifiable criterion.\n` +
+                '  Bare quality adjectives ("improved", "better", "cleaner", "faster") give the\n' +
+                "  implementing session no terminal state to converge on.\n";
+    }
+    const criteria = "  At least one criterion must be mechanically checkable: a command with its\n" +
+        "  expected exit/output, a threshold number or percentage, a named artifact path,\n" +
+        '  an exit-code/status assertion, or a "verifiable via X" phrase.\n';
+    const hatch = "  If the goal is intentionally open-ended, re-run with --allow-vague-goal.";
+    return head + criteria + hatch;
+}

package/dist/types/linear.d.ts

@@ -223,6 +223,15 @@ export type FileDownloadResult = {
     error: string;
     statusCode?: number;
 };
+export type FileReadResult = {
+    success: true;
+    content: string;
+    contentType: string;
+} | {
+    success: false;
+    error: string;
+    statusCode?: number;
+};
 export type FileUploadResult = {
     success: true;
     assetUrl: string;

package/dist/utils/file-service.d.ts

@@ -1,5 +1,5 @@
 import type { LinearCredential } from "../auth/linear-credential.js";
-import type { FileDownloadResult, FileUploadResult } from "../types/linear.js";
+import type { FileDownloadResult, FileReadResult, FileUploadResult } from "../types/linear.js";
 /**
  * Constructor arg for `FileService`. Re-exported alias of the shared
  * `LinearCredential` union (`{ apiKey } | { oauthToken }`). See
@@ -10,6 +10,8 @@ export type FileServiceAuth = LinearCredential;
 export declare class FileService {
     private readonly authHeader;
     constructor(auth: FileServiceAuth);
+    private fetchUpload;
+    readTextFile(url: string): Promise<FileReadResult>;
     downloadFile(url: string, options?: {
         output?: string;
         overwrite?: boolean;

package/dist/utils/file-service.js

@@ -47,6 +47,58 @@ export class FileService {
     constructor(auth) {
         this.authHeader = buildAuthHeader(auth);
     }
+    async fetchUpload(url) {
+        const urlObj = new URL(url);
+        const headers = {};
+        if (!urlObj.searchParams.has("signature")) {
+            headers.Authorization = this.authHeader;
+        }
+        return fetch(url, { method: "GET", headers });
+    }
+    async readTextFile(url) {
+        if (!isLinearUploadUrl(url)) {
+            return {
+                success: false,
+                error: "URL must be from uploads.linear.app domain",
+            };
+        }
+        try {
+            const response = await this.fetchUpload(url);
+            if (!response.ok) {
+                return {
+                    success: false,
+                    error: `HTTP ${response.status}: ${response.statusText}`,
+                    statusCode: response.status,
+                };
+            }
+            const contentType = (response.headers.get("content-type") ?? "")
+                .split(";", 1)[0]
+                .toLowerCase();
+            const isText = contentType.startsWith("text/") ||
+                [
+                    "application/json",
+                    "application/xml",
+                    "application/javascript",
+                ].includes(contentType);
+            if (!isText) {
+                return {
+                    success: false,
+                    error: `Attachment is not text (${contentType || "unknown content type"}); use attachments download instead.`,
+                };
+            }
+            return {
+                success: true,
+                content: await response.text(),
+                contentType,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
     async downloadFile(url, options = {}) {
         if (!isLinearUploadUrl(url)) {
             return {
@@ -68,13 +120,7 @@ export class FileService {
             }
         }
         try {
-            const urlObj = new URL(url);
-            const isSignedUrl = urlObj.searchParams.has("signature");
-            const headers = {};
-            if (!isSignedUrl) {
-                headers.Authorization = this.authHeader;
-            }
-            const response = await fetch(url, { method: "GET", headers });
+            const response = await this.fetchUpload(url);
             if (!response.ok) {
                 return {
                     success: false,

package/dist/utils/graphql-issues-service.d.ts

@@ -209,6 +209,7 @@ export declare class GraphQLIssuesService {
     startIssue(issueId: string): Promise<StartIssueResult>;
     claimIssue(issueId: string): Promise<ClaimIssueResult>;
     updateIssue(args: UpdateIssueArgs, labelMode?: string): Promise<LinearIssue>;
+    private updateIssueImpl;
     archiveIssue(issueId: string): Promise<IssueArchiveOperationResult>;
     deleteIssue(issueId: string, options?: {
         permanentlyDelete?: boolean;
@@ -216,6 +217,7 @@ export declare class GraphQLIssuesService {
     private extractMilestoneNodes;
     private executeUpdateMutation;
     createIssue(args: CreateIssueArgs): Promise<LinearIssue>;
+    private createIssueImpl;
     /**
      * Folds the `@include`-gated `projectsByName` / `projectsById` aliases
      * from a create batch response into the single `projects` field the

package/dist/utils/graphql-issues-service.js

@@ -28,6 +28,31 @@ function extractSummaryText(summary) {
     walk(summary.content);
     return parts.length > 0 ? parts.join("") : undefined;
 }
+/**
+ * FE-926: Linear's description-content store can end up in a corrupted state
+ * for a specific issue — observed on FE-921, where a description saved
+ * cleanly at creation was empty ~1 minute later with no issue-history trace,
+ * and every subsequent write attempt raised this same raw GraphQL error
+ * against a *different* DocumentContent id each time. It can surface from
+ * any call that touches the issue's description, including a plain
+ * batch-resolve read (not just the create/update mutation itself), so
+ * `updateIssue`/`createIssue` wrap their whole body rather than a single
+ * call site. Retrying does not self-heal — the raw backend message is
+ * replaced with the known workaround.
+ */
+function rethrowWithDocumentContentHint(error, issueId) {
+    const msg = error instanceof Error ? error.message : String(error);
+    if (msg.includes("Conflict on insert of DocumentContent")) {
+        const detail = issueId
+            ? `for ${issueId}. This does not self-heal by retrying — each attempt fails against a new conflicting id. Workaround: create a replacement issue with the same content, relate it back with --duplicate-of ${issueId}, and cancel the original.`
+            : "for this issue. This does not self-heal by retrying — each attempt fails against a new conflicting id. If it recurs on the same issue after creation, recreate it under a fresh id rather than repairing via update.";
+        throw new Error(`Linear reports its description store is in conflict ${detail}`);
+    }
+    if (error instanceof Error) {
+        throw error;
+    }
+    throw new Error(msg);
+}
 export class GraphQLIssuesService {
     graphQLService;
     linearService;
@@ -262,6 +287,14 @@ export class GraphQLIssuesService {
         };
     }
     async updateIssue(args, labelMode = "overwriting") {
+        try {
+            return await this.updateIssueImpl(args, labelMode);
+        }
+        catch (error) {
+            rethrowWithDocumentContentHint(error, args.id);
+        }
+    }
+    async updateIssueImpl(args, labelMode = "overwriting") {
         // Normalize URL/slug-id --project inputs to UUIDs before the batch
         // resolver runs; see comment on `withNormalizedProjectId`.
         const normalizedArgs = await this.withNormalizedProjectId(args);
@@ -368,6 +401,14 @@ export class GraphQLIssuesService {
         return this.transformIssueData(issueUpdate.issue);
     }
     async createIssue(args) {
+        try {
+            return await this.createIssueImpl(args);
+        }
+        catch (error) {
+            rethrowWithDocumentContentHint(error);
+        }
+    }
+    async createIssueImpl(args) {
         // Pre-resolve URL/slug-id forms of --project to a UUID so the batch
         // resolver below (which uses a `name eqIgnoreCase` filter) can skip
         // the project lookup entirely. Plain name inputs flow through unchanged

package/package.json

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