@enrichlayer/el-linear 1.16.0 → 1.18.0

package/dist/commands/comments.js

@@ -1,6 +1,6 @@
 import { readFileSync } from "node:fs";
 import { resolveUserDisplayName } from "../config/resolver.js";
-import { CREATE_COMMENT_MUTATION, LIST_COMMENTS_QUERY, UPDATE_COMMENT_MUTATION, } from "../queries/comments.js";
+import { CREATE_COMMENT_MUTATION, DELETE_COMMENT_MUTATION, LIST_COMMENTS_QUERY, UPDATE_COMMENT_MUTATION, } from "../queries/comments.js";
 import { autoLinkReferences, } from "../utils/auto-link-references.js";
 import { applyFooter } from "../utils/footer.js";
 import { createGraphQLService, } from "../utils/graphql-service.js";
@@ -260,6 +260,15 @@ async function handleListComments(issueId, options, command) {
         },
     });
 }
+async function handleDeleteComment(commentId, _options, command) {
+    const rootOpts = getRootOpts(command);
+    const graphQLService = await createGraphQLService(rootOpts);
+    const result = await graphQLService.rawRequest(DELETE_COMMENT_MUTATION, { id: commentId });
+    if (!result.commentDelete.success) {
+        throw new Error(`Failed to delete comment "${commentId}"`);
+    }
+    outputSuccess({ id: commentId, deleted: true });
+}
 export function setupCommentsCommands(program) {
     const comments = program
         .command("comments")
@@ -291,4 +300,11 @@ export function setupCommentsCommands(program) {
         .addHelpText("after", "\nBoth UUID and identifiers like ABC-123 are supported.")
         .option("-l, --limit <number>", "limit results", "25")
         .action(handleAsyncCommand(handleListComments));
+    comments
+        .command("delete <commentId>")
+        .alias("remove")
+        .alias("rm")
+        .description("Delete a comment by its id.")
+        .addHelpText("after", "\nTakes a comment id (the `id` field from `comments list` / `comments create`), not an issue identifier.")
+        .action(handleAsyncCommand(handleDeleteComment));
 }

package/dist/commands/documents.js

@@ -34,7 +34,7 @@ async function handleCreateDocument(options, command) {
         title: options.title,
         content: options.content,
         projectId: options.project
-            ? await linearService.resolveProjectId(options.project)
+            ? await linearService.resolveProjectId(options.project, options.team)
             : undefined,
         teamId: options.team
             ? await linearService.resolveTeamId(options.team)

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

@@ -13,5 +13,52 @@ export declare function toBranchName(linearBranchName: string, prefix?: string):
 /**
  * Check out a new git branch. Warns and skips if not in a git repo.
  * Throws if the branch already exists.
+ *
+ * Returns `true` if the branch was actually checked out, `false` if the
+ * checkout was skipped (not in a git repo). Callers gate follow-on work
+ * (e.g. writing the `branch.<branch>.linearIssue` marker) on the result so
+ * they don't emit a second, contradictory warning about a branch that was
+ * never created.
+ */
+export declare function gitCheckoutBranch(branchName: string): boolean;
+/**
+ * Extract the canonical (uppercase) Linear identifier embedded in a branch
+ * name — `feature/DEV-4293-slug` → `DEV-4293`, `dev-4293-slug` → `DEV-4293`.
+ * Returns null when the branch carries no identifier token.
+ */
+export declare function extractIssueIdentifierFromBranch(branch: string): string | null;
+/**
+ * Record the Linear issue a branch implements as durable git metadata:
+ * `git config branch.<branch>.linearIssue <identifier>`. This is the signal
+ * DEV-4241's PreToolUse hook reads to confirm a workflow was established
+ * before allowing tracked-file edits — far more robust than parsing the
+ * branch name shape (which legitimately varies: `dev-4083-slug`,
+ * `fe-630-slug`, `emw-280-slug`), and it stays fast + offline (a local
+ * git config read, no API call).
+ *
+ * Best-effort by design: a failure to write the marker must never abort the
+ * issue-creation flow that triggered it. Callers in a known-good repo
+ * context wrap this and warn on failure; the standalone `mark-branch`
+ * command does its own repo/branch validation first so it can surface a
+ * clear error instead.
+ *
+ * No `--` ref-terminator (unlike the checkout/rename calls above): `git
+ * config <key> <value>` takes exactly two positional operands, the key is
+ * always our `branch.`-prefixed literal, and a value beginning with `-` is
+ * stored verbatim rather than parsed as a flag — so there's no
+ * flag-injection surface to defend here.
+ */
+export declare function setBranchLinearIssue(branch: string, identifier: string): void;
+/**
+ * Read back the `branch.<branch>.linearIssue` marker, or null when unset.
+ */
+export declare function getBranchLinearIssue(branch: string): string | null;
+/**
+ * Current branch's short name, or null when detached / not in a repo.
+ *
+ * Uses `symbolic-ref` rather than `rev-parse --abbrev-ref`: the former
+ * resolves the name even on an unborn branch (fresh repo, no commits yet)
+ * and still fails — yielding null — on a detached HEAD, which is exactly
+ * the "no named branch" signal callers want.
  */
-export declare function gitCheckoutBranch(branchName: string): void;
+export declare function currentGitBranch(): string | null;

package/dist/commands/issues/branch.js

@@ -25,6 +25,12 @@ export function toBranchName(linearBranchName, prefix = "feature/") {
 /**
  * Check out a new git branch. Warns and skips if not in a git repo.
  * Throws if the branch already exists.
+ *
+ * Returns `true` if the branch was actually checked out, `false` if the
+ * checkout was skipped (not in a git repo). Callers gate follow-on work
+ * (e.g. writing the `branch.<branch>.linearIssue` marker) on the result so
+ * they don't emit a second, contradictory warning about a branch that was
+ * never created.
  */
 export function gitCheckoutBranch(branchName) {
     try {
@@ -34,7 +40,7 @@ export function gitCheckoutBranch(branchName) {
     }
     catch {
         outputWarning("Not inside a git repository — skipping branch checkout.");
-        return;
+        return false;
     }
     // `--` separates the new-branch name from any ref. Without it, a
     // branch name starting with `-` (server bug, malicious team member
@@ -45,4 +51,78 @@ export function gitCheckoutBranch(branchName) {
     // prefix callers would lose the defense without this terminator.
     // Defense-in-depth (DEV-4064).
     execFileSync("git", ["checkout", "-b", branchName, "--"], { stdio: "pipe" });
+    return true;
+}
+// First Linear-style identifier token in a branch name, in any position, so
+// it survives a configurable prefix (`feature/DEV-123-slug`) and the bare
+// Linear shape (`dev-123-slug`). Anchored on a non-word boundary so it
+// doesn't match mid-token.
+const BRANCH_IDENTIFIER_REGEX = /(?:^|[^A-Za-z0-9])([A-Za-z]+-\d+)(?![A-Za-z0-9])/;
+/**
+ * Extract the canonical (uppercase) Linear identifier embedded in a branch
+ * name — `feature/DEV-4293-slug` → `DEV-4293`, `dev-4293-slug` → `DEV-4293`.
+ * Returns null when the branch carries no identifier token.
+ */
+export function extractIssueIdentifierFromBranch(branch) {
+    const match = branch.match(BRANCH_IDENTIFIER_REGEX);
+    return match ? match[1].toUpperCase() : null;
+}
+/**
+ * Record the Linear issue a branch implements as durable git metadata:
+ * `git config branch.<branch>.linearIssue <identifier>`. This is the signal
+ * DEV-4241's PreToolUse hook reads to confirm a workflow was established
+ * before allowing tracked-file edits — far more robust than parsing the
+ * branch name shape (which legitimately varies: `dev-4083-slug`,
+ * `fe-630-slug`, `emw-280-slug`), and it stays fast + offline (a local
+ * git config read, no API call).
+ *
+ * Best-effort by design: a failure to write the marker must never abort the
+ * issue-creation flow that triggered it. Callers in a known-good repo
+ * context wrap this and warn on failure; the standalone `mark-branch`
+ * command does its own repo/branch validation first so it can surface a
+ * clear error instead.
+ *
+ * No `--` ref-terminator (unlike the checkout/rename calls above): `git
+ * config <key> <value>` takes exactly two positional operands, the key is
+ * always our `branch.`-prefixed literal, and a value beginning with `-` is
+ * stored verbatim rather than parsed as a flag — so there's no
+ * flag-injection surface to defend here.
+ */
+export function setBranchLinearIssue(branch, identifier) {
+    execFileSync("git", ["config", `branch.${branch}.linearIssue`, identifier], {
+        stdio: "pipe",
+    });
+}
+/**
+ * Read back the `branch.<branch>.linearIssue` marker, or null when unset.
+ */
+export function getBranchLinearIssue(branch) {
+    try {
+        return execFileSync("git", ["config", "--get", `branch.${branch}.linearIssue`], { stdio: "pipe" })
+            .toString()
+            .trim();
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Current branch's short name, or null when detached / not in a repo.
+ *
+ * Uses `symbolic-ref` rather than `rev-parse --abbrev-ref`: the former
+ * resolves the name even on an unborn branch (fresh repo, no commits yet)
+ * and still fails — yielding null — on a detached HEAD, which is exactly
+ * the "no named branch" signal callers want.
+ */
+export function currentGitBranch() {
+    try {
+        return execFileSync("git", ["symbolic-ref", "--short", "HEAD"], {
+            stdio: "pipe",
+        })
+            .toString()
+            .trim();
+    }
+    catch {
+        return null;
+    }
 }

package/dist/commands/issues.js

@@ -17,7 +17,7 @@ import { handleAsyncCommand, outputSuccess, outputWarning, warnIfTruncated, } fr
 import { getRootOpts } from "../utils/root-opts.js";
 import { formatCsv, formatMarkdown, formatTable, } from "../utils/table-formatter.js";
 import { parsePositiveInt, parsePriorityFilter, splitList, validatePriority, } from "../utils/validators.js";
-import { gitCheckoutBranch, toBranchName } from "./issues/branch.js";
+import { currentGitBranch, extractIssueIdentifierFromBranch, getBranchLinearIssue, gitCheckoutBranch, setBranchLinearIssue, toBranchName, } from "./issues/branch.js";
 import { maybeAutoLink, prepareAutoLinkedDescription, readDescriptionFile, resolveDescription, } from "./issues/description.js";
 import { handleLinkReferencesIssue } from "./issues/link-references.js";
 import { buildIncomingRelationEntries, buildOutgoingRelationEntries, createRelations, } from "./issues/relations.js";
@@ -292,6 +292,10 @@ async function resolveCreateInputs(title, options, rootOpts) {
             title,
             assignee: effectiveAssignee,
             project: options.project,
+            // DEV-4084: scope the accepted type-label set to the team so the
+            // DEV team's `research` label validates without `--skip-validation`.
+            // Falls back to the workspace default when no team is provided.
+            team: options.team || config.defaultTeam || undefined,
         });
         // Apply normalized labels back so resolution uses the canonical names
         if (validationResult.normalizedLabels) {
@@ -468,8 +472,25 @@ async function handleCreateIssue(title, options, command) {
     }
     let branch;
     if (options.checkout && result.branchName) {
-        branch = toBranchName(result.branchName);
-        gitCheckoutBranch(branch);
+        const branchName = toBranchName(result.branchName);
+        // Only treat the branch as created (and surface it in the output) when
+        // the checkout actually happened — outside a git repo gitCheckoutBranch
+        // warns and skips, and claiming a branch / a missing marker afterward
+        // would be a contradictory second warning (DEV-4293 cycle-1).
+        if (gitCheckoutBranch(branchName)) {
+            branch = branchName;
+            // Record the issue→branch link as git metadata (DEV-4293) so the
+            // DEV-4241 hook can confirm a workflow was established without parsing
+            // the branch name. Best-effort: never let a marker-write failure abort
+            // a successful issue creation.
+            try {
+                setBranchLinearIssue(branch, result.identifier);
+            }
+            catch {
+                outputWarning(`Created branch ${branch} but could not record its Linear issue marker. ` +
+                    `Run 'el-linear issues mark-branch ${result.identifier}' from the branch to set it.`);
+            }
+        }
     }
     const output = {
         ...result,
@@ -790,6 +811,14 @@ async function handleRetrolink(options, command) {
         execFileSync("git", ["branch", "-m", "--", oldBranch, newBranch], {
             stdio: "pipe",
         });
+        // Record the issue→branch link (DEV-4293), same as `create --checkout`.
+        try {
+            setBranchLinearIssue(newBranch, result.identifier);
+        }
+        catch {
+            outputWarning(`Renamed branch to ${newBranch} but could not record its Linear issue marker. ` +
+                `Run 'el-linear issues mark-branch ${result.identifier}' from the branch to set it.`);
+        }
     }
     outputSuccess({
         ...result,
@@ -797,6 +826,43 @@ async function handleRetrolink(options, command) {
         ...(newBranch ? { branch: newBranch } : {}),
     });
 }
+async function handleMarkBranch(issueId, _options, _command) {
+    const branch = currentGitBranch();
+    if (!branch) {
+        throw new Error("Not on a named git branch (detached HEAD or not in a repository).");
+    }
+    if (branch === "main" || branch === "master") {
+        throw new Error(`Refusing to mark the '${branch}' branch.`);
+    }
+    // Resolve the identifier to record. An explicit arg wins; otherwise infer
+    // it from the branch name. Both paths are offline — the marker's whole
+    // value is letting the hook verify a workflow without a network call, so
+    // we don't round-trip to the API just to normalize an identifier.
+    let identifier;
+    if (issueId) {
+        // Accepts a bare identifier (DEV-123), a branch-style token
+        // (dev-123-slug), or a Linear URL — extract normalizes all three.
+        identifier = extractIssueIdentifierFromBranch(issueId);
+        if (!identifier) {
+            throw new Error(`'${issueId}' is not a Linear issue identifier (expected a shape like DEV-123).`);
+        }
+    }
+    else {
+        identifier = extractIssueIdentifierFromBranch(branch);
+        if (!identifier) {
+            throw new Error(`Branch '${branch}' has no Linear identifier to infer. ` +
+                `Pass one explicitly: 'el-linear issues mark-branch DEV-123'.`);
+        }
+    }
+    const previous = getBranchLinearIssue(branch);
+    setBranchLinearIssue(branch, identifier);
+    outputSuccess({
+        branch,
+        linearIssue: identifier,
+        ...(previous && previous !== identifier ? { previous } : {}),
+        marked: true,
+    });
+}
 export function setupIssuesCommands(program) {
     const issues = program
         .command("issues")
@@ -997,4 +1063,11 @@ export function setupIssuesCommands(program) {
         .option("--title <title>", "override auto-generated title (default: first commit message)")
         .option("--base <branch>", "base branch for log comparison", "main")
         .action(handleAsyncCommand(handleRetrolink));
+    issues
+        .command("mark-branch [issueId]")
+        .description("Record the current branch's Linear issue as git metadata (branch.<branch>.linearIssue).")
+        .addHelpText("after", "\nManual recovery for branches not created via 'issues create --checkout' / 'retrolink'.\n" +
+        "With no argument, infers the identifier from the branch name (e.g. dev-4293-slug -> DEV-4293).\n" +
+        "Accepts a bare identifier (DEV-123), a branch-style token, or a Linear URL.")
+        .action(handleAsyncCommand(handleMarkBranch));
 }

package/dist/config/config.d.ts

@@ -47,6 +47,14 @@ export interface ElLinearConfig {
     validation?: {
         enabled: boolean;
         typeLabels?: string[];
+        /**
+         * Per-team overrides of the canonical type-label set. Keys are Linear
+         * team keys (uppercase, e.g. `DEV`). When set, an `issues create
+         * --team X` call validates labels against the team-scoped set rather
+         * than the workspace default — see `issue-validation.ts` for the
+         * built-in overrides (DEV-4084).
+         */
+        teamTypeLabels?: Record<string, string[]>;
     };
     /**
      * Optional override for the Linear workspace URL key (the part after

package/dist/config/error-enrichment.js

@@ -232,8 +232,13 @@ export async function enrichValidationErrors(result, options, services) {
     const projects = teamData.projects?.nodes ?? [];
     const members = teamData.members?.nodes ?? [];
     const labels = teamData.labels?.nodes ?? [];
-    const typeLabels = getCanonicalTypeLabels();
-    const inferred = options.title ? inferTypeFromTitle(options.title) : null;
+    // DEV-4084: scope the suggested type-label set to the team when one is
+    // known so the retry hint surfaces (e.g.) `research` instead of `spike`
+    // on the Dev team.
+    const typeLabels = getCanonicalTypeLabels(options.team);
+    const inferred = options.title
+        ? inferTypeFromTitle(options.title, options.team)
+        : null;
     for (let i = 0; i < result.errors.length; i++) {
         result.errors[i] = decorateError(result.errors[i], classifications[i], {
             projects,

package/dist/config/issue-validation.d.ts

@@ -13,6 +13,14 @@
  *
  * Exported so error-enrichment can reuse the same mapping when inferring a
  * type label from a title's first word.
+ *
+ * **Ambiguous-verb resolution.** When a verb belongs to multiple type sets
+ * (e.g. `Research` appears under both `spike` and `research`), the first
+ * declared type wins — `Object.entries` preserves insertion order, and
+ * `inferTypeFromTitle` filters by the team's accepted set before iterating.
+ * In practice no team accepts both `spike` and `research` (the synonyms),
+ * so the first-declared-wins rule never bites; if a future team accepts
+ * both, list the preferred one earlier in this map.
  */
 export declare const TYPE_VERB_MAP: Record<string, string[]>;
 export interface ValidationResult {
@@ -27,12 +35,23 @@ export interface ValidationInput {
     title: string;
     assignee: string | undefined;
     project: string | undefined;
+    /**
+     * Team key (e.g. `DEV`) the issue is being created on. When set, the
+     * validator consults the team-scoped `typeLabels` override (DEV-4084) so
+     * a team whose taxonomy doesn't include the workspace default (`spike`)
+     * can validate its own equivalent (`research`) without `--skip-validation`.
+     *
+     * `team` is otherwise advisory: it does not affect description/title/
+     * assignee/project requirements.
+     */
+    team?: string;
 }
 /**
- * Public accessor for the canonical type labels.
- * Used by error-enrichment when suggesting labels.
+ * Public accessor for the canonical type labels. Pass the team key to get
+ * the team-scoped set (DEV-4084); omit for the workspace default. Used by
+ * error-enrichment when suggesting labels.
  */
-export declare function getCanonicalTypeLabels(): string[];
+export declare function getCanonicalTypeLabels(team?: string): string[];
 /**
  * Find the canonical type label for a title's first word, if it matches a
  * known verb in TYPE_VERB_MAP. Returns the matched verb and inferred type,
@@ -53,7 +72,7 @@ export declare function getCanonicalTypeLabels(): string[];
  * conflate "warn about mismatch" with "suggest a default" and produce
  * subtle bugs (e.g. inferring a type the alignment check just rejected).
  */
-export declare function inferTypeFromTitle(title: string): {
+export declare function inferTypeFromTitle(title: string, team?: string): {
     verb: string;
     type: string;
 } | null;

package/dist/config/issue-validation.js

@@ -11,12 +11,54 @@ import { outputWarning } from "../utils/output.js";
 import { loadConfig } from "./config.js";
 /** Canonical type labels. Stored in config so they can be updated without code changes. */
 const DEFAULT_TYPE_LABELS = ["bug", "feature", "refactor", "chore", "spike"];
+/**
+ * Built-in per-team overrides for the canonical type-label set. Teams whose
+ * taxonomy diverges from the workspace default ship here so the CLI accepts
+ * their labels out of the box without forcing every operator to maintain a
+ * personal config override.
+ *
+ * DEV-4084: the Dev team uses `research` instead of `spike` (and has no
+ * `spike` label) — the DEV-3768 fix removed the silent `research → spike`
+ * alias correctly, but left the validator's accepted set workspace-wide,
+ * so DEV creators were forced into `--skip-validation` (which also drops
+ * title-verb, label-count, and description checks).
+ *
+ * This widens the accepted set for DEV (no rewrite — DEV-3768's no-silent-
+ * alias guarantee is preserved) so `--labels "research,tools"` validates
+ * cleanly on DEV while every other team keeps `spike`.
+ */
+const TEAM_TYPE_LABELS = {
+    DEV: ["bug", "feature", "refactor", "chore", "research"],
+};
+/**
+ * Verbs that indicate a `spike`-equivalent type. Shared between `spike` and
+ * its team-local synonym `research` so adding a new investigation verb only
+ * has to land in one place — without this constant the two arrays drift the
+ * next time someone adds e.g. `Probe`.
+ */
+const SPIKE_VERBS = [
+    "Research",
+    "Investigate",
+    "Explore",
+    "Evaluate",
+    "Audit",
+    "Benchmark",
+    "Test",
+];
 /**
  * Recommended leading verbs for each type label.
  * Title verb and type label should express the same intent.
  *
  * Exported so error-enrichment can reuse the same mapping when inferring a
  * type label from a title's first word.
+ *
+ * **Ambiguous-verb resolution.** When a verb belongs to multiple type sets
+ * (e.g. `Research` appears under both `spike` and `research`), the first
+ * declared type wins — `Object.entries` preserves insertion order, and
+ * `inferTypeFromTitle` filters by the team's accepted set before iterating.
+ * In practice no team accepts both `spike` and `research` (the synonyms),
+ * so the first-declared-wins rule never bites; if a future team accepts
+ * both, list the preferred one earlier in this map.
  */
 export const TYPE_VERB_MAP = {
     bug: ["Fix", "Resolve", "Patch", "Handle", "Address", "Correct"],
@@ -56,15 +98,13 @@ export const TYPE_VERB_MAP = {
         "Teardown",
         "Upgrade",
     ],
-    spike: [
-        "Research",
-        "Investigate",
-        "Explore",
-        "Evaluate",
-        "Audit",
-        "Benchmark",
-        "Test",
-    ],
+    spike: SPIKE_VERBS,
+    // Team-local synonym for `spike`. Active when the validator is scoped to
+    // a team whose `typeLabels` includes `research` (see `TEAM_TYPE_LABELS` /
+    // `validation.teamTypeLabels`). Shares `SPIKE_VERBS` so the two stay in
+    // lockstep — drift would silently produce different inferences depending
+    // on which team you're on.
+    research: SPIKE_VERBS,
     refactor: [
         "Refactor",
         "Restructure",
@@ -91,17 +131,50 @@ const LABEL_ALIASES = {
 function getValidationConfig() {
     const config = loadConfig();
     const validation = config.validation;
+    // User-supplied `teamTypeLabels` are layered on top of the built-in
+    // `TEAM_TYPE_LABELS` so an operator can add a new team's override
+    // without having to re-declare DEV's. A user override for an existing
+    // team key replaces the built-in entry for that key.
+    //
+    // Normalize user-config keys to uppercase before merging — Linear team
+    // keys are uppercase canonical, but an operator who writes
+    // `{ "dev": [...] }` (lowercase) should still hit DEV's override. Doing
+    // it here means `resolveTypeLabels` can rely on a uniformly uppercased
+    // map without re-walking on every lookup.
+    const userOverrides = {};
+    for (const [key, value] of Object.entries(validation?.teamTypeLabels ?? {})) {
+        userOverrides[key.toUpperCase()] = value;
+    }
+    const teamTypeLabels = {
+        ...TEAM_TYPE_LABELS,
+        ...userOverrides,
+    };
     return {
         enabled: validation?.enabled ?? true,
         typeLabels: validation?.typeLabels ?? DEFAULT_TYPE_LABELS,
+        teamTypeLabels,
     };
 }
 /**
- * Public accessor for the canonical type labels.
- * Used by error-enrichment when suggesting labels.
+ * Resolve the canonical type-label set for a team. DEV-4084: when the team
+ * has a per-team override (built-in or config-declared) that set is returned;
+ * otherwise the workspace default. The team key is normalized to uppercase
+ * because Linear team keys are case-insensitive but stored uppercase.
+ */
+function resolveTypeLabels(team) {
+    const cfg = getValidationConfig();
+    if (!team)
+        return cfg.typeLabels;
+    const teamKey = team.toUpperCase();
+    return cfg.teamTypeLabels[teamKey] ?? cfg.typeLabels;
+}
+/**
+ * Public accessor for the canonical type labels. Pass the team key to get
+ * the team-scoped set (DEV-4084); omit for the workspace default. Used by
+ * error-enrichment when suggesting labels.
  */
-export function getCanonicalTypeLabels() {
-    return getValidationConfig().typeLabels;
+export function getCanonicalTypeLabels(team) {
+    return resolveTypeLabels(team);
 }
 /**
  * Find the canonical type label for a title's first word, if it matches a
@@ -123,10 +196,18 @@ export function getCanonicalTypeLabels() {
  * conflate "warn about mismatch" with "suggest a default" and produce
  * subtle bugs (e.g. inferring a type the alignment check just rejected).
  */
-export function inferTypeFromTitle(title) {
+export function inferTypeFromTitle(title, team) {
     const lowered = title.toLowerCase();
+    // DEV-4084: when scoping to a team, only suggest a type that the team
+    // actually accepts. This makes "Research GraphQL caching options" on a
+    // DEV team infer `research` instead of `spike` (which DEV doesn't have)
+    // without disrupting other teams whose taxonomy still uses `spike`.
+    const allowedTypes = new Set(resolveTypeLabels(team));
+    const isAllowed = (type) => allowedTypes.has(type);
     // Multi-word verbs first ("Set up")
     for (const [type, verbs] of Object.entries(TYPE_VERB_MAP)) {
+        if (!isAllowed(type))
+            continue;
         for (const verb of verbs) {
             if (!verb.includes(" ")) {
                 continue;
@@ -144,6 +225,8 @@ export function inferTypeFromTitle(title) {
     }
     const firstLower = firstWord.toLowerCase();
     for (const [type, verbs] of Object.entries(TYPE_VERB_MAP)) {
+        if (!isAllowed(type))
+            continue;
         for (const verb of verbs) {
             if (verb.includes(" ")) {
                 continue;
@@ -182,6 +265,10 @@ export function validateIssueCreation(input) {
     if (!vConfig.enabled) {
         return result;
     }
+    // DEV-4084: scope the accepted type-label set to the team when one was
+    // passed. Falls back to the workspace default when no team is supplied
+    // or no override exists.
+    const typeLabels = resolveTypeLabels(input.team);
     // --- Label normalization (always runs when validation is on) ---
     if (input.labels && input.labels.length > 0) {
         result.normalizedLabels = input.labels.map((label) => {
@@ -196,21 +283,21 @@ export function validateIssueCreation(input) {
     // --- Required: labels must be provided ---
     if (effectiveLabels.length === 0) {
         result.errors.push("Missing --labels. At least one label is required, including a type label.\n" +
-            `  Valid type labels: ${vConfig.typeLabels.join(", ")}\n` +
+            `  Valid type labels: ${typeLabels.join(", ")}\n` +
             '  Example: --labels "bug,backend"');
     }
     else {
         // --- Required: exactly one type label ---
-        const typeLabelsFound = effectiveLabels.filter((l) => vConfig.typeLabels.includes(l.toLowerCase()));
+        const typeLabelsFound = effectiveLabels.filter((l) => typeLabels.includes(l.toLowerCase()));
         if (typeLabelsFound.length === 0) {
             result.errors.push("Missing type label. Exactly one required.\n" +
-                `  Valid type labels: ${vConfig.typeLabels.join(", ")}\n` +
+                `  Valid type labels: ${typeLabels.join(", ")}\n` +
                 `  Provided labels: ${effectiveLabels.join(", ")}\n` +
-                `  Example: --labels "${vConfig.typeLabels[0]},${effectiveLabels[0]}"`);
+                `  Example: --labels "${typeLabels[0]},${effectiveLabels[0]}"`);
         }
         else if (typeLabelsFound.length > 1) {
             result.errors.push(`Multiple type labels found: ${typeLabelsFound.join(", ")}. Exactly one required.\n` +
-                `  Valid type labels: ${vConfig.typeLabels.join(", ")}`);
+                `  Valid type labels: ${typeLabels.join(", ")}`);
         }
     }
     // --- Required: description must be provided ---
@@ -242,7 +329,7 @@ export function validateIssueCreation(input) {
         result.warnings.push("Consider starting the title with an action verb instead of an article.");
     }
     // --- Warning: title-verb / type-label alignment ---
-    const typeLabelsFound = effectiveLabels.filter((l) => vConfig.typeLabels.includes(l.toLowerCase()));
+    const typeLabelsFound = effectiveLabels.filter((l) => typeLabels.includes(l.toLowerCase()));
     if (typeLabelsFound.length === 1) {
         checkTitleVerbAlignment(input.title, typeLabelsFound[0].toLowerCase(), result);
     }

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

@@ -52,4 +52,9 @@ export interface UpdateCommentResponse {
         comment: UpdatedCommentResourceNode | null;
     };
 }
+export interface DeleteCommentResponse {
+    commentDelete: {
+        success: boolean;
+    };
+}
 export {};

package/dist/queries/comments.d.ts

@@ -1,3 +1,4 @@
 export declare const LIST_COMMENTS_QUERY = "\n  query ListComments($issueId: String!, $first: Int) {\n    issue(id: $issueId) {\n      id\n      identifier\n      comments(first: $first, orderBy: createdAt) {\n        nodes {\n          id\n          body\n          createdAt\n          updatedAt\n          user {\n            id\n            name\n            displayName\n            url\n          }\n        }\n      }\n    }\n  }\n";
 export declare const CREATE_COMMENT_MUTATION = "\n  mutation CreateComment($input: CommentCreateInput!) {\n    commentCreate(input: $input) {\n      success\n      comment {\n        id\n        body\n        createdAt\n        updatedAt\n        user {\n          id\n          name\n          displayName\n          url\n        }\n      }\n    }\n  }\n";
 export declare const UPDATE_COMMENT_MUTATION = "\n  mutation UpdateComment($id: String!, $input: CommentUpdateInput!) {\n    commentUpdate(id: $id, input: $input) {\n      success\n      comment {\n        id\n        body\n        createdAt\n        updatedAt\n        user {\n          id\n          name\n          displayName\n          url\n        }\n        issue {\n          id\n          identifier\n        }\n      }\n    }\n  }\n";
+export declare const DELETE_COMMENT_MUTATION = "\n  mutation DeleteComment($id: String!) {\n    commentDelete(id: $id) {\n      success\n    }\n  }\n";

package/dist/queries/comments.js

@@ -62,3 +62,16 @@ export const UPDATE_COMMENT_MUTATION = `
     }
   }
 `;
+// commentDelete returns a DeletePayload (`{ success }`) — no `comment` node,
+// since the entity is gone. The @linear/sdk exposes this as
+// `client.deleteComment(id)`, but the standalone comment commands all go
+// through raw mutations on `graphQLService` (create/update need `bodyData`,
+// which the SDK's typed input wraps awkwardly), so delete stays on the same
+// raw path for a consistent, single-mock test surface.
+export const DELETE_COMMENT_MUTATION = `
+  mutation DeleteComment($id: String!) {
+    commentDelete(id: $id) {
+      success
+    }
+  }
+`;

package/dist/queries/issues.d.ts

@@ -22,7 +22,7 @@ export declare const GET_ISSUE_BY_IDENTIFIER_QUERY = "\n  query GetIssueByIdenti
  * by `id` (`projectsById`) so its milestones are still fetched for
  * `--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: 1\n    ) @include(if: $hasProjectName) {\n      nodes {\n        id\n        name\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 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  }\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  }\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";
@@ -46,7 +46,7 @@ export declare const DELETE_ISSUE_MUTATION = "\n  mutation DeleteIssue($id: Stri
  * so they carry distinct aliases and the service folds whichever ran
  * into `resolveResult.projects`.
  */
-export declare const BATCH_RESOLVE_FOR_CREATE_QUERY = "\n  query BatchResolveForCreate(\n    $teamKey: String\n    $teamName: String\n    $projectName: String\n    $projectId: ID\n    $hasProjectName: Boolean = false\n    $hasProjectId: Boolean = false\n    $parentTeamKey: String\n    $parentIssueNumber: Float\n    $milestoneName: String\n    $hasMilestoneName: Boolean = false\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    projectsByName: projects(\n      filter: { name: { eqIgnoreCase: $projectName } }\n      first: 1\n    ) @include(if: $hasProjectName) {\n      nodes {\n        id\n        name\n        teams {\n          nodes { id key }\n        }\n        projectMilestones {\n          nodes { id name }\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        teams {\n          nodes { id key }\n        }\n        projectMilestones {\n          nodes { id name }\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    parentIssues: issues(\n      filter: {\n        and: [\n          { team: { key: { eq: $parentTeamKey } } }\n          { number: { eq: $parentIssueNumber } }\n        ]\n      }\n      first: 1\n    ) {\n      nodes {\n        id\n        identifier\n      }\n    }\n  }\n";
+export declare const BATCH_RESOLVE_FOR_CREATE_QUERY = "\n  query BatchResolveForCreate(\n    $teamKey: String\n    $teamName: String\n    $projectName: String\n    $projectId: ID\n    $hasProjectName: Boolean = false\n    $hasProjectId: Boolean = false\n    $parentTeamKey: String\n    $parentIssueNumber: Float\n    $milestoneName: String\n    $hasMilestoneName: Boolean = false\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    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 { id name }\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        teams {\n          nodes { id key }\n        }\n        projectMilestones {\n          nodes { id name }\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    parentIssues: issues(\n      filter: {\n        and: [\n          { team: { key: { eq: $parentTeamKey } } }\n          { number: { eq: $parentIssueNumber } }\n        ]\n      }\n      first: 1\n    ) {\n      nodes {\n        id\n        identifier\n      }\n    }\n  }\n";
 /**
  * Build a label-resolution query filtered by names (case-insensitive).
  * Uses `or` + `eqIgnoreCase` since Linear's `in` filter may be case-sensitive.

package/dist/queries/issues.js

@@ -146,11 +146,14 @@ export const BATCH_RESOLVE_FOR_UPDATE_QUERY = `
   ) {
     projectsByName: projects(
       filter: { name: { eqIgnoreCase: $projectName } }
-      first: 1
+      first: 5
     ) @include(if: $hasProjectName) {
       nodes {
         id
         name
+        teams {
+          nodes { id key }
+        }
         projectMilestones {
           nodes {
             id
@@ -313,7 +316,7 @@ export const BATCH_RESOLVE_FOR_CREATE_QUERY = `
 
     projectsByName: projects(
       filter: { name: { eqIgnoreCase: $projectName } }
-      first: 1
+      first: 5
     ) @include(if: $hasProjectName) {
       nodes {
         id

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

@@ -175,6 +175,19 @@ export declare class GraphQLIssuesService {
     private executeCreateMutation;
     searchIssues(args: SearchIssueArgs): Promise<LinearIssue[]>;
     private resolveTeamId;
+    /**
+     * Pick a project ID from the batched name-lookup result.
+     *
+     * The batch query fetches up to 5 candidates by name (DEV-4103) so that
+     * a name shared across teams doesn't silently bind to whichever project
+     * Linear returned first. When a `--team` was supplied, prefer the
+     * candidate whose team set includes it; the downstream
+     * `validateProjectTeam` will then no-op (the team already matches).
+     * When multiple candidates exist and none of them are on the requested
+     * team (or no team was supplied), throw an explicit ambiguous-project
+     * error listing the candidate teams — far better than the prior silent
+     * cross-team match.
+     */
     private resolveProjectId;
     /**
      * Check that the resolved team is associated with the project.

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

@@ -3,7 +3,7 @@ import { ARCHIVE_ISSUE_MUTATION, BATCH_RESOLVE_FOR_CREATE_QUERY, BATCH_RESOLVE_F
 import { CREATE_LABEL_MUTATION } from "../queries/labels.js";
 import { toISOStringOrNow } from "./date-format.js";
 import { extractEmbeds } from "./embed-parser.js";
-import { notFoundError } from "./error-messages.js";
+import { multipleMatchesError, notFoundError } from "./error-messages.js";
 import { parseIssueIdentifier, tryParseIssueIdentifier, } from "./identifier-parser.js";
 import { logger } from "./logger.js";
 import { isUuid } from "./uuid.js";
@@ -111,8 +111,15 @@ export class GraphQLIssuesService {
             teamIdForLabels = await this.fetchIssueTeamId(resolvedIssueId);
         }
         const finalLabelIds = await this.resolveLabelsWithMode(normalizedArgs.labelIds, resolveResult, labelMode, currentIssueLabels, teamIdForLabels, normalizedArgs.teamId);
+        // DEV-4103: scope project disambiguation by the issue's existing team
+        // so a `--project` name shared across teams binds to the issue's team
+        // rather than whichever project Linear happened to return first.
+        // `issueTeamId` is the right scope here — it's always a UUID and
+        // represents the team the issue currently lives on. `--team` is rare
+        // on update (and would imply a cross-team move that goes through
+        // separate validation paths anyway).
         const finalProjectId = normalizedArgs.projectId
-            ? this.resolveProjectId(normalizedArgs.projectId, resolveResult)
+            ? this.resolveProjectId(normalizedArgs.projectId, resolveResult, issueTeamId)
             : undefined;
         const { projectMilestoneNodes, issueProjectMilestoneNodes } = this.extractMilestoneNodes(normalizedArgs, resolveResult);
         const finalMilestoneId = this.resolveMilestoneId(normalizedArgs.milestoneId, resolveResult, projectMilestoneNodes, issueProjectMilestoneNodes);
@@ -272,7 +279,7 @@ export class GraphQLIssuesService {
             ? await this.resolveTeamId(args.teamId, resolveResult)
             : undefined;
         const projectId = args.projectId
-            ? this.resolveProjectId(args.projectId, resolveResult)
+            ? this.resolveProjectId(args.projectId, resolveResult, teamId)
             : undefined;
         // Validate team-project compatibility and auto-correct when possible
         if (projectId && teamId && args.projectId) {
@@ -352,7 +359,7 @@ export class GraphQLIssuesService {
         const finalProjectId = projectIdArg
             ? this.resolveProjectId(projectIdArg, resolveResult)
             : undefined;
-        const finalAssigneeId = this.resolveAssigneeId(args.assigneeId, resolveResult);
+        const finalAssigneeId = await this.resolveAssigneeId(args.assigneeId, resolveResult);
         const finalDelegateId = await this.resolveDelegateId(args.delegateId, resolveResult);
         // Map the public discriminant back to the internal filter shape:
         // `{ kind: "id", id }` → `{ kind: "id", id: <resolvedUuid> }`
@@ -423,7 +430,20 @@ export class GraphQLIssuesService {
         // Exact GraphQL match failed — fall back to prefix matching via LinearService
         return this.linearService.resolveTeamId(teamId);
     }
-    resolveProjectId(projectId, resolveResult) {
+    /**
+     * Pick a project ID from the batched name-lookup result.
+     *
+     * The batch query fetches up to 5 candidates by name (DEV-4103) so that
+     * a name shared across teams doesn't silently bind to whichever project
+     * Linear returned first. When a `--team` was supplied, prefer the
+     * candidate whose team set includes it; the downstream
+     * `validateProjectTeam` will then no-op (the team already matches).
+     * When multiple candidates exist and none of them are on the requested
+     * team (or no team was supplied), throw an explicit ambiguous-project
+     * error listing the candidate teams — far better than the prior silent
+     * cross-team match.
+     */
+    resolveProjectId(projectId, resolveResult, teamId) {
         if (isUuid(projectId)) {
             // The create/update batch queries fetch a `projectsById` block for a
             // UUID `--project` (folded into `resolveResult.projects`). An empty
@@ -443,7 +463,25 @@ export class GraphQLIssuesService {
         if (!projectNodes?.length) {
             throw notFoundError("Project", projectId);
         }
-        return projectNodes[0].id;
+        if (projectNodes.length === 1) {
+            return projectNodes[0].id;
+        }
+        // Multiple matches — disambiguate by team when possible.
+        if (teamId) {
+            const teamMatches = projectNodes.filter((n) => n.teams?.nodes.some((t) => t.id === teamId));
+            if (teamMatches.length === 1) {
+                return teamMatches[0].id;
+            }
+            if (teamMatches.length > 1) {
+                // Same name, same team — extremely rare but Linear permits it.
+                // Fall through to ambiguity error so the user picks by URL/slug.
+            }
+        }
+        const descriptions = projectNodes.map((n) => {
+            const teamKeys = n.teams?.nodes.map((t) => t.key) ?? [];
+            return `${n.id} (teams: ${teamKeys.join(", ") || "none"})`;
+        });
+        throw multipleMatchesError("project", projectId, descriptions, "scope with --team, or pass the project URL/slug-id");
     }
     /**
      * Check that the resolved team is associated with the project.
@@ -839,10 +877,20 @@ export class GraphQLIssuesService {
         }
         return filter;
     }
-    resolveAssigneeId(assigneeId, resolveResult) {
-        if (!assigneeId || isUuid(assigneeId) || !assigneeId.includes("@")) {
+    async resolveAssigneeId(assigneeId, resolveResult) {
+        if (!assigneeId || isUuid(assigneeId)) {
             return assigneeId;
         }
+        // A plain name (no `@`) resolves via the user lookup — same as
+        // `resolveDelegateId`. Without this, a non-config full name like
+        // "Yury Tsukerman" fell through unchanged and was sent to the
+        // GraphQL filter as a bogus UUID, producing an opaque "Argument
+        // Validation Error" instead of resolving (or a clean not-found).
+        // `resolveUserId` matches displayName then name and throws a
+        // structured notFound / multiple-matches error (DEV-4312).
+        if (!assigneeId.includes("@")) {
+            return this.linearService.resolveUserId(assigneeId);
+        }
         const userNodes = resolveResult.users?.nodes;
         if (!userNodes?.length) {
             throw notFoundError("User", assigneeId);

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

@@ -35,7 +35,21 @@ export declare class LinearService {
     getCycles(teamFilter?: string, activeOnly?: boolean, limit?: number): Promise<LinearCycleSummary[]>;
     getCycleById(cycleId: string, issuesLimit?: number): Promise<LinearCycleDetail>;
     resolveCycleId(cycleNameOrId: string, teamFilter?: string): Promise<string>;
-    resolveProjectId(projectInput: string): Promise<string>;
+    /**
+     * Resolve a user-supplied project identifier to a UUID.
+     *
+     * Inputs (in order): UUID (pass-through), Linear URL or slug-id pair
+     * (unique by slug, resolved via `slugId` filter), or a plain name (case
+     * insensitive). DEV-4103: when a name resolution returns multiple matches
+     * across teams, the resolver disambiguates by `--team` when provided and
+     * throws an `ambiguous project` error otherwise — replacing the prior
+     * silent `first: 1` pick that could cross team boundaries.
+     *
+     * `teamInput` is the same string a user would pass to `--team`
+     * (key / name / UUID); it is resolved here when present so callers don't
+     * have to double-resolve.
+     */
+    resolveProjectId(projectInput: string, teamInput?: string): Promise<string>;
     /**
      * Normalize a user-supplied project input to a UUID when the input is
      * a URL or slug-id form. Pass-through for UUIDs and plain names — the

package/dist/utils/linear-service.js

@@ -471,7 +471,21 @@ export class LinearService {
         }
         return chosen.id;
     }
-    async resolveProjectId(projectInput) {
+    /**
+     * Resolve a user-supplied project identifier to a UUID.
+     *
+     * Inputs (in order): UUID (pass-through), Linear URL or slug-id pair
+     * (unique by slug, resolved via `slugId` filter), or a plain name (case
+     * insensitive). DEV-4103: when a name resolution returns multiple matches
+     * across teams, the resolver disambiguates by `--team` when provided and
+     * throws an `ambiguous project` error otherwise — replacing the prior
+     * silent `first: 1` pick that could cross team boundaries.
+     *
+     * `teamInput` is the same string a user would pass to `--team`
+     * (key / name / UUID); it is resolved here when present so callers don't
+     * have to double-resolve.
+     */
+    async resolveProjectId(projectInput, teamInput) {
         if (isUuid(projectInput)) {
             return projectInput;
         }
@@ -501,15 +515,46 @@ export class LinearService {
             // not-found error as the name path.
             throw notFoundError("Project", projectInput);
         }
-        const filter = { name: { eqIgnoreCase: projectInput } };
+        // DEV-4103: scope by team when provided so a name shared across teams
+        // doesn't resolve to a different team's project. Same SDK filter shape
+        // `getProjects` already uses for `--team` filtering.
+        const teamId = teamInput ? await this.resolveTeamId(teamInput) : undefined;
+        const filter = {
+            name: { eqIgnoreCase: projectInput },
+        };
+        if (teamId) {
+            // Matches the filter shape `getProjects` uses for `--team`.
+            filter.teams = { some: { id: { eq: teamId } } };
+        }
+        // `first: 5` is wide enough to detect ambiguity (same name across
+        // multiple teams) without paying for a deeper page. Linear's UI caps
+        // effective project-name collisions at a handful in practice; if a
+        // workspace ever exceeds this we'll see it as a still-ambiguous error
+        // listing the first 5 teams — better than a silent wrong pick.
         const projectsConnection = await this.client.projects({
             filter,
-            first: 1,
+            first: 5,
         });
         if (projectsConnection.nodes.length === 0) {
-            throw notFoundError("Project", projectInput);
+            const context = teamInput ? `on team "${teamInput}"` : undefined;
+            throw notFoundError("Project", projectInput, context);
+        }
+        if (projectsConnection.nodes.length === 1) {
+            return projectsConnection.nodes[0].id;
         }
-        return projectsConnection.nodes[0].id;
+        // Multiple candidates — collect team keys per candidate so the error
+        // names them concretely. Bounded N ≤ 5 keeps the per-edge resolver
+        // promise cheap (handful of round-trips on the rare ambiguous path).
+        const candidates = await Promise.all(projectsConnection.nodes.map(async (p) => {
+            const teams = await p.teams();
+            return {
+                id: p.id,
+                name: p.name,
+                teamKeys: teams.nodes.map((t) => t.key),
+            };
+        }));
+        const descriptions = candidates.map((c) => `${c.id} (teams: ${c.teamKeys.join(", ") || "none"})`);
+        throw multipleMatchesError("project", projectInput, descriptions, "scope with --team, or pass the project URL/slug-id");
     }
     /**
      * Normalize a user-supplied project input to a UUID when the input is

package/package.json

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