@enrichlayer/el-linear 1.37.2 → 1.38.1

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/queries/projects-types.d.ts

@@ -77,6 +77,16 @@ export interface UpdateProjectResponse {
         project: ProjectBaseNode | null;
     };
 }
+interface ProjectUpdateFieldsNode extends ProjectBaseNode {
+    description: string | null;
+    content: string | null;
+}
+export interface UpdateProjectFieldsResponse {
+    projectUpdate: {
+        success: boolean;
+        project: ProjectUpdateFieldsNode | null;
+    };
+}
 interface ProjectArchiveEntity {
     id: string;
 }

package/dist/queries/projects.d.ts

@@ -14,5 +14,6 @@ export declare const GET_PROJECT_TEAM_ISSUES_QUERY = "\n  query GetProjectTeamIs
 export declare const SEARCH_PROJECTS_BY_NAME_QUERY = "\n  query SearchProjectsByName($name: String!) {\n    projects(filter: { name: { containsIgnoreCase: $name } }, first: 10) {\n      nodes {\n        id\n        name\n        state\n        teams {\n          nodes { id key name }\n        }\n      }\n    }\n  }\n";
 export declare const CREATE_PROJECT_MUTATION = "\n  mutation CreateProject($input: ProjectCreateInput!) {\n    projectCreate(input: $input) {\n      success\n      project {\n        id\n        name\n        state\n        teams {\n          nodes { id key name }\n        }\n      }\n    }\n  }\n";
 export declare const UPDATE_PROJECT_MUTATION = "\n  mutation UpdateProject($id: String!, $input: ProjectUpdateInput!) {\n    projectUpdate(id: $id, input: $input) {\n      success\n      project {\n        id\n        name\n        teams {\n          nodes {\n            id\n            key\n            name\n          }\n        }\n      }\n    }\n  }\n";
+export declare const UPDATE_PROJECT_FIELDS_MUTATION = "\n  mutation UpdateProjectFields($id: String!, $input: ProjectUpdateInput!) {\n    projectUpdate(id: $id, input: $input) {\n      success\n      project {\n        id\n        name\n        description\n        content\n        teams {\n          nodes {\n            id\n            key\n            name\n          }\n        }\n      }\n    }\n  }\n";
 export declare const ARCHIVE_PROJECT_MUTATION = "\n  mutation ArchiveProject($id: String!) {\n    projectArchive(id: $id) {\n      success\n      lastSyncId\n      entity {\n        id\n      }\n    }\n  }\n";
 export declare const DELETE_PROJECT_MUTATION = "\n  mutation DeleteProject($id: String!) {\n    projectDelete(id: $id) {\n      success\n      lastSyncId\n      entity {\n        id\n      }\n    }\n  }\n";

package/dist/queries/projects.js

@@ -129,6 +129,26 @@ export const UPDATE_PROJECT_MUTATION = `
     }
   }
 `;
+export const UPDATE_PROJECT_FIELDS_MUTATION = `
+  mutation UpdateProjectFields($id: String!, $input: ProjectUpdateInput!) {
+    projectUpdate(id: $id, input: $input) {
+      success
+      project {
+        id
+        name
+        description
+        content
+        teams {
+          nodes {
+            id
+            key
+            name
+          }
+        }
+      }
+    }
+  }
+`;
 export const ARCHIVE_PROJECT_MUTATION = `
   mutation ArchiveProject($id: String!) {
     projectArchive(id: $id) {

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/gate-telemetry.d.ts

@@ -1,3 +1,23 @@
+/**
+ * Deterministic-gate fire/override telemetry (DEV-4834, sub of DEV-4831).
+ *
+ * The `issues create` duplicate-detection gate (DEV-4823) records each decision
+ * it makes as a `gate` event so a reader (the Enrich Layer `el-telemetry gates`
+ * command, or any JSONL consumer) can compute the gate's override-rate
+ * (overridden / total) and tell whether the threshold is noisy.
+ *
+ * **Opt-in.** el-linear is open-source; most installs have no telemetry, and we
+ * must never write files a user didn't ask for. Emission is therefore OFF by
+ * default and turns on only when telemetry is actually configured — see
+ * {@link decideGateLedger}. The ledger is a plain local JSONL file
+ * (`gate-events.jsonl`); there is no server or database. el-linear can't import
+ * `el-telemetry` (separate package), so it writes by **path-contract** — the
+ * same approach `el-hook` uses. The path mirrors `el-telemetry`'s
+ * `GATE_EVENTS_PATH`; keep the two in sync. Format + reader are documented in
+ * `docs/telemetry.md`.
+ */
+export declare const GATE_LEDGER_MAX_BYTES: number;
+export declare const GATE_LEDGER_BACKUP_SUFFIX = ".old";
 /** Resolve where the ledger lives — for a *reader* locating the file (mirrors
  * el-telemetry's `GATE_EVENTS_PATH`). This is NOT the emit decision: it ignores
  * the opt-in policy, so never write through it — `emitGateEvent` goes through

package/dist/utils/gate-telemetry.js

@@ -1,5 +1,5 @@
 import { existsSync } from "node:fs";
-import { appendFile, mkdir } from "node:fs/promises";
+import { appendFile, mkdir, rename, rm, stat } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 /**
@@ -20,6 +20,8 @@ import { dirname, join } from "node:path";
  * `GATE_EVENTS_PATH`; keep the two in sync. Format + reader are documented in
  * `docs/telemetry.md`.
  */
+export const GATE_LEDGER_MAX_BYTES = 2 * 1024 * 1024;
+export const GATE_LEDGER_BACKUP_SUFFIX = ".old";
 /** The default ledger directory when `EL_TELEMETRY_DIR` is not set. */
 function defaultTelemetryDir() {
     return join(homedir(), ".cache", "el-telemetry");
@@ -67,6 +69,28 @@ function gateLedgerIfEnabled() {
         defaultDirExists: existsSync(defaultDir),
     });
 }
+async function rotateGateLedgerIfOverLimit(path) {
+    let size = 0;
+    try {
+        const s = await stat(path);
+        if (!s.isFile())
+            return;
+        size = s.size;
+    }
+    catch {
+        return;
+    }
+    if (size <= GATE_LEDGER_MAX_BYTES)
+        return;
+    try {
+        const backupPath = `${path}${GATE_LEDGER_BACKUP_SUFFIX}`;
+        await rm(backupPath, { force: true });
+        await rename(path, backupPath);
+    }
+    catch {
+        // best-effort — telemetry never blocks issue creation
+    }
+}
 /**
  * Best-effort append of a gate event to the local ledger — but only when
  * telemetry is opted in ({@link gateLedgerIfEnabled}); otherwise a silent
@@ -80,6 +104,7 @@ export async function emitGateEvent(name, subcommand, event) {
     }
     try {
         await mkdir(dirname(path), { recursive: true });
+        await rotateGateLedgerIfOverLimit(path);
         const record = {
             ts: new Date().toISOString(),
             kind: "gate",

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/dist/utils/inline-text-input.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Normalize shell-literal newline escapes in inline CLI text fields.
+ *
+ * File inputs are intentionally excluded by call site: a file body is already
+ * explicit authored text and may intentionally contain backslash sequences.
+ */
+export declare function normalizeInlineTextInput(value: string): string;

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

@@ -0,0 +1,12 @@
+/**
+ * Normalize shell-literal newline escapes in inline CLI text fields.
+ *
+ * File inputs are intentionally excluded by call site: a file body is already
+ * explicit authored text and may intentionally contain backslash sequences.
+ */
+export function normalizeInlineTextInput(value) {
+    return value
+        .replace(/\\r\\n/g, "\n")
+        .replace(/\\n/g, "\n")
+        .replace(/\\r/g, "\n");
+}

package/dist/utils/relation-candidate-prompt.d.ts

@@ -41,16 +41,23 @@
  */
 export declare function extractCandidateIdentifiers(rows: unknown[]): string[];
 /**
- * Build the relation-candidate confirmation warning string, or `null` when
- * the result set has no identifier-bearing rows (nothing to confirm).
+ * Build the relation-candidate warning string, or `null` when the result set
+ * has no identifier-bearing rows (nothing to surface).
  *
  * Shape (single line, structured-prose so a skill can match on the prefix):
  *
  *     relation_candidates: Found N candidate related issues (DEV-1, DEV-2, …).
- *     To link them as related: reply with the IDs you want linked
- *     (e.g. "link DEV-1 and DEV-2"). To skip linking: reply "no links".
+ *     Link the relevant ones now — at create time with --related-to, or
+ *     `issues relate <id> --related-to "<ids>"`. If auto-mode blocks an
+ *     agent-inferred relate, reply with the IDs you want linked
+ *     (e.g. "link DEV-1 and DEV-2"), or "no links" to skip.
  *
- * The `relation_candidates:` prefix matches the existing `results_truncated:`
+ * DEV-5853: the primary framing is **proactive** — this is a convenience list
+ * of link candidates, not a stop sign. Relate the relevant ones directly
+ * rather than waiting to be told; the reply flow is the *fallback* for when
+ * the auto-mode classifier actually blocks an agent-inferred `issues relate`
+ * (create-time `--related-to` typically passes, so prefer it). The
+ * `relation_candidates:` prefix matches the existing `results_truncated:`
  * convention in `outputWarning` callers — a stable token a skill / agent
  * harness can grep for without parsing free-form prose.
  */