@enrichlayer/el-linear 1.35.0 → 1.37.0

package/README.md

@@ -249,13 +249,14 @@ itself: `el-linear teams list --raw | jq '.[] | {key, id}'`, etc.
 
 ### Gate telemetry (optional)
 
-`issues create` has a duplicate-detection gate. el-linear can record each
-fire/override decision to a local JSONL file so you can measure the gate's
-**override-rate** and tell whether it's too aggressive. It is **off by default**
-and writes nothing unless you opt in (e.g. `export EL_TELEMETRY_DIR=<path>`);
-there is no server or database, and `EL_TELEMETRY_DISABLED=1` forces it off.
-Full opt-in rules, the event schema, and a `jq` reader are in
-[docs/telemetry.md](./docs/telemetry.md).
+`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).
+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.
+`export EL_TELEMETRY_DIR=<path>`); there is no server or database, and
+`EL_TELEMETRY_DISABLED=1` forces it off. Full opt-in rules, the event schema, and
+a `jq` reader are in [docs/telemetry.md](./docs/telemetry.md).
 
 ### Networking (IPv4 preference)
 
@@ -555,9 +556,9 @@ Currently wired through:
 
 | Resource | Defaults | Extras you can request |
 |----------|----------|------------------------|
-| `issues list` | `id, title, state, assignee` | `project, cycle, milestone, labels, url, priority, estimate, createdAt, updatedAt, team` |
+| `issues list` | `id, title, state, assignee` | `project, cycle, milestone, labels, url, priority, estimate, createdAt, updatedAt, completedAt, team` |
 | `projects list` | `name, state, progress, lead` | `teams, target, url, updatedAt` |
-| `issues read` (single) | `state, assignee, project, cycle, milestone, labels, url` | `priority, estimate, created, updated` |
+| `issues read` (single) | `state, assignee, project, cycle, milestone, labels, url` | `priority, estimate, created, updated, completed` |
 | `projects read` (single) | `state, lead, teams, target, progress, url` | (filter only — no extras) |
 
 `identifier`, `id`, `title` and `name` are headline-only on single-resource summaries and are filtered out of the labelled block (they remain on the title line above). `status` is accepted as a synonym for `state`, `owner` for `assignee`, `targetDate` for `target`.

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

@@ -143,8 +143,8 @@ For tools that aren't `el-linear` (e.g. `gh`, `glab`, `kubectl`), prefer `jq` fo
 
 `--format summary` is implemented for:
 
-- **Single resources:** `issues read`, `comments read`, `projects read`, `cycles read`, `project-milestones read`, `documents read`, `templates read`, releases (`graphql` query results), `users read`
-- **Lists:** `issues list`, `issues search`, `projects list`, `comments list`, `cycles list`, `project-milestones list`, `labels list`, `teams list`, `users list`, `documents list`, `templates list`, `attachments list`, `releases list`, and the cross-resource `search` command
+- **Single resources:** `issues read`, `comments read`, `projects read`, `cycles read`, `project-milestones read`, `project-updates read`, `documents read`, `templates read`, releases (`graphql` query results), `users read`
+- **Lists:** `issues list`, `issues search`, `projects list`, `comments list`, `cycles list`, `project-milestones list`, `project-updates list`, `labels list`, `teams list`, `users list`, `documents list`, `templates list`, `attachments list`, `releases list`, and the cross-resource `search` command
 
 Commands without a dedicated formatter (e.g. `config show`, custom `graphql` queries) fall back to a generic key/value rendering of their JSON payload.
 
@@ -200,6 +200,21 @@ and outreach tracked in one place.
 > `validation.duplicateDetection: false` (field validation still runs);
 > `validation.enabled: false` turns off all validation.
 
+> **SOP-label parent gate ([DEV-5378](https://linear.app/verticalint/issue/DEV-5378/), opt-in).** When enabled, `el-linear issues create` requires an
+> issue carrying an **SOP-type label** (any name in `validation.sopLabels`,
+> default `["SOP"]`, case-insensitive) to point at a **parent SOP** — `--parent`
+> or `--related-to` must resolve to another SOP-labeled issue — and **blocks
+> (exit non-zero)** otherwise, naming the rule. An SOP with no parent SOP is
+> unfindable by SOP tooling and breaks the catalog topology. It is **off by
+> default** (`validation.sopLabelParentGate: true` turns it on; the Enrich Layer
+> shared team config flips it on) because "SOP" is a workspace-specific
+> taxonomy, not something an open-source install should assume. Escape hatch:
+> `--allow-unparented-sop` (narrow, for an intentionally top-level SOP);
+> `--skip-validation` also bypasses it but skips all field validation. A typo'd
+> or nonexistent parent reference **blocks** (naming the ref) so a mistake can't
+> orphan an SOP; a transport/service error **fails open** with a warning (and a
+> `fail-open` gate event); a resolvable non-SOP parent hard-blocks.
+
 ```bash
 # --include-closed is required so previously-completed duplicates surface.
 # `issues search` defaults to open states (DEV-4478); the duplicate check
@@ -517,6 +532,25 @@ el-linear projects add-team "Project Name" ENG 2>&1
 
 **Never use raw `projectUpdate` with `teamIds`** — it replaces the entire team list. Always use `projects add-team` / `remove-team`.
 
+### Project Updates (status posts) — mind the naming collision
+
+Linear has two unrelated things spelled almost the same:
+
+- `projectUpdate(id, input)` — the mutation that **edits a project** (the one warned about just above). Surfaced by the `projects` command.
+- `ProjectUpdate` — a **status post** in a project's Updates feed (progress + a health color). Surfaced by the dedicated `project-updates` command:
+
+```bash
+# Post a status update to a project (appears in the Updates feed)
+el-linear project-updates create --project "Auth Refactor" \
+  --body "Shipped the session-store migration; rollout at 60%." \
+  --health onTrack   # onTrack | atRisk | offTrack — omit to leave unset
+
+el-linear project-updates list --project "Auth Refactor"
+el-linear project-updates read <updateId>
+```
+
+`--body` / `--body-file` are mutually exclusive (one required); `--body-file` avoids shell-quoting for markdown/tables. `--health` is validated against the enum before the API call. `--diff-hidden` hides the auto-generated progress diff on the update. `-q/--quiet` prints `<health>  <url>`. A status update is not the same as a project **document** (`documents create --project`) — use a document for durable reference content, a project update for point-in-time progress.
+
 ### Discovery Before Creation
 
 Always check if a project exists before creating: `el-linear projects list`.

package/dist/commands/config.js

@@ -33,6 +33,8 @@ function sourceLabel(source) {
             return "teamConfigPath in personal config";
         case "marker":
             return "auto-discovered via ~/.config/el-tools-root";
+        case "disabled":
+            return 'disabled for this profile via teamConfigPath: "" in personal config';
         case null:
             return null;
     }

package/dist/commands/issues.js

@@ -3,6 +3,7 @@ import { loadConfig } from "../config/config.js";
 import { enrichProjectResolverError, enrichValidationErrors, } from "../config/error-enrichment.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";
 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";
@@ -544,6 +545,109 @@ async function enforceNoDuplicateIssue(title, options, issuesService) {
     });
     throw new Error(`Issue creation blocked: ${formatDuplicateBlock(matches)}`);
 }
+/**
+ * DEV-5378: create-time SOP-label parent gate. When the issue being created
+ * carries an SOP-type label, require that `--parent` or `--related-to` resolves
+ * to another SOP-labeled issue, and throw otherwise — the deterministic form of
+ * the kaizen skill's Stage-4 rule (parent ALL-1028). An SOP with no parent SOP
+ * is unfindable by `el-sop landscape` and breaks the catalog topology.
+ *
+ * OPT-IN: dormant unless `validation.sopLabelParentGate: true` (see
+ * {@link getSopLabelGateConfig}) — el-linear is MIT/open-source and "SOP" is an
+ * Enrich-Layer-specific taxonomy. Bypassed by `--skip-validation` (blanket) and
+ * the narrow `--allow-unparented-sop` (which records an `overridden` gate event,
+ * mirroring `--allow-duplicate`). The parent-label fetch is best-effort: when a
+ * referenced issue can't be resolved (network / not-found) the gate fails open
+ * with a warning rather than blocking legitimate creation on infra trouble — a
+ * genuinely resolvable non-SOP parent still hard-blocks.
+ */
+async function enforceSopLabelParent(labels, options, issuesService) {
+    if (options.skipValidation) {
+        return;
+    }
+    const { enabled, sopLabels } = getSopLabelGateConfig();
+    if (!enabled) {
+        return;
+    }
+    if (!hasSopLabel(labels, sopLabels)) {
+        return;
+    }
+    const parentRefs = [
+        ...(typeof options.parentTicket === "string" && options.parentTicket
+            ? [options.parentTicket]
+            : []),
+        ...(options.relatedTo ? splitList(options.relatedTo) : []),
+    ];
+    // Record the decision so `el-telemetry gates` can compute override-rate,
+    // mirroring the dup gate (DEV-4834): `overridden` when the caller passed
+    // --allow-unparented-sop and we proceed, `blocked` when we stop creation.
+    const decide = async (reason, unresolvableRefs) => {
+        const gateEvent = { gate: "issues-create-sop-parent" };
+        if (options.allowUnparentedSop) {
+            await emitGateEvent("el-linear", "issues create", {
+                ...gateEvent,
+                outcome: "overridden",
+            });
+            return;
+        }
+        await emitGateEvent("el-linear", "issues create", {
+            ...gateEvent,
+            outcome: "blocked",
+        });
+        throw new Error(`Issue creation blocked: ${formatSopParentBlock({
+            sopLabels,
+            reason,
+            parentRefs,
+            unresolvableRefs,
+        })}`);
+    };
+    // No parent/related at all → deterministic block (no fetch needed).
+    if (parentRefs.length === 0) {
+        await decide("no-parent");
+        return;
+    }
+    // A referenced issue that resolves AND carries an SOP label satisfies the
+    // gate. Fetch per-ref (not batched) so one unresolvable ref doesn't sink a
+    // sibling that would have passed. Classify each failure: a clean
+    // not-found/malformed ref is an unresolvable reference (it contributes to a
+    // block — a typo must not slip through), a transport/service error is infra
+    // trouble (fail open so it can't block legitimate creation).
+    const unresolvableRefs = [];
+    let transportError = false;
+    for (const ref of parentRefs) {
+        try {
+            const issue = await issuesService.getIssueById(ref);
+            if (hasSopLabel(issue.labels.map((l) => l.name), sopLabels)) {
+                return; // valid SOP parent — pass
+            }
+        }
+        catch (err) {
+            if (isUnresolvableReferenceError(err)) {
+                unresolvableRefs.push(ref);
+            }
+            else {
+                transportError = true;
+            }
+        }
+    }
+    // No SOP parent was confirmed. A transport failure may have hidden the real
+    // SOP parent → fail open (best-effort, like the dup gate on a search
+    // failure) and record it so the degradation is measurable (DEV-5378).
+    if (transportError) {
+        await emitGateEvent("el-linear", "issues create", {
+            gate: "issues-create-sop-parent",
+            outcome: "fail-open",
+        });
+        outputWarning(`SOP-parent check could not verify a parent SOP for ${parentRefs.join(", ")} due to a service error; proceeding without blocking.${options.allowUnparentedSop
+            ? ""
+            : " Pass --allow-unparented-sop to silence."}`);
+        return;
+    }
+    // Every reference either resolved to a non-SOP issue or cleanly failed to
+    // resolve (typo / nonexistent) — none is a valid SOP parent → block, naming
+    // any unresolvable refs so a typo reads differently from a real non-SOP parent.
+    await decide("no-sop-parent", unresolvableRefs.length > 0 ? unresolvableRefs : undefined);
+}
 async function handleCreateIssue(title, options, command) {
     const rootOpts = getRootOpts(command);
     const { teamInput, teamId, assigneeId, delegateId, labelIds, status, subscriberIds, priority, } = await resolveCreateInputs(title ?? "", options, rootOpts);
@@ -572,6 +676,15 @@ async function handleCreateIssue(title, options, command) {
     if (title) {
         await enforceNoDuplicateIssue(title, options, issuesService);
     }
+    // DEV-5378: deterministic SOP-label parent gate. Opt-in (dormant unless
+    // validation.sopLabelParentGate). Runs on the post-normalization labels
+    // (resolveCreateInputs rewrote options.labels to the canonical set) and,
+    // when the issue is SOP-labeled, blocks unless --parent/--related-to points
+    // at another SOP-labeled issue. Independent of title, so it runs even on the
+    // --from-template path — though a template that supplies labels server-side
+    // leaves options.labels undefined here, in which case the gate sees no SOP
+    // label and no-ops (same client-side-visibility gap as the dup gate).
+    await enforceSopLabelParent(options.labels ? splitList(options.labels) : [], options, issuesService);
     // Wrap valid issue identifiers as markdown links before creating, so the description
     // saved on Linear has clickable refs from the start. Self-reference can't apply here
     // because the issue doesn't exist yet — pass undefined.
@@ -1137,8 +1250,9 @@ 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)")
+        .option("--skip-validation", "skip all validation (labels, description, assignee, project, duplicate detection, SOP-parent gate)")
         .option("--allow-duplicate", "skip the duplicate-detection gate and create even if a similar issue already exists")
+        .option("--allow-unparented-sop", "skip the SOP-label parent gate and create an SOP-labeled issue without a parent SOP")
         .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

@@ -7,9 +7,11 @@ import type { TermRule } from "./term-enforcer.js";
  * - `env`: `EL_LINEAR_TEAM_CONFIG` is set in the environment (highest).
  * - `personal`: `teamConfigPath` field in personal `config.json`.
  * - `marker`: auto-discovered via `~/.config/el-tools-root` (DEV-4258).
+ * - `disabled`: explicitly opted out via `teamConfigPath: ""` in personal
+ *   config — the layer is off even when the marker would otherwise apply.
  * - `null`: no team layer active.
  */
-export type TeamConfigSource = "env" | "personal" | "marker" | null;
+export type TeamConfigSource = "env" | "personal" | "marker" | "disabled" | null;
 /**
  * Canonical shape of `~/.config/el-linear/config.json`. This is the single source
  * of truth for the on-disk config — the wizard reads/writes the same shape
@@ -67,6 +69,21 @@ export interface ElLinearConfig {
          * `DEFAULT_DUPLICATE_THRESHOLD` (0.35). Lower = more aggressive.
          */
         duplicateThreshold?: number;
+        /**
+         * OPT-IN SOP-label parent gate (DEV-5378). When `true`, `issues create`
+         * requires an issue carrying an SOP-type label (see `sopLabels`) to point
+         * at a parent SOP via `--parent` or `--related-to`, blocking otherwise.
+         * Defaults to `false` (dormant) — el-linear is MIT/open-source and "SOP"
+         * is an Enrich-Layer-specific taxonomy, so a fresh install stays silent
+         * until a workspace opts in (the EL shared team config flips it on).
+         * Bypass a single create with `--allow-unparented-sop`.
+         */
+        sopLabelParentGate?: boolean;
+        /**
+         * Label names (matched case-insensitively) that mark an issue as an SOP
+         * for the `sopLabelParentGate` check. Defaults to `["SOP"]`.
+         */
+        sopLabels?: string[];
     };
     /**
      * Optional override for the Linear workspace URL key (the part after
@@ -127,6 +144,15 @@ export interface ElLinearConfig {
      * maps, and term rules across a team by checking the file into a shared
      * repository. Override at runtime with the `EL_LINEAR_TEAM_CONFIG` env var
      * (env var takes precedence over this field).
+     *
+     * Set to the empty string (`""`) to explicitly DISABLE the team layer for
+     * this profile, including `~/.config/el-tools-root` marker auto-discovery.
+     * This is the multi-account escape hatch: a marker-discovered team config
+     * carries workspace-specific member/label UUIDs, and applying it to a
+     * profile pointed at a different Linear workspace makes `--assignee <name>`
+     * resolve to a foreign UUID that the API rejects with an opaque
+     * "Entity not found in validateAccess" error. Profiles for secondary
+     * workspaces should set `"teamConfigPath": ""`.
      */
     teamConfigPath?: string;
 }

package/dist/config/config.js

@@ -112,6 +112,10 @@ export function loadConfig() {
         // The marker is the opt-in consent signal — only developers who ran
         // `link-project.sh` get the auto-discovery; OSS users hit the silent
         // no-op path. DEV-4258 / ALL-964.
+        //
+        // An EMPTY string is a deliberate per-profile opt-out (see the
+        // `teamConfigPath` JSDoc): it is defined, so marker discovery is
+        // skipped, and falsy, so no team layer is loaded below.
         personalRaw = readRawPersonalConfig(active);
         teamConfigPath = personalRaw.teamConfigPath;
         if (teamConfigPath === undefined) {
@@ -181,7 +185,14 @@ export function getActiveTeamConfigInfo() {
     }
     const personalRaw = readRawPersonalConfig(resolveActiveProfile());
     const personalPath = personalRaw.teamConfigPath;
-    if (personalPath !== undefined && personalPath !== "") {
+    if (personalPath === "") {
+        // Explicit per-profile opt-out — must be attributed as such, and must
+        // NOT fall through to the marker: loadConfig skips marker discovery
+        // for a defined-but-empty path, so reporting "marker" here would
+        // contradict what actually loads.
+        return { path: undefined, source: "disabled" };
+    }
+    if (personalPath !== undefined) {
         return { path: personalPath, source: "personal" };
     }
     const markerPath = discoverTeamConfigViaMarker();

package/dist/config/sop-label-validation.d.ts

@@ -0,0 +1,82 @@
+/**
+ * SOP-label parent validation — DEV-5378.
+ *
+ * The el-linear side of the SOP-system enforcement (parent ALL-1028). When an
+ * issue carries an SOP-type label, it must point at a parent SOP so the
+ * `el-sop landscape` catalog topology stays connected — an SOP with no parent
+ * SOP is unfindable and breaks the tree. This turns the kaizen skill's Stage-4
+ * "always give an SOP issue a parent SOP" prose rule into a deterministic
+ * create-time gate, mirroring the DEV-4823 duplicate-detection gate.
+ *
+ * OPT-IN by design. el-linear is MIT and published on npm; most installs are
+ * not Enrich Layer and have no SOP taxonomy. The gate is dormant unless
+ * `validation.sopLabelParentGate: true` is set (the EL workspace flips it on in
+ * its shared team config). This is the opposite of the duplicate-detection gate,
+ * which defaults on — but the dup check is workspace-agnostic, whereas "SOP" is
+ * an Enrich-Layer-specific label taxonomy that a fresh OSS install must not be
+ * surprised by.
+ */
+/**
+ * Default label names that mark an issue as an SOP. Overridable via
+ * `config.validation.sopLabels`. Matched case-insensitively against the
+ * issue's labels.
+ */
+export declare const DEFAULT_SOP_LABELS: string[];
+export interface SopLabelGateConfig {
+    /**
+     * Whether the gate is active. OPT-IN: only true when validation is not
+     * turned off AND `sopLabelParentGate` is explicitly `true`.
+     */
+    enabled: boolean;
+    /** The SOP label names in effect (config override or {@link DEFAULT_SOP_LABELS}). */
+    sopLabels: string[];
+}
+/**
+ * Resolve the SOP-label-parent-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.sopLabelParentGate: true`. An absent or empty `sopLabels` falls
+ * back to {@link DEFAULT_SOP_LABELS}.
+ */
+export declare function getSopLabelGateConfig(): SopLabelGateConfig;
+/**
+ * Case-insensitive membership test: does `labels` contain any of the configured
+ * SOP label names? Returns false for an empty `labels` set.
+ */
+export declare function hasSopLabel(labels: string[], sopLabels: string[]): boolean;
+/**
+ * Distinguish a reference that cleanly does NOT resolve to a real issue (a
+ * typo'd or nonexistent `--parent` / `--related-to`) from a transport/service
+ * failure (network, GraphQL 5xx, timeout).
+ *
+ * `getIssueById` throws a plain `Error` for both — this codebase has no error
+ * `code` or subclass to switch on — so we key on the two message families it
+ * produces for an *unresolvable reference*:
+ *   - `notFoundError` → `… not found.`  (well-formed ref, no such issue)
+ *   - `parseIssueIdentifier` → `Invalid issue identifier format: …` /
+ *     `Invalid issue number in identifier: …`  (malformed ref)
+ * Everything else — notably `GraphQL request failed: …` / `GraphQL query
+ * failed` from `graphql-service` — is treated as transport and fails open.
+ *
+ * This is a correctness distinction, not just telemetry: an unresolvable
+ * reference must BLOCK. Otherwise a typo'd `--related-to` on an SOP issue fails
+ * open, the issue is created, and the *follow-up* `createRelations` throws —
+ * leaving an orphan SOP on the board (the exact gap DEV-5378 cycle-1 caught). A
+ * transport error must FAIL OPEN so infra trouble can't block legitimate work.
+ */
+export declare function isUnresolvableReferenceError(err: unknown): boolean;
+/**
+ * Render the human/agent-facing block thrown when an SOP-labeled issue has no
+ * SOP parent. `reason` distinguishes "no parent at all" from "one or more
+ * references present but none resolves to an SOP-labeled issue", so the message
+ * points at the exact fix. When some references couldn't be resolved at all,
+ * `unresolvableRefs` names them (a typo'd ref reads differently from a real but
+ * non-SOP parent). Names the rule and the `--allow-unparented-sop` escape hatch.
+ */
+export declare function formatSopParentBlock(opts: {
+    sopLabels: string[];
+    reason: "no-parent" | "no-sop-parent";
+    parentRefs: string[];
+    unresolvableRefs?: string[];
+}): string;

package/dist/config/sop-label-validation.js

@@ -0,0 +1,103 @@
+/**
+ * SOP-label parent validation — DEV-5378.
+ *
+ * The el-linear side of the SOP-system enforcement (parent ALL-1028). When an
+ * issue carries an SOP-type label, it must point at a parent SOP so the
+ * `el-sop landscape` catalog topology stays connected — an SOP with no parent
+ * SOP is unfindable and breaks the tree. This turns the kaizen skill's Stage-4
+ * "always give an SOP issue a parent SOP" prose rule into a deterministic
+ * create-time gate, mirroring the DEV-4823 duplicate-detection gate.
+ *
+ * OPT-IN by design. el-linear is MIT and published on npm; most installs are
+ * not Enrich Layer and have no SOP taxonomy. The gate is dormant unless
+ * `validation.sopLabelParentGate: true` is set (the EL workspace flips it on in
+ * its shared team config). This is the opposite of the duplicate-detection gate,
+ * which defaults on — but the dup check is workspace-agnostic, whereas "SOP" is
+ * an Enrich-Layer-specific label taxonomy that a fresh OSS install must not be
+ * surprised by.
+ */
+import { loadConfig } from "./config.js";
+/**
+ * Default label names that mark an issue as an SOP. Overridable via
+ * `config.validation.sopLabels`. Matched case-insensitively against the
+ * issue's labels.
+ */
+export const DEFAULT_SOP_LABELS = ["SOP"];
+/**
+ * Resolve the SOP-label-parent-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.sopLabelParentGate: true`. An absent or empty `sopLabels` falls
+ * back to {@link DEFAULT_SOP_LABELS}.
+ */
+export function getSopLabelGateConfig() {
+    const validation = loadConfig().validation;
+    const enabled = validation?.enabled !== false && validation?.sopLabelParentGate === true;
+    const sopLabels = validation?.sopLabels && validation.sopLabels.length > 0
+        ? validation.sopLabels
+        : DEFAULT_SOP_LABELS;
+    return { enabled, sopLabels };
+}
+/**
+ * Case-insensitive membership test: does `labels` contain any of the configured
+ * SOP label names? Returns false for an empty `labels` set.
+ */
+export function hasSopLabel(labels, sopLabels) {
+    const wanted = new Set(sopLabels.map((l) => l.toLowerCase()));
+    return labels.some((l) => wanted.has(l.toLowerCase()));
+}
+/**
+ * Distinguish a reference that cleanly does NOT resolve to a real issue (a
+ * typo'd or nonexistent `--parent` / `--related-to`) from a transport/service
+ * failure (network, GraphQL 5xx, timeout).
+ *
+ * `getIssueById` throws a plain `Error` for both — this codebase has no error
+ * `code` or subclass to switch on — so we key on the two message families it
+ * produces for an *unresolvable reference*:
+ *   - `notFoundError` → `… not found.`  (well-formed ref, no such issue)
+ *   - `parseIssueIdentifier` → `Invalid issue identifier format: …` /
+ *     `Invalid issue number in identifier: …`  (malformed ref)
+ * Everything else — notably `GraphQL request failed: …` / `GraphQL query
+ * failed` from `graphql-service` — is treated as transport and fails open.
+ *
+ * This is a correctness distinction, not just telemetry: an unresolvable
+ * reference must BLOCK. Otherwise a typo'd `--related-to` on an SOP issue fails
+ * open, the issue is created, and the *follow-up* `createRelations` throws —
+ * leaving an orphan SOP on the board (the exact gap DEV-5378 cycle-1 caught). A
+ * transport error must FAIL OPEN so infra trouble can't block legitimate work.
+ */
+export function isUnresolvableReferenceError(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return (message.includes("not found.") ||
+        message.includes("Invalid issue identifier format") ||
+        message.includes("Invalid issue number in identifier"));
+}
+/**
+ * Render the human/agent-facing block thrown when an SOP-labeled issue has no
+ * SOP parent. `reason` distinguishes "no parent at all" from "one or more
+ * references present but none resolves to an SOP-labeled issue", so the message
+ * points at the exact fix. When some references couldn't be resolved at all,
+ * `unresolvableRefs` names them (a typo'd ref reads differently from a real but
+ * non-SOP parent). Names the rule and the `--allow-unparented-sop` escape hatch.
+ */
+export function formatSopParentBlock(opts) {
+    const sopList = opts.sopLabels.join(", ");
+    const head = `SOP-labeled issue must point at a parent SOP (SOP label(s): ${sopList}).\n` +
+        "  An SOP with no parent SOP is unfindable by `el-sop landscape` and breaks the catalog topology.\n";
+    let detail;
+    if (opts.reason === "no-parent") {
+        detail =
+            "  This issue has no --parent or --related-to. Add one that points at an SOP-labeled issue.\n";
+    }
+    else {
+        detail = `  No referenced issue resolves to an SOP-labeled issue (referenced: ${opts.parentRefs.join(", ")}).\n`;
+        if (opts.unresolvableRefs && opts.unresolvableRefs.length > 0) {
+            detail += `  Could not resolve: ${opts.unresolvableRefs.join(", ")} — check the identifier exists.\n`;
+        }
+        detail +=
+            "  Point --parent or --related-to at an existing SOP-labeled issue.\n";
+    }
+    const hatch = "  If this SOP is intentionally top-level, re-run with --allow-unparented-sop.";
+    return head + detail + hatch;
+}

package/dist/queries/common.d.ts

@@ -1,2 +1,2 @@
-export declare const COMPLETE_ISSUE_FRAGMENT = "\n  \n  id\n  identifier\n  title\n  description\n  summary { content generationStatus }\n  branchName\n  priority\n  estimate\n  dueDate\n  url\n  createdAt\n  updatedAt\n\n  \n  state {\n    id\n    name\n    type\n  }\n\n  \n  assignee {\n    id\n    name\n    url\n  }\n\n  \n  delegate {\n    id\n    name\n    url\n  }\n\n  \n  team {\n    id\n    key\n    name\n  }\n\n  \n  project {\n    id\n    name\n  }\n\n  \n  labels {\n    nodes {\n      id\n      name\n    }\n  }\n\n  \n  cycle {\n    id\n    name\n    number\n  }\n\n  \n  projectMilestone {\n    id\n    name\n    targetDate\n  }\n\n  \n  parent {\n    id\n    identifier\n    title\n  }\n\n  \n  children {\n    nodes {\n      id\n      identifier\n      title\n    }\n  }\n\n";
-export declare const COMPLETE_ISSUE_WITH_COMMENTS_FRAGMENT = "\n  \n  \n  id\n  identifier\n  title\n  description\n  summary { content generationStatus }\n  branchName\n  priority\n  estimate\n  dueDate\n  url\n  createdAt\n  updatedAt\n\n  \n  state {\n    id\n    name\n    type\n  }\n\n  \n  assignee {\n    id\n    name\n    url\n  }\n\n  \n  delegate {\n    id\n    name\n    url\n  }\n\n  \n  team {\n    id\n    key\n    name\n  }\n\n  \n  project {\n    id\n    name\n  }\n\n  \n  labels {\n    nodes {\n      id\n      name\n    }\n  }\n\n  \n  cycle {\n    id\n    name\n    number\n  }\n\n  \n  projectMilestone {\n    id\n    name\n    targetDate\n  }\n\n  \n  parent {\n    id\n    identifier\n    title\n  }\n\n  \n  children {\n    nodes {\n      id\n      identifier\n      title\n    }\n  }\n\n\n  \n  comments {\n    nodes {\n      id\n      body\n      createdAt\n      updatedAt\n      user {\n        id\n        name\n        url\n      }\n    }\n  }\n\n";
+export declare const COMPLETE_ISSUE_FRAGMENT = "\n  \n  id\n  identifier\n  title\n  description\n  summary { content generationStatus }\n  branchName\n  priority\n  estimate\n  dueDate\n  url\n  createdAt\n  updatedAt\n  completedAt\n\n  \n  state {\n    id\n    name\n    type\n  }\n\n  \n  assignee {\n    id\n    name\n    url\n  }\n\n  \n  delegate {\n    id\n    name\n    url\n  }\n\n  \n  team {\n    id\n    key\n    name\n  }\n\n  \n  project {\n    id\n    name\n  }\n\n  \n  labels {\n    nodes {\n      id\n      name\n    }\n  }\n\n  \n  cycle {\n    id\n    name\n    number\n  }\n\n  \n  projectMilestone {\n    id\n    name\n    targetDate\n  }\n\n  \n  parent {\n    id\n    identifier\n    title\n  }\n\n  \n  children {\n    nodes {\n      id\n      identifier\n      title\n    }\n  }\n\n";
+export declare const COMPLETE_ISSUE_WITH_COMMENTS_FRAGMENT = "\n  \n  \n  id\n  identifier\n  title\n  description\n  summary { content generationStatus }\n  branchName\n  priority\n  estimate\n  dueDate\n  url\n  createdAt\n  updatedAt\n  completedAt\n\n  \n  state {\n    id\n    name\n    type\n  }\n\n  \n  assignee {\n    id\n    name\n    url\n  }\n\n  \n  delegate {\n    id\n    name\n    url\n  }\n\n  \n  team {\n    id\n    key\n    name\n  }\n\n  \n  project {\n    id\n    name\n  }\n\n  \n  labels {\n    nodes {\n      id\n      name\n    }\n  }\n\n  \n  cycle {\n    id\n    name\n    number\n  }\n\n  \n  projectMilestone {\n    id\n    name\n    targetDate\n  }\n\n  \n  parent {\n    id\n    identifier\n    title\n  }\n\n  \n  children {\n    nodes {\n      id\n      identifier\n      title\n    }\n  }\n\n\n  \n  comments {\n    nodes {\n      id\n      body\n      createdAt\n      updatedAt\n      user {\n        id\n        name\n        url\n      }\n    }\n  }\n\n";

package/dist/queries/common.js

@@ -11,6 +11,7 @@ const ISSUE_CORE_FIELDS = `
   url
   createdAt
   updatedAt
+  completedAt
 `;
 const ISSUE_STATE_FRAGMENT = `
   state {

package/dist/queries/issue-tree.d.ts

@@ -39,6 +39,8 @@ export interface IssueTreeNode {
         id: string;
         name: string;
     } | null;
+    /** ISO timestamp the node reached a terminal state; null while open. */
+    completedAt?: string | null;
     children?: {
         nodes: IssueTreeNode[];
     };

package/dist/queries/issue-tree.js

@@ -23,6 +23,10 @@ export const DEFAULT_TREE_DEPTH = 3;
 // Field set per tree node — kept minimal so the depth-N query stays small.
 // `state.type` is required client-side for `--no-include-closed` pruning;
 // `state.name` for the [Done]/[Canceled] suffix on terminal nodes.
+// `completedAt` is the moment a node reached a terminal state (null while
+// open) — consumers that reason about how long a subtree has been finished
+// (e.g. el-sop health's completed-children grace period, DEV-5454) need the
+// per-child timestamp, which no other field carries.
 // `priority` was intentionally dropped after cycle-1: the ASCII formatter
 // doesn't render it and including it inflates the query string by ~N nodes.
 const TREE_NODE_FIELDS = `
@@ -31,6 +35,7 @@ const TREE_NODE_FIELDS = `
 	title
 	state { id name type }
 	assignee { id name }
+	completedAt
 `;
 /**
  * Recursive children fragment generator. `depth=0` emits nothing (no

package/dist/queries/issues-types.d.ts

@@ -106,6 +106,7 @@ export interface IssueNode {
     url: string;
     createdAt: string;
     updatedAt: string;
+    completedAt: string | null;
     state: IdNameRef | null;
     assignee: AssigneeNode | null;
     delegate: AssigneeNode | null;

package/dist/queries/issues.d.ts

@@ -1,6 +1,6 @@
-export declare const GET_ISSUES_QUERY = "\n  query GetIssues($first: Int!, $orderBy: PaginationOrderBy) {\n    issues(\n      first: $first\n      orderBy: $orderBy\n      filter: {\n        state: { type: { neq: \"completed\" } }\n      }\n    ) {\n      nodes {\n        \n  \n  id\n  identifier\n  title\n  description\n  summary { content generationStatus }\n  branchName\n  priority\n  estimate\n  dueDate\n  url\n  createdAt\n  updatedAt\n\n  \n  state {\n    id\n    name\n    type\n  }\n\n  \n  assignee {\n    id\n    name\n    url\n  }\n\n  \n  delegate {\n    id\n    name\n    url\n  }\n\n  \n  team {\n    id\n    key\n    name\n  }\n\n  \n  project {\n    id\n    name\n  }\n\n  \n  labels {\n    nodes {\n      id\n      name\n    }\n  }\n\n  \n  cycle {\n    id\n    name\n    number\n  }\n\n  \n  projectMilestone {\n    id\n    name\n    targetDate\n  }\n\n  \n  parent {\n    id\n    identifier\n    title\n  }\n\n  \n  children {\n    nodes {\n      id\n      identifier\n      title\n    }\n  }\n\n\n      }\n    }\n  }\n";
-export declare const SEARCH_ISSUES_QUERY = "\n  query SearchIssues($term: String!, $first: Int!) {\n    searchIssues(term: $term, first: $first, includeArchived: false) {\n      nodes {\n        \n  \n  id\n  identifier\n  title\n  description\n  summary { content generationStatus }\n  branchName\n  priority\n  estimate\n  dueDate\n  url\n  createdAt\n  updatedAt\n\n  \n  state {\n    id\n    name\n    type\n  }\n\n  \n  assignee {\n    id\n    name\n    url\n  }\n\n  \n  delegate {\n    id\n    name\n    url\n  }\n\n  \n  team {\n    id\n    key\n    name\n  }\n\n  \n  project {\n    id\n    name\n  }\n\n  \n  labels {\n    nodes {\n      id\n      name\n    }\n  }\n\n  \n  cycle {\n    id\n    name\n    number\n  }\n\n  \n  projectMilestone {\n    id\n    name\n    targetDate\n  }\n\n  \n  parent {\n    id\n    identifier\n    title\n  }\n\n  \n  children {\n    nodes {\n      id\n      identifier\n      title\n    }\n  }\n\n\n      }\n    }\n  }\n";
-export declare const FILTERED_SEARCH_ISSUES_QUERY = "\n  query FilteredSearchIssues(\n    $first: Int!\n    $filter: IssueFilter\n    $orderBy: PaginationOrderBy\n  ) {\n    issues(\n      first: $first\n      filter: $filter\n      orderBy: $orderBy\n      includeArchived: false\n    ) {\n      nodes {\n        \n  \n  id\n  identifier\n  title\n  description\n  summary { content generationStatus }\n  branchName\n  priority\n  estimate\n  dueDate\n  url\n  createdAt\n  updatedAt\n\n  \n  state {\n    id\n    name\n    type\n  }\n\n  \n  assignee {\n    id\n    name\n    url\n  }\n\n  \n  delegate {\n    id\n    name\n    url\n  }\n\n  \n  team {\n    id\n    key\n    name\n  }\n\n  \n  project {\n    id\n    name\n  }\n\n  \n  labels {\n    nodes {\n      id\n      name\n    }\n  }\n\n  \n  cycle {\n    id\n    name\n    number\n  }\n\n  \n  projectMilestone {\n    id\n    name\n    targetDate\n  }\n\n  \n  parent {\n    id\n    identifier\n    title\n  }\n\n  \n  children {\n    nodes {\n      id\n      identifier\n      title\n    }\n  }\n\n\n      }\n    }\n  }\n";
+export declare const GET_ISSUES_QUERY = "\n  query GetIssues($first: Int!, $orderBy: PaginationOrderBy) {\n    issues(\n      first: $first\n      orderBy: $orderBy\n      filter: {\n        state: { type: { neq: \"completed\" } }\n      }\n    ) {\n      nodes {\n        \n  \n  id\n  identifier\n  title\n  description\n  summary { content generationStatus }\n  branchName\n  priority\n  estimate\n  dueDate\n  url\n  createdAt\n  updatedAt\n  completedAt\n\n  \n  state {\n    id\n    name\n    type\n  }\n\n  \n  assignee {\n    id\n    name\n    url\n  }\n\n  \n  delegate {\n    id\n    name\n    url\n  }\n\n  \n  team {\n    id\n    key\n    name\n  }\n\n  \n  project {\n    id\n    name\n  }\n\n  \n  labels {\n    nodes {\n      id\n      name\n    }\n  }\n\n  \n  cycle {\n    id\n    name\n    number\n  }\n\n  \n  projectMilestone {\n    id\n    name\n    targetDate\n  }\n\n  \n  parent {\n    id\n    identifier\n    title\n  }\n\n  \n  children {\n    nodes {\n      id\n      identifier\n      title\n    }\n  }\n\n\n      }\n    }\n  }\n";
+export declare const SEARCH_ISSUES_QUERY = "\n  query SearchIssues($term: String!, $first: Int!) {\n    searchIssues(term: $term, first: $first, includeArchived: false) {\n      nodes {\n        \n  \n  id\n  identifier\n  title\n  description\n  summary { content generationStatus }\n  branchName\n  priority\n  estimate\n  dueDate\n  url\n  createdAt\n  updatedAt\n  completedAt\n\n  \n  state {\n    id\n    name\n    type\n  }\n\n  \n  assignee {\n    id\n    name\n    url\n  }\n\n  \n  delegate {\n    id\n    name\n    url\n  }\n\n  \n  team {\n    id\n    key\n    name\n  }\n\n  \n  project {\n    id\n    name\n  }\n\n  \n  labels {\n    nodes {\n      id\n      name\n    }\n  }\n\n  \n  cycle {\n    id\n    name\n    number\n  }\n\n  \n  projectMilestone {\n    id\n    name\n    targetDate\n  }\n\n  \n  parent {\n    id\n    identifier\n    title\n  }\n\n  \n  children {\n    nodes {\n      id\n      identifier\n      title\n    }\n  }\n\n\n      }\n    }\n  }\n";
+export declare const FILTERED_SEARCH_ISSUES_QUERY = "\n  query FilteredSearchIssues(\n    $first: Int!\n    $filter: IssueFilter\n    $orderBy: PaginationOrderBy\n  ) {\n    issues(\n      first: $first\n      filter: $filter\n      orderBy: $orderBy\n      includeArchived: false\n    ) {\n      nodes {\n        \n  \n  id\n  identifier\n  title\n  description\n  summary { content generationStatus }\n  branchName\n  priority\n  estimate\n  dueDate\n  url\n  createdAt\n  updatedAt\n  completedAt\n\n  \n  state {\n    id\n    name\n    type\n  }\n\n  \n  assignee {\n    id\n    name\n    url\n  }\n\n  \n  delegate {\n    id\n    name\n    url\n  }\n\n  \n  team {\n    id\n    key\n    name\n  }\n\n  \n  project {\n    id\n    name\n  }\n\n  \n  labels {\n    nodes {\n      id\n      name\n    }\n  }\n\n  \n  cycle {\n    id\n    name\n    number\n  }\n\n  \n  projectMilestone {\n    id\n    name\n    targetDate\n  }\n\n  \n  parent {\n    id\n    identifier\n    title\n  }\n\n  \n  children {\n    nodes {\n      id\n      identifier\n      title\n    }\n  }\n\n\n      }\n    }\n  }\n";
 /**
  * Batch-resolves a search's team/project/assignee/delegate filter inputs.
  *
@@ -11,8 +11,8 @@ export declare const FILTERED_SEARCH_ISSUES_QUERY = "\n  query FilteredSearchIss
  * name-resolution arm is needed here.)
  */
 export declare const BATCH_RESOLVE_FOR_SEARCH_QUERY = "\n  query BatchResolveForSearch(\n    $teamKey: String\n    $teamName: String\n    $projectName: String\n    $hasProjectName: Boolean = false\n    $assigneeEmail: String\n    $delegateEmail: String\n  ) {\n    teams(\n      filter: {\n        or: [\n          { key: { eq: $teamKey } }\n          { name: { eqIgnoreCase: $teamName } }\n        ]\n      }\n      first: 1\n    ) {\n      nodes {\n        id\n        key\n        name\n      }\n    }\n\n    projects(\n      filter: { name: { eqIgnoreCase: $projectName } }\n      first: 1\n    ) @include(if: $hasProjectName) {\n      nodes {\n        id\n        name\n      }\n    }\n\n    users(filter: { email: { eq: $assigneeEmail } }, first: 1) {\n      nodes {\n        id\n        name\n        email\n      }\n    }\n\n    delegates: users(filter: { email: { eq: $delegateEmail } }, first: 1) {\n      nodes {\n        id\n        name\n        email\n      }\n    }\n  }\n";
-export declare const GET_ISSUE_BY_ID_QUERY = "\n  query GetIssue($id: String!) {\n    issue(id: $id) {\n      \n  \n  \n  id\n  identifier\n  title\n  description\n  summary { content generationStatus }\n  branchName\n  priority\n  estimate\n  dueDate\n  url\n  createdAt\n  updatedAt\n\n  \n  state {\n    id\n    name\n    type\n  }\n\n  \n  assignee {\n    id\n    name\n    url\n  }\n\n  \n  delegate {\n    id\n    name\n    url\n  }\n\n  \n  team {\n    id\n    key\n    name\n  }\n\n  \n  project {\n    id\n    name\n  }\n\n  \n  labels {\n    nodes {\n      id\n      name\n    }\n  }\n\n  \n  cycle {\n    id\n    name\n    number\n  }\n\n  \n  projectMilestone {\n    id\n    name\n    targetDate\n  }\n\n  \n  parent {\n    id\n    identifier\n    title\n  }\n\n  \n  children {\n    nodes {\n      id\n      identifier\n      title\n    }\n  }\n\n\n  \n  comments {\n    nodes {\n      id\n      body\n      createdAt\n      updatedAt\n      user {\n        id\n        name\n        url\n      }\n    }\n  }\n\n\n    }\n  }\n";
-export declare const GET_ISSUE_BY_IDENTIFIER_QUERY = "\n  query GetIssueByIdentifier($teamKey: String!, $number: Float!) {\n    issues(\n      filter: {\n        team: { key: { eq: $teamKey } }\n        number: { eq: $number }\n      }\n      first: 1\n    ) {\n      nodes {\n        \n  \n  \n  id\n  identifier\n  title\n  description\n  summary { content generationStatus }\n  branchName\n  priority\n  estimate\n  dueDate\n  url\n  createdAt\n  updatedAt\n\n  \n  state {\n    id\n    name\n    type\n  }\n\n  \n  assignee {\n    id\n    name\n    url\n  }\n\n  \n  delegate {\n    id\n    name\n    url\n  }\n\n  \n  team {\n    id\n    key\n    name\n  }\n\n  \n  project {\n    id\n    name\n  }\n\n  \n  labels {\n    nodes {\n      id\n      name\n    }\n  }\n\n  \n  cycle {\n    id\n    name\n    number\n  }\n\n  \n  projectMilestone {\n    id\n    name\n    targetDate\n  }\n\n  \n  parent {\n    id\n    identifier\n    title\n  }\n\n  \n  children {\n    nodes {\n      id\n      identifier\n      title\n    }\n  }\n\n\n  \n  comments {\n    nodes {\n      id\n      body\n      createdAt\n      updatedAt\n      user {\n        id\n        name\n        url\n      }\n    }\n  }\n\n\n      }\n    }\n  }\n";
+export declare const GET_ISSUE_BY_ID_QUERY = "\n  query GetIssue($id: String!) {\n    issue(id: $id) {\n      \n  \n  \n  id\n  identifier\n  title\n  description\n  summary { content generationStatus }\n  branchName\n  priority\n  estimate\n  dueDate\n  url\n  createdAt\n  updatedAt\n  completedAt\n\n  \n  state {\n    id\n    name\n    type\n  }\n\n  \n  assignee {\n    id\n    name\n    url\n  }\n\n  \n  delegate {\n    id\n    name\n    url\n  }\n\n  \n  team {\n    id\n    key\n    name\n  }\n\n  \n  project {\n    id\n    name\n  }\n\n  \n  labels {\n    nodes {\n      id\n      name\n    }\n  }\n\n  \n  cycle {\n    id\n    name\n    number\n  }\n\n  \n  projectMilestone {\n    id\n    name\n    targetDate\n  }\n\n  \n  parent {\n    id\n    identifier\n    title\n  }\n\n  \n  children {\n    nodes {\n      id\n      identifier\n      title\n    }\n  }\n\n\n  \n  comments {\n    nodes {\n      id\n      body\n      createdAt\n      updatedAt\n      user {\n        id\n        name\n        url\n      }\n    }\n  }\n\n\n    }\n  }\n";
+export declare const GET_ISSUE_BY_IDENTIFIER_QUERY = "\n  query GetIssueByIdentifier($teamKey: String!, $number: Float!) {\n    issues(\n      filter: {\n        team: { key: { eq: $teamKey } }\n        number: { eq: $number }\n      }\n      first: 1\n    ) {\n      nodes {\n        \n  \n  \n  id\n  identifier\n  title\n  description\n  summary { content generationStatus }\n  branchName\n  priority\n  estimate\n  dueDate\n  url\n  createdAt\n  updatedAt\n  completedAt\n\n  \n  state {\n    id\n    name\n    type\n  }\n\n  \n  assignee {\n    id\n    name\n    url\n  }\n\n  \n  delegate {\n    id\n    name\n    url\n  }\n\n  \n  team {\n    id\n    key\n    name\n  }\n\n  \n  project {\n    id\n    name\n  }\n\n  \n  labels {\n    nodes {\n      id\n      name\n    }\n  }\n\n  \n  cycle {\n    id\n    name\n    number\n  }\n\n  \n  projectMilestone {\n    id\n    name\n    targetDate\n  }\n\n  \n  parent {\n    id\n    identifier\n    title\n  }\n\n  \n  children {\n    nodes {\n      id\n      identifier\n      title\n    }\n  }\n\n\n  \n  comments {\n    nodes {\n      id\n      body\n      createdAt\n      updatedAt\n      user {\n        id\n        name\n        url\n      }\n    }\n  }\n\n\n      }\n    }\n  }\n";
 /**
  * Batch issue fetch. Used by `issues read <id...>` (DEV-4477) to collapse
  * N parallel single-issue queries into one round-trip. The `$filter` is
@@ -34,7 +34,7 @@ export declare const GET_ISSUE_BY_IDENTIFIER_QUERY = "\n  query GetIssueByIdenti
  * CLAUDE.md ("Performance-critical loops where the SDK's per-edge
  * resolver promises produce N+1 round-trips") explicitly authorizes this.
  */
-export declare const BATCH_GET_ISSUES_QUERY = "\n  query BatchGetIssues($filter: IssueFilter!, $first: Int!) {\n    issues(filter: $filter, first: $first) {\n      nodes {\n        \n  \n  \n  id\n  identifier\n  title\n  description\n  summary { content generationStatus }\n  branchName\n  priority\n  estimate\n  dueDate\n  url\n  createdAt\n  updatedAt\n\n  \n  state {\n    id\n    name\n    type\n  }\n\n  \n  assignee {\n    id\n    name\n    url\n  }\n\n  \n  delegate {\n    id\n    name\n    url\n  }\n\n  \n  team {\n    id\n    key\n    name\n  }\n\n  \n  project {\n    id\n    name\n  }\n\n  \n  labels {\n    nodes {\n      id\n      name\n    }\n  }\n\n  \n  cycle {\n    id\n    name\n    number\n  }\n\n  \n  projectMilestone {\n    id\n    name\n    targetDate\n  }\n\n  \n  parent {\n    id\n    identifier\n    title\n  }\n\n  \n  children {\n    nodes {\n      id\n      identifier\n      title\n    }\n  }\n\n\n  \n  comments {\n    nodes {\n      id\n      body\n      createdAt\n      updatedAt\n      user {\n        id\n        name\n        url\n      }\n    }\n  }\n\n\n      }\n    }\n  }\n";
+export declare const BATCH_GET_ISSUES_QUERY = "\n  query BatchGetIssues($filter: IssueFilter!, $first: Int!) {\n    issues(filter: $filter, first: $first) {\n      nodes {\n        \n  \n  \n  id\n  identifier\n  title\n  description\n  summary { content generationStatus }\n  branchName\n  priority\n  estimate\n  dueDate\n  url\n  createdAt\n  updatedAt\n  completedAt\n\n  \n  state {\n    id\n    name\n    type\n  }\n\n  \n  assignee {\n    id\n    name\n    url\n  }\n\n  \n  delegate {\n    id\n    name\n    url\n  }\n\n  \n  team {\n    id\n    key\n    name\n  }\n\n  \n  project {\n    id\n    name\n  }\n\n  \n  labels {\n    nodes {\n      id\n      name\n    }\n  }\n\n  \n  cycle {\n    id\n    name\n    number\n  }\n\n  \n  projectMilestone {\n    id\n    name\n    targetDate\n  }\n\n  \n  parent {\n    id\n    identifier\n    title\n  }\n\n  \n  children {\n    nodes {\n      id\n      identifier\n      title\n    }\n  }\n\n\n  \n  comments {\n    nodes {\n      id\n      body\n      createdAt\n      updatedAt\n      user {\n        id\n        name\n        url\n      }\n    }\n  }\n\n\n      }\n    }\n  }\n";
 /**
  * Batch-resolves an update's project/milestone/issue inputs.
  *
@@ -45,8 +45,8 @@ export declare const BATCH_GET_ISSUES_QUERY = "\n  query BatchGetIssues($filter:
  * `--project-milestone` name resolution; a name uses `projectsByName`.
  */
 export declare const BATCH_RESOLVE_FOR_UPDATE_QUERY = "\n  query BatchResolveForUpdate(\n    $projectName: String\n    $projectId: ID\n    $hasProjectName: Boolean = false\n    $hasProjectId: Boolean = false\n    $teamKey: String\n    $issueNumber: Float\n    $milestoneName: String\n    $hasMilestoneName: Boolean = false\n  ) {\n    projectsByName: projects(\n      filter: { name: { eqIgnoreCase: $projectName } }\n      first: 5\n    ) @include(if: $hasProjectName) {\n      nodes {\n        id\n        name\n        teams {\n          nodes { id key }\n        }\n        projectMilestones {\n          nodes {\n            id\n            name\n          }\n        }\n      }\n    }\n\n    projectsById: projects(\n      filter: { id: { eq: $projectId } }\n      first: 1\n    ) @include(if: $hasProjectId) {\n      nodes {\n        id\n        name\n        projectMilestones {\n          nodes {\n            id\n            name\n          }\n        }\n      }\n    }\n\n    milestones: projectMilestones(\n      filter: { name: { eq: $milestoneName } }\n      first: 1\n    ) @include(if: $hasMilestoneName) {\n      nodes {\n        id\n        name\n      }\n    }\n\n    issues(\n      filter: {\n        and: [\n          { team: { key: { eq: $teamKey } } }\n          { number: { eq: $issueNumber } }\n        ]\n      }\n      first: 1\n    ) {\n      nodes {\n        id\n        identifier\n        team {\n          id\n          key\n        }\n        labels {\n          nodes {\n            id\n            name\n          }\n        }\n        project {\n          id\n          projectMilestones {\n            nodes {\n              id\n              name\n            }\n          }\n        }\n      }\n    }\n  }\n";
-export declare const CREATE_ISSUE_MUTATION = "\n  mutation CreateIssue($input: IssueCreateInput!) {\n    issueCreate(input: $input) {\n      success\n      issue {\n        \n  \n  id\n  identifier\n  title\n  description\n  summary { content generationStatus }\n  branchName\n  priority\n  estimate\n  dueDate\n  url\n  createdAt\n  updatedAt\n\n  \n  state {\n    id\n    name\n    type\n  }\n\n  \n  assignee {\n    id\n    name\n    url\n  }\n\n  \n  delegate {\n    id\n    name\n    url\n  }\n\n  \n  team {\n    id\n    key\n    name\n  }\n\n  \n  project {\n    id\n    name\n  }\n\n  \n  labels {\n    nodes {\n      id\n      name\n    }\n  }\n\n  \n  cycle {\n    id\n    name\n    number\n  }\n\n  \n  projectMilestone {\n    id\n    name\n    targetDate\n  }\n\n  \n  parent {\n    id\n    identifier\n    title\n  }\n\n  \n  children {\n    nodes {\n      id\n      identifier\n      title\n    }\n  }\n\n\n      }\n    }\n  }\n";
-export declare const UPDATE_ISSUE_MUTATION = "\n  mutation UpdateIssue($id: String!, $input: IssueUpdateInput!) {\n    issueUpdate(id: $id, input: $input) {\n      success\n      issue {\n        \n  \n  id\n  identifier\n  title\n  description\n  summary { content generationStatus }\n  branchName\n  priority\n  estimate\n  dueDate\n  url\n  createdAt\n  updatedAt\n\n  \n  state {\n    id\n    name\n    type\n  }\n\n  \n  assignee {\n    id\n    name\n    url\n  }\n\n  \n  delegate {\n    id\n    name\n    url\n  }\n\n  \n  team {\n    id\n    key\n    name\n  }\n\n  \n  project {\n    id\n    name\n  }\n\n  \n  labels {\n    nodes {\n      id\n      name\n    }\n  }\n\n  \n  cycle {\n    id\n    name\n    number\n  }\n\n  \n  projectMilestone {\n    id\n    name\n    targetDate\n  }\n\n  \n  parent {\n    id\n    identifier\n    title\n  }\n\n  \n  children {\n    nodes {\n      id\n      identifier\n      title\n    }\n  }\n\n\n      }\n    }\n  }\n";
+export declare const CREATE_ISSUE_MUTATION = "\n  mutation CreateIssue($input: IssueCreateInput!) {\n    issueCreate(input: $input) {\n      success\n      issue {\n        \n  \n  id\n  identifier\n  title\n  description\n  summary { content generationStatus }\n  branchName\n  priority\n  estimate\n  dueDate\n  url\n  createdAt\n  updatedAt\n  completedAt\n\n  \n  state {\n    id\n    name\n    type\n  }\n\n  \n  assignee {\n    id\n    name\n    url\n  }\n\n  \n  delegate {\n    id\n    name\n    url\n  }\n\n  \n  team {\n    id\n    key\n    name\n  }\n\n  \n  project {\n    id\n    name\n  }\n\n  \n  labels {\n    nodes {\n      id\n      name\n    }\n  }\n\n  \n  cycle {\n    id\n    name\n    number\n  }\n\n  \n  projectMilestone {\n    id\n    name\n    targetDate\n  }\n\n  \n  parent {\n    id\n    identifier\n    title\n  }\n\n  \n  children {\n    nodes {\n      id\n      identifier\n      title\n    }\n  }\n\n\n      }\n    }\n  }\n";
+export declare const UPDATE_ISSUE_MUTATION = "\n  mutation UpdateIssue($id: String!, $input: IssueUpdateInput!) {\n    issueUpdate(id: $id, input: $input) {\n      success\n      issue {\n        \n  \n  id\n  identifier\n  title\n  description\n  summary { content generationStatus }\n  branchName\n  priority\n  estimate\n  dueDate\n  url\n  createdAt\n  updatedAt\n  completedAt\n\n  \n  state {\n    id\n    name\n    type\n  }\n\n  \n  assignee {\n    id\n    name\n    url\n  }\n\n  \n  delegate {\n    id\n    name\n    url\n  }\n\n  \n  team {\n    id\n    key\n    name\n  }\n\n  \n  project {\n    id\n    name\n  }\n\n  \n  labels {\n    nodes {\n      id\n      name\n    }\n  }\n\n  \n  cycle {\n    id\n    name\n    number\n  }\n\n  \n  projectMilestone {\n    id\n    name\n    targetDate\n  }\n\n  \n  parent {\n    id\n    identifier\n    title\n  }\n\n  \n  children {\n    nodes {\n      id\n      identifier\n      title\n    }\n  }\n\n\n      }\n    }\n  }\n";
 export declare const ARCHIVE_ISSUE_MUTATION = "\n  mutation ArchiveIssue($id: String!) {\n    issueArchive(id: $id) {\n      success\n      lastSyncId\n      entity {\n        id\n      }\n    }\n  }\n";
 export declare const DELETE_ISSUE_MUTATION = "\n  mutation DeleteIssue($id: String!, $permanentlyDelete: Boolean) {\n    issueDelete(id: $id, permanentlyDelete: $permanentlyDelete) {\n      success\n      lastSyncId\n      entity {\n        id\n      }\n    }\n  }\n";
 /**

package/dist/queries/project-milestones.d.ts

@@ -1,5 +1,5 @@
 export declare const LIST_PROJECT_MILESTONES_QUERY = "\n  query ListProjectMilestones($projectId: String!, $first: Int!) {\n    project(id: $projectId) {\n      id\n      name\n      projectMilestones(first: $first) {\n        nodes {\n          id\n          name\n          description\n          targetDate\n          sortOrder\n          createdAt\n          updatedAt\n        }\n      }\n    }\n  }\n";
-export declare const GET_PROJECT_MILESTONE_BY_ID_QUERY = "\n  query GetProjectMilestone($id: String!, $issuesFirst: Int) {\n    projectMilestone(id: $id) {\n      id\n      name\n      description\n      targetDate\n      sortOrder\n      createdAt\n      updatedAt\n      project {\n        id\n        name\n      }\n      issues(first: $issuesFirst) {\n        nodes {\n          \n  \n  id\n  identifier\n  title\n  description\n  summary { content generationStatus }\n  branchName\n  priority\n  estimate\n  dueDate\n  url\n  createdAt\n  updatedAt\n\n  \n  state {\n    id\n    name\n    type\n  }\n\n  \n  assignee {\n    id\n    name\n    url\n  }\n\n  \n  delegate {\n    id\n    name\n    url\n  }\n\n  \n  team {\n    id\n    key\n    name\n  }\n\n  \n  project {\n    id\n    name\n  }\n\n  \n  labels {\n    nodes {\n      id\n      name\n    }\n  }\n\n  \n  cycle {\n    id\n    name\n    number\n  }\n\n  \n  projectMilestone {\n    id\n    name\n    targetDate\n  }\n\n  \n  parent {\n    id\n    identifier\n    title\n  }\n\n  \n  children {\n    nodes {\n      id\n      identifier\n      title\n    }\n  }\n\n\n        }\n      }\n    }\n  }\n";
+export declare const GET_PROJECT_MILESTONE_BY_ID_QUERY = "\n  query GetProjectMilestone($id: String!, $issuesFirst: Int) {\n    projectMilestone(id: $id) {\n      id\n      name\n      description\n      targetDate\n      sortOrder\n      createdAt\n      updatedAt\n      project {\n        id\n        name\n      }\n      issues(first: $issuesFirst) {\n        nodes {\n          \n  \n  id\n  identifier\n  title\n  description\n  summary { content generationStatus }\n  branchName\n  priority\n  estimate\n  dueDate\n  url\n  createdAt\n  updatedAt\n  completedAt\n\n  \n  state {\n    id\n    name\n    type\n  }\n\n  \n  assignee {\n    id\n    name\n    url\n  }\n\n  \n  delegate {\n    id\n    name\n    url\n  }\n\n  \n  team {\n    id\n    key\n    name\n  }\n\n  \n  project {\n    id\n    name\n  }\n\n  \n  labels {\n    nodes {\n      id\n      name\n    }\n  }\n\n  \n  cycle {\n    id\n    name\n    number\n  }\n\n  \n  projectMilestone {\n    id\n    name\n    targetDate\n  }\n\n  \n  parent {\n    id\n    identifier\n    title\n  }\n\n  \n  children {\n    nodes {\n      id\n      identifier\n      title\n    }\n  }\n\n\n        }\n      }\n    }\n  }\n";
 export declare const FIND_PROJECT_MILESTONE_BY_NAME_SCOPED = "\n  query FindProjectMilestoneScoped($name: String!, $projectId: String!) {\n    project(id: $projectId) {\n      projectMilestones(filter: { name: { eq: $name } }, first: 10) {\n        nodes {\n          id\n          name\n          targetDate\n          sortOrder\n          project {\n            id\n            name\n          }\n        }\n      }\n    }\n  }\n";
 export declare const FIND_PROJECT_MILESTONE_BY_NAME_GLOBAL = "\n  query FindProjectMilestoneGlobal($name: String!) {\n    projectMilestones(filter: { name: { eq: $name } }, first: 10) {\n      nodes {\n        id\n        name\n        targetDate\n        sortOrder\n        project {\n          id\n          name\n        }\n      }\n    }\n  }\n";
 export declare const CREATE_PROJECT_MILESTONE_MUTATION = "\n  mutation CreateProjectMilestone($projectId: String!, $name: String!, $description: String, $targetDate: TimelessDate) {\n    projectMilestoneCreate(input: {\n      projectId: $projectId\n      name: $name\n      description: $description\n      targetDate: $targetDate\n    }) {\n      success\n      projectMilestone {\n        id\n        name\n        description\n        targetDate\n        sortOrder\n        createdAt\n        updatedAt\n        project {\n          id\n          name\n        }\n      }\n    }\n  }\n";

package/dist/types/linear.d.ts

@@ -114,6 +114,7 @@ export interface LinearIssue {
     assignee?: UserRef;
     branchName?: string;
     comments?: LinearComment[];
+    completedAt?: string;
     createdAt: string;
     cycle?: CycleRef;
     delegate?: UserRef;

package/dist/utils/formatters/summary.js

@@ -301,6 +301,7 @@ const ISSUE_SUMMARY_SYNONYMS = {
     owner: "assignee",
     createdat: "created",
     updatedat: "updated",
+    completedat: "completed",
     prioritylabel: "priority",
     projectmilestone: "milestone",
 };
@@ -316,6 +317,7 @@ function buildIssueHeaderFields(issue) {
         { label: "Estimate", value: s(issue.estimate) },
         { label: "Created", value: s(issue.createdAt) },
         { label: "Updated", value: s(issue.updatedAt) },
+        { label: "Completed", value: s(issue.completedAt) },
         { label: "URL", value: s(issue.url) },
     ];
 }
@@ -424,6 +426,11 @@ const ISSUE_LIST_EXTRAS = {
         minWidth: 7,
         extract: (i) => s(i.updatedAt).slice(0, 10),
     },
+    completedat: {
+        header: "COMPLETED",
+        minWidth: 9,
+        extract: (i) => s(i.completedAt).slice(0, 10),
+    },
     team: {
         header: "TEAM",
         minWidth: 4,

package/dist/utils/gate-telemetry.d.ts

@@ -25,7 +25,13 @@ export declare function decideGateLedger(opts: {
 export interface GateEvent {
     /** Stable gate id, e.g. `issues-create-dup`. */
     gate: string;
-    outcome: "blocked" | "overridden";
+    /**
+     * `blocked` — the gate stopped creation. `overridden` — a gate-specific
+     * override flag let a would-block proceed. `fail-open` — the gate could not
+     * evaluate (infra/service error) and let creation proceed rather than block
+     * on trouble; tracked so degradation is measurable (DEV-5378).
+     */
+    outcome: "blocked" | "overridden" | "fail-open";
     /** Highest candidate similarity that triggered the gate (0–1). */
     topScore?: number;
     /** How many candidates crossed the threshold. */

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

@@ -3,7 +3,7 @@ import { resolveUserDisplayName } from "../config/resolver.js";
 import { ARCHIVE_ISSUE_MUTATION, BATCH_GET_ISSUES_QUERY, BATCH_RESOLVE_FOR_CREATE_QUERY, BATCH_RESOLVE_FOR_SEARCH_QUERY, BATCH_RESOLVE_FOR_UPDATE_QUERY, buildResolveLabelsByNameQuery, CREATE_ISSUE_MUTATION, DELETE_ISSUE_MUTATION, FILTERED_SEARCH_ISSUES_QUERY, GET_ISSUE_BY_ID_QUERY, GET_ISSUE_BY_IDENTIFIER_QUERY, GET_ISSUE_CLAIM_CONTEXT_QUERY, GET_ISSUE_START_CONTEXT_QUERY, GET_ISSUE_TEAM_QUERY, GET_ISSUES_QUERY, SEARCH_ISSUES_QUERY, TEAM_STARTED_STATUSES_QUERY, UPDATE_ISSUE_MUTATION, } from "../queries/issues.js";
 import { CREATE_LABEL_MUTATION } from "../queries/labels.js";
 import { TERMINAL_STATE_TYPES } from "../types/linear.js";
-import { toISOStringOrNow } from "./date-format.js";
+import { toISOStringOrNow, toISOStringOrUndefined } from "./date-format.js";
 import { extractEmbeds } from "./embed-parser.js";
 import { multipleMatchesError, notFoundError } from "./error-messages.js";
 import { parseIssueIdentifier, tryParseIssueIdentifier, } from "./identifier-parser.js";
@@ -1270,6 +1270,9 @@ export class GraphQLIssuesService {
                 : [],
             createdAt: toISOStringOrNow(issue.createdAt),
             updatedAt: toISOStringOrNow(issue.updatedAt),
+            // Nullable, not `-OrNow`: an open issue has no completion, so it must
+            // stay `undefined` rather than be fabricated as the current time.
+            completedAt: toISOStringOrUndefined(issue.completedAt),
         };
     }
     transformIssueCoreFields(issue) {

package/package.json

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