@enrichlayer/el-linear 1.41.0 → 1.41.1

package/dist/commands/issues.js

@@ -9,7 +9,7 @@ import { formatSopParentBlock, getSopLabelGateConfig, hasSopLabel, isUnresolvabl
 import { resolveDefaultStatus } from "../config/status-defaults.js";
 import { enforceTerms } from "../config/term-enforcer.js";
 import { GET_ISSUE_RELATIONS_QUERY, GET_ISSUE_STATE_HISTORY_QUERY, } from "../queries/issues.js";
-import { DEFAULT_DUPLICATE_THRESHOLD, DEFAULT_HARD_BLOCK_THRESHOLD, formatDuplicateBlock, scoreDuplicateCandidates, tokenizeTitle, } from "../utils/duplicate-detection.js";
+import { bypassesDuplicateHardBlock, DEFAULT_DUPLICATE_THRESHOLD, DEFAULT_HARD_BLOCK_THRESHOLD, formatDuplicateBlock, scoreDuplicateCandidates, tokenizeTitle, } from "../utils/duplicate-detection.js";
 import { createFileService } from "../utils/file-service.js";
 import { applyFooter } from "../utils/footer.js";
 import { emitGateEvent } from "../utils/gate-telemetry.js";
@@ -589,7 +589,12 @@ async function enforceNoDuplicateIssue(title, options, issuesService) {
     // The gate would hard-block. Record the decision so `el-telemetry gates`
     // can compute override-rate (DEV-4834): `overridden` when the user passed
     // --allow-duplicate and we proceed anyway, `blocked` when we stop creation.
-    if (options.allowDuplicate) {
+    //
+    // The escape set lives in `bypassesDuplicateHardBlock` rather than inline so
+    // the remedy copy in `formatDuplicateBlock` is derived from the same source
+    // this decision reads (DEV-6205 — the message previously named a flag the
+    // gate never consulted).
+    if (bypassesDuplicateHardBlock(options)) {
         await emitGateEvent("el-linear", "issues create", {
             ...gateEvent,
             outcome: "overridden",

package/dist/commands/read-shortcut.js

@@ -73,14 +73,21 @@ export async function readIssues(issueIds, options, command) {
     const rootOpts = getRootOpts(command);
     const { graphQLService, issuesService } = await createIssuesService(rootOpts);
     const fileService = await createFileService(rootOpts);
-    const fieldName = typeof options.field === "string" ? options.field : null;
-    const bodyOnly = options.body === true;
-    const sectionsRaw = typeof options.sections === "string" ? options.sections : null;
+    // `issues` owns these options for its no-subcommand shorthand, while
+    // `issues read` registers the same options on the child command. Commander
+    // stores a duplicated flag on the parent even when it appears after `read`,
+    // so the action callback's local options can be empty. Merge the command
+    // hierarchy here, with local values winning, so every read route shares the
+    // same deterministic option contract.
+    const readOptions = { ...command.optsWithGlobals(), ...options };
+    const fieldName = typeof readOptions.field === "string" ? readOptions.field : null;
+    const bodyOnly = readOptions.body === true;
+    const sectionsRaw = typeof readOptions.sections === "string" ? readOptions.sections : null;
     // DEV-4476: --with opt-in includes (currently `relations`). Throws on
     // unknown values via parseWithIncludes — fail fast in the CLI per the
     // deterministic-CLI doctrine.
-    const includes = typeof options.with === "string"
-        ? parseWithIncludes(options.with)
+    const includes = typeof readOptions.with === "string"
+        ? parseWithIncludes(readOptions.with)
         : { relations: false };
     if (fieldName && sectionsRaw) {
         throw new Error("--field and --sections are mutually exclusive. Use --field for a single section (plain-text output) or --sections for multiple (JSON map).");

package/dist/utils/duplicate-detection.d.ts

@@ -70,6 +70,30 @@ export declare const DEFAULT_DUPLICATE_THRESHOLD = 0.35;
  * Overridable via `config.validation.duplicateHardBlockThreshold`.
  */
 export declare const DEFAULT_HARD_BLOCK_THRESHOLD = 0.6;
+/**
+ * The one CLI flag that lets a HARD-BLOCKED create proceed.
+ *
+ * Exported so the remedy copy in {@link formatDuplicateBlock} is BUILT from the
+ * same constant the gate honors, rather than restating it. DEV-6205 shipped a
+ * remedy naming `--parent <id>` alone — a flag the gate never reads — so the
+ * message promised an outcome the command refused. Deriving the copy from this
+ * constant makes that class of drift a compile-time concern instead of a
+ * proofreading one.
+ */
+export declare const DUPLICATE_GATE_OVERRIDE_FLAG = "--allow-duplicate";
+/**
+ * Does this parsed option set clear the duplicate gate's HARD block?
+ *
+ * The single source of truth for the escape set, consumed by the gate itself
+ * (`enforceNoDuplicateIssue`) and asserted against the rendered remedy copy by
+ * the composition test. Note `--skip-validation` also bypasses, but it returns
+ * long before scoring (it skips ALL field validation), so it is not part of the
+ * hard-block decision this predicate models and is deliberately not offered as
+ * a remedy.
+ */
+export declare function bypassesDuplicateHardBlock(options: {
+    allowDuplicate?: unknown;
+}): boolean;
 /** A scored duplicate candidate, ready to print in the block. */
 export interface DuplicateCandidate {
     identifier: string;
@@ -116,5 +140,30 @@ export declare function scoreDuplicateCandidates(title: string, candidates: Line
  * "advisory"` is printed as a warning when the score is below the hard-block
  * threshold: creation already proceeded, so the trailing hint differs (no
  * "re-run" — there's nothing to re-run).
+ *
+ * Three remedies, not two (DEV-6205). "Same work → comment" and "distinct →
+ * --allow-duplicate" leave out the most common real case: the new work is a
+ * piece of the match — neither a duplicate of it nor unrelated to it. Offering
+ * only the two extremes pushes the operator toward reusing the matched issue,
+ * which is actively harmful when that issue is a multi-phase parent: the branch
+ * then carries the parent's id, and merging it auto-closes work that isn't done.
+ * That is not hypothetical — it is what the omission cost on MAR-744, where a
+ * findings pack was filed against a six-criterion parent because `--parent` was
+ * never mentioned.
+ *
+ * The sub-issue remedy is per-tier, NOT shared, because the two tiers are at
+ * opposite sides of the create:
+ *
+ * - **block** — creation was refused, so the remedy is a re-run. `--parent`
+ *   alone does NOT satisfy the gate ({@link bypassesDuplicateHardBlock} reads
+ *   only `allowDuplicate`), so the copy is built from
+ *   {@link DUPLICATE_GATE_OVERRIDE_FLAG} and names both flags. A message that
+ *   names a command the gate then refuses is the DEV-6205 bug one level down;
+ *   the composition test parses this copy through the real CLI and asserts it
+ *   actually clears the gate.
+ * - **advisory** — creation ALREADY proceeded, so there is nothing to re-run
+ *   and a re-run would file a second issue (which then scores 1.0 against its
+ *   own twin and hard-blocks). The remedy is to attach the issue that now
+ *   exists, via `issues update`.
  */
 export declare function formatDuplicateBlock(candidates: DuplicateCandidate[], mode?: "block" | "advisory"): string;

package/dist/utils/duplicate-detection.js

@@ -141,6 +141,30 @@ const BOILERPLATE_STOPWORDS = new Set([
     "create",
     "update",
 ]);
+/**
+ * The one CLI flag that lets a HARD-BLOCKED create proceed.
+ *
+ * Exported so the remedy copy in {@link formatDuplicateBlock} is BUILT from the
+ * same constant the gate honors, rather than restating it. DEV-6205 shipped a
+ * remedy naming `--parent <id>` alone — a flag the gate never reads — so the
+ * message promised an outcome the command refused. Deriving the copy from this
+ * constant makes that class of drift a compile-time concern instead of a
+ * proofreading one.
+ */
+export const DUPLICATE_GATE_OVERRIDE_FLAG = "--allow-duplicate";
+/**
+ * Does this parsed option set clear the duplicate gate's HARD block?
+ *
+ * The single source of truth for the escape set, consumed by the gate itself
+ * (`enforceNoDuplicateIssue`) and asserted against the rendered remedy copy by
+ * the composition test. Note `--skip-validation` also bypasses, but it returns
+ * long before scoring (it skips ALL field validation), so it is not part of the
+ * hard-block decision this predicate models and is deliberately not offered as
+ * a remedy.
+ */
+export function bypassesDuplicateHardBlock(options) {
+    return Boolean(options.allowDuplicate);
+}
 /**
  * Tokenize a title into a set of salient lowercase keywords.
  *
@@ -219,19 +243,52 @@ export function scoreDuplicateCandidates(title, candidates, threshold = DEFAULT_
  * "advisory"` is printed as a warning when the score is below the hard-block
  * threshold: creation already proceeded, so the trailing hint differs (no
  * "re-run" — there's nothing to re-run).
+ *
+ * Three remedies, not two (DEV-6205). "Same work → comment" and "distinct →
+ * --allow-duplicate" leave out the most common real case: the new work is a
+ * piece of the match — neither a duplicate of it nor unrelated to it. Offering
+ * only the two extremes pushes the operator toward reusing the matched issue,
+ * which is actively harmful when that issue is a multi-phase parent: the branch
+ * then carries the parent's id, and merging it auto-closes work that isn't done.
+ * That is not hypothetical — it is what the omission cost on MAR-744, where a
+ * findings pack was filed against a six-criterion parent because `--parent` was
+ * never mentioned.
+ *
+ * The sub-issue remedy is per-tier, NOT shared, because the two tiers are at
+ * opposite sides of the create:
+ *
+ * - **block** — creation was refused, so the remedy is a re-run. `--parent`
+ *   alone does NOT satisfy the gate ({@link bypassesDuplicateHardBlock} reads
+ *   only `allowDuplicate`), so the copy is built from
+ *   {@link DUPLICATE_GATE_OVERRIDE_FLAG} and names both flags. A message that
+ *   names a command the gate then refuses is the DEV-6205 bug one level down;
+ *   the composition test parses this copy through the real CLI and asserts it
+ *   actually clears the gate.
+ * - **advisory** — creation ALREADY proceeded, so there is nothing to re-run
+ *   and a re-run would file a second issue (which then scores 1.0 against its
+ *   own twin and hard-blocks). The remedy is to attach the issue that now
+ *   exists, via `issues update`.
  */
 export function formatDuplicateBlock(candidates, mode = "block") {
     const lines = candidates.map((c) => `    ${c.identifier} · ${c.title} · ${c.state} · ${c.assignee}  (similarity ${c.score})`);
+    // Name the parent when there is exactly one candidate; with several there is
+    // no single right parent, and silently picking the top score would invite a
+    // wrong one.
+    const parentRef = candidates.length === 1 ? candidates[0].identifier : "<id>";
     const header = `Possible duplicate issue${candidates.length > 1 ? "s" : ""} found ` +
         "(by title-keyword overlap):\n" +
         `${lines.join("\n")}\n\n` +
         "  If one of these is the same work, comment on it instead of creating a new issue.\n";
     if (mode === "advisory") {
         return (header +
+            "  If this is a piece of one of them rather than a duplicate, attach it with " +
+            `\`issues update <new-id> --parent ${parentRef}\`.\n` +
             "  This is advisory only (DEV-5590) — creation is proceeding. Pass " +
             "--allow-duplicate to silence this notice next time.");
     }
     return (header +
-        "  If this is genuinely distinct, re-run with --allow-duplicate to proceed " +
+        "  If this is a piece of one of them rather than a duplicate, re-run with " +
+        `--parent ${parentRef} ${DUPLICATE_GATE_OVERRIDE_FLAG} to file it as a sub-issue.\n` +
+        `  If this is genuinely distinct, re-run with ${DUPLICATE_GATE_OVERRIDE_FLAG} to proceed ` +
         "(and consider --related-to to link the related issue).");
 }

package/package.json

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