@enrichlayer/el-linear 1.45.1 → 1.46.0

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

@@ -468,6 +468,23 @@ The label is plain config — set it to anything you want, or skip it entirely.
 
 ---
 
+## Label advisor defaults and consent labels (`bot`)
+
+A workspace can configure a **label advisor** (`labelAdvisor.command` in personal config, or `EL_LINEAR_LABEL_ADVISOR`): a command `issues create` consults with the proposed issue. Whatever labels it returns are added and reported — a `labels added by advisor: … (<reason>)` warning on stderr and a `labelAdvisor` field in the JSON output. In Enrich Layer's Tools setup the advisor is `el-bot linear-rubric --advise`, the bot-suitability rubric: an issue it marks BOT gets `bot` **by default**, and an EXCLUDE issue is unchanged.
+
+- **Opt out for one create** with `--no-label-advisor` (for example, work you intend to do yourself, or an issue whose consent you are not in a position to give).
+- **Read the create output.** `labelAdvisor.added` lists what the advisor added; `labelAdvisor.consent` reports a consent label (`{labels, applied, repo, problem?}`). `applied: false` means the issue exists without that label, and `problem` says why.
+
+**Consent labels need a receipt.** Where `validation.consentReceiptGate` is on (Enrich Layer's shared config turns it on), a consent label (`validation.consentLabels`, default `bot`) is only valid with exactly one `<!-- el-intake-decision:v1 {...} -->` receipt in the description that names the issue — bot-layer intake silently skips a `bot` issue without one. So:
+
+- **Default route: let the advisor apply it.** When the advisor returns `bot` with its receipt fields, el-linear creates the issue and then, in one update, applies `bot` with a receipt naming the new issue and you (the acting Linear user) as `actor`.
+- **Never pass `--labels bot` on create.** It is refused: the receipt must name an issue that does not exist yet.
+- **Adding `bot` to an existing issue** needs the receipt in the same update, or the update is refused and the error names what is missing. Enrich Layer: run `el-bot linear-consent <ID> --automatic-implementation --reason "<why>"`, which writes the label and a valid receipt together. Elsewhere: `el-linear issues update <ID> --labels bot --description-file <body-ending-with-the-receipt>`.
+
+The gate has no override flag and ignores `--skip-validation`: it protects consent, not field hygiene.
+
+---
+
 ## User @Mentions
 
 Reference team members by name in comments. el-linear resolves both explicit `@name` tokens and bare capitalized references to proper Linear mentions.

package/dist/commands/issues.js

@@ -1,9 +1,11 @@
 import { execFileSync } from "node:child_process";
 import { loadConfig } from "../config/config.js";
+import { appendConsentReceipt, consentLabelsIn, evaluateConsentReceipt, formatConsentReceipt, formatCreateConsentRefusal, formatUpdateConsentRefusal, getConsentReceiptGateConfig, } from "../config/consent-receipt.js";
 import { enrichProjectResolverError, enrichValidationErrors, } from "../config/error-enrichment.js";
 import { evaluateGoalCompletion, formatGoalCompletionBlock, getGoalCompletionGateConfig, } from "../config/goal-completion-validation.js";
 import { evaluateIntakeDecision, formatIntakeDecisionBlock, getIntakeDecisionGateConfig, } from "../config/intake-decision-validation.js";
 import { enforceValidation, validateIssueCreation, } from "../config/issue-validation.js";
+import { runLabelAdvisor, } from "../config/label-advisor.js";
 import { maybeEmitPinMismatchHint } from "../config/pin-hint.js";
 import { resolveAssignee, resolveLabels, resolveMemberWithRegistry, resolveTeam, } from "../config/resolver.js";
 import { formatSopParentBlock, getSopLabelGateConfig, hasSopLabel, isUnresolvableReferenceError, } from "../config/sop-label-validation.js";
@@ -811,6 +813,199 @@ async function enforceIntakeDecision(description, options) {
     });
     throw new Error(`Issue creation blocked: ${message}`);
 }
+/**
+ * DEV-10372: consent-label receipt gate on create. A consent label (default
+ * `bot`) needs a receipt naming the issue, which cannot exist before the issue
+ * does, so an explicit consent label on create is refused with the two-step
+ * route. Dormant unless `validation.consentReceiptGate` is true; not bypassed
+ * by `--skip-validation`.
+ */
+function enforceCreateConsentLabels(options) {
+    const gate = getConsentReceiptGateConfig();
+    if (!gate.enabled || !options.labels) {
+        return;
+    }
+    const requested = splitList(options.labels).map((label) => labelNameForId(label) ?? label);
+    const consent = consentLabelsIn(requested, gate.labels);
+    if (consent.length > 0) {
+        throw new Error(`Issue creation blocked: ${formatCreateConsentRefusal(consent)}`);
+    }
+}
+/**
+ * DEV-10372: consult the optional label advisor and return the labels to add.
+ * Fail-closed on labels: an advisor failure warns and adds nothing. Labels the
+ * author already passed are not re-added. When the consent-receipt gate is on,
+ * an advisor-proposed consent label is dropped with a warning — the advisor
+ * cannot supply the receipt, and a create cannot carry one.
+ */
+function adviseLabels(title, options, context) {
+    if (options.labelAdvisor === false) {
+        return null;
+    }
+    const current = options.labels ? splitList(options.labels) : [];
+    const result = runLabelAdvisor({
+        team: context.teamInput || null,
+        project: typeof options.project === "string" ? options.project : null,
+        title: title ?? null,
+        description: context.description ?? null,
+        labels: current,
+        state: context.status ?? null,
+    }, loadConfig());
+    if (result === null) {
+        return null;
+    }
+    if (!result.ok) {
+        outputWarning(`label advisor failed; creating without advisor labels: ${result.error}`);
+        return null;
+    }
+    const present = new Set(current.map((label) => label.toLowerCase()));
+    let added = result.labels.filter((label) => !present.has(label.toLowerCase()));
+    const gate = getConsentReceiptGateConfig();
+    const consent = consentLabelsIn(added, gate.labels);
+    let deferred;
+    if (consent.length > 0 && (gate.enabled || result.receipt)) {
+        const held = new Set(consent.map((label) => label.toLowerCase()));
+        added = added.filter((label) => !held.has(label.toLowerCase()));
+        if (result.receipt) {
+            // DEV-10455: the advisor supplied the receipt policy fields, so the
+            // consent label is applied right after create, in one update with a
+            // receipt naming the new issue (see applyAdvisorConsent).
+            deferred = { labels: consent, receipt: result.receipt };
+        }
+        else {
+            outputWarning(`label advisor proposed ${consent.join(", ")}, not applied: a consent label needs an el-intake-decision:v1 receipt naming the issue. Apply it after creation with \`el-linear issues update <ID> --labels ${consent.join(",")}\` and the receipt in the description.`);
+        }
+    }
+    if (added.length === 0 && !deferred) {
+        return null;
+    }
+    if (added.length > 0) {
+        outputWarning(`labels added by advisor: ${added.join(", ")}${result.reason ? ` (${result.reason})` : ""}`);
+    }
+    return {
+        added,
+        reason: result.reason,
+        ...(deferred ? { consent: deferred } : {}),
+    };
+}
+/**
+ * DEV-10455: apply advisor-proposed consent labels after create, in ONE
+ * update that also appends an `el-intake-decision:v1` receipt naming the new
+ * issue. The advisor supplied the policy fields (`repo`, `reason`); el-linear
+ * adds only the identifier and the acting Linear user, read from the API.
+ *
+ * Fail-closed: any problem (an app viewer, a description that already holds a
+ * receipt marker, a failed update, a stored receipt that does not read back
+ * as valid) warns and leaves the issue without the consent label — or, when
+ * the write landed but the read-back fails, says so loudly. Never throws: the
+ * issue already exists.
+ *
+ * Raw GraphQL for the read: it batches `viewer` (including the `app` flag the
+ * SDK's typed viewer wrapper does not expose) with the issue in one round
+ * trip.
+ */
+async function applyAdvisorConsent(created, consent, services) {
+    const labels = consent.labels.join(", ");
+    const skip = (problem) => {
+        outputWarning(`label advisor proposed ${labels}, not applied: ${problem}. Apply it with \`el-linear issues update ${created.identifier} --labels ${consent.labels.join(",")}\` and a receipt in the description.`);
+        return { applied: false, problem };
+    };
+    try {
+        const current = await services.graphQLService.rawRequest("query($id: String!) { viewer { name email app } issue(id: $id) { identifier description } }", { id: created.id });
+        if (!current.issue) {
+            return skip(`issue ${created.identifier} could not be read back`);
+        }
+        const viewer = current.viewer;
+        if (!viewer || viewer.app === true) {
+            return skip("consent must be attributable to a person, and the authenticated Linear viewer is not one");
+        }
+        const actor = (viewer.name?.trim() || viewer.email?.trim() || "").slice(0, 160);
+        if (!actor) {
+            return skip("the authenticated Linear viewer has no name or email");
+        }
+        const existing = current.issue.description ?? "";
+        const description = appendConsentReceipt(existing, formatConsentReceipt({
+            repo: consent.receipt.repo,
+            reason: consent.receipt.reason,
+            actor,
+            issue: current.issue.identifier,
+        }));
+        const planned = evaluateConsentReceipt(description, current.issue.identifier);
+        if (!planned.ok) {
+            return skip(planned.problem);
+        }
+        const updated = await services.issuesService.updateIssue({ id: created.id, description, labelIds: consent.labels }, "adding");
+        const stored = evaluateConsentReceipt(updated.description ?? "", current.issue.identifier);
+        if (!stored.ok) {
+            outputWarning(`label advisor applied ${labels} to ${created.identifier}, but the stored receipt does not read back as valid (${stored.problem}); fix the receipt or remove the label.`);
+            return { applied: true, problem: stored.problem, issue: updated };
+        }
+        outputWarning(`labels added by advisor: ${labels} with an el-intake-decision:v1 receipt for ${current.issue.identifier} (repo ${consent.receipt.repo}, actor ${actor})`);
+        return { applied: true, issue: updated };
+    }
+    catch (error) {
+        return skip(error instanceof Error ? error.message : String(error));
+    }
+}
+/**
+ * DEV-10372: consent-label receipt gate on update. When the update newly
+ * applies a consent label, the resulting description must carry exactly one
+ * valid automatic-implementation receipt for this issue; otherwise refuse and
+ * name what is missing. Labels already on the issue are not re-checked.
+ */
+async function enforceUpdateConsentLabels(issueId, options, graphQLService, linearService) {
+    const gate = getConsentReceiptGateConfig();
+    if (!gate.enabled || !options.labels) {
+        return;
+    }
+    const requested = splitList(options.labels).map((label) => labelNameForId(label) ?? label);
+    const consent = consentLabelsIn(requested, gate.labels);
+    if (consent.length === 0) {
+        return;
+    }
+    const resolved = await linearService.resolveIssueId(issueId);
+    const current = await graphQLService.rawRequest("query($id: String!) { issue(id: $id) { identifier description labels { nodes { name } } } }", { id: resolved });
+    if (!current.issue) {
+        throw new Error(`Issue "${issueId}" not found`);
+    }
+    const existing = new Set(current.issue.labels.nodes.map((label) => label.name.toLowerCase()));
+    const newlyApplied = consent.filter((label) => !existing.has(label.toLowerCase()));
+    if (newlyApplied.length === 0) {
+        return;
+    }
+    const description = typeof options.description === "string"
+        ? options.description
+        : (current.issue.description ?? "");
+    const evaluation = evaluateConsentReceipt(description, current.issue.identifier);
+    if (!evaluation.ok) {
+        throw new Error(`Issue update blocked: ${formatUpdateConsentRefusal(newlyApplied, current.issue.identifier, evaluation.problem)}`);
+    }
+}
+/**
+ * The configured team key for a resolved team UUID, so the label advisor sees
+ * the canonical key (`DEV`) rather than whatever alias the author typed.
+ */
+function teamKeyForId(teamId) {
+    if (!teamId)
+        return undefined;
+    for (const [key, id] of Object.entries(loadConfig().teams ?? {})) {
+        if (id === teamId)
+            return key;
+    }
+    return undefined;
+}
+/** Reverse-map a configured label UUID to its name, so a UUID cannot bypass the gate. */
+function labelNameForId(value) {
+    const labels = loadConfig().labels;
+    const maps = [labels?.workspace ?? {}, ...Object.values(labels?.teams ?? {})];
+    for (const map of maps) {
+        for (const [name, id] of Object.entries(map)) {
+            if (id === value)
+                return name;
+        }
+    }
+    return undefined;
+}
 async function handleCreateIssue(title, options, command) {
     const rootOpts = getRootOpts(command);
     // DEV-7277: non-blocking nudge when this write is landing via the
@@ -833,7 +1028,25 @@ async function handleCreateIssue(title, options, command) {
     // intentionally contains backslash sequences.
     const rawDescription = resolveDescription(options);
     await enforceIntakeDecision(rawDescription ?? "", options);
+    enforceCreateConsentLabels(options);
     const { teamInput, teamId, assigneeId, delegateId, labelIds, status, subscriberIds, priority, } = await resolveCreateInputs(title ?? "", options, rootOpts, rawDescription);
+    // DEV-10372: optional label advisor. Runs after validation/normalization so
+    // it sees the canonical labels, and before every gate that reads labels.
+    const labelAdvice = adviseLabels(title, options, {
+        teamInput: teamKeyForId(teamId) ?? teamInput,
+        description: rawDescription,
+        status,
+    });
+    if (labelAdvice) {
+        for (const id of resolveLabels(labelAdvice.added)) {
+            if (!labelIds.includes(id))
+                labelIds.push(id);
+        }
+        options.labels = [
+            ...(options.labels ? splitList(options.labels) : []),
+            ...labelAdvice.added,
+        ].join(",");
+    }
     const uploadResults = await uploadAttachmentsIfNeeded(options, rootOpts);
     const descriptionWithAttachments = buildDescriptionWithAttachments(rawDescription ?? "", uploadResults);
     // Append messageFooter (config or --footer flag) so auto-link picks up any
@@ -912,6 +1125,33 @@ async function handleCreateIssue(title, options, command) {
             ? { templateId: options.fromTemplate }
             : {}),
     }), { team: options.team ?? loadConfig().defaultTeam, title }, { graphQLService, linearService });
+    // DEV-10455: advisor-proposed consent label + receipt, applied now that
+    // the issue (and its identifier) exists.
+    let issue = result;
+    let labelAdvisorOutput;
+    if (labelAdvice) {
+        labelAdvisorOutput = {
+            added: [...labelAdvice.added],
+            reason: labelAdvice.reason,
+        };
+        if (labelAdvice.consent) {
+            const outcome = await applyAdvisorConsent(result, labelAdvice.consent, {
+                graphQLService,
+                issuesService,
+            });
+            if (outcome.issue)
+                issue = { ...result, ...outcome.issue };
+            if (outcome.applied) {
+                labelAdvisorOutput.added.push(...labelAdvice.consent.labels);
+            }
+            labelAdvisorOutput.consent = {
+                labels: labelAdvice.consent.labels,
+                applied: outcome.applied,
+                repo: labelAdvice.consent.receipt.repo,
+                ...(outcome.problem ? { problem: outcome.problem } : {}),
+            };
+        }
+    }
     const relations = await createRelations(result.id, options, graphQLService, linearService);
     // Pass the ORIGINAL description (pre-wrap) so the extractor's prose-keyword inference
     // ("blocked by", "duplicates", etc.) sees `keyword DEV-100` instead of `keyword [DEV-100](url)`.
@@ -966,7 +1206,8 @@ async function handleCreateIssue(title, options, command) {
         }
     }
     const output = {
-        ...result,
+        ...issue,
+        ...(labelAdvisorOutput ? { labelAdvisor: labelAdvisorOutput } : {}),
         ...(branch ? { branch } : {}),
         ...(claim ? { claim } : {}),
         ...(relations.length > 0 ? { relations } : {}),
@@ -1153,6 +1394,7 @@ async function handleUpdateIssue(issueId, options, command) {
             strict: options.strict,
         });
     }
+    await enforceUpdateConsentLabels(issueId, options, graphQLService, linearService);
     // Save the original (pre-wrap) description so we can pass it to maybeAutoLink later.
     // The wrapped form breaks prose-keyword inference because the inserted `[` defeats the
     // trailing-whitespace anchor in patterns like /\bblocked by\s*$/.
@@ -1483,6 +1725,7 @@ export function setupIssuesCommands(program) {
         .option("--allow-vague-goal", 'skip the goal-completion gate and create even without a falsifiable "Done when" / acceptance-criteria section')
         .option("--allow-missing-intake-decision", "create without a complete intake decision when an accountable human approved the exception (recorded as a gate override)")
         .option("--no-auto-link", "skip auto-linking issue references found in the description")
+        .option("--no-label-advisor", "skip the configured label advisor (config.labelAdvisor / EL_LINEAR_LABEL_ADVISOR) for this issue")
         .option("--footer <text>", "text appended to the description (overrides config.messageFooter)")
         .option("--no-footer", "skip the configured messageFooter for this issue")
         .option("-q, --quiet", "print one confirmation line (IDENTIFIER  STATE  URL) instead of the full JSON")

package/dist/config/config.d.ts

@@ -61,6 +61,23 @@ export interface ElLinearConfig {
         /** Milliseconds before the resolver is treated as a miss (default 8000). */
         resolverTimeoutMs?: number;
     };
+    /**
+     * Optional label-advisor hook (DEV-10372). `command` is an argv array that
+     * `issues create` runs with the proposed issue as JSON on stdin
+     * (`{team, project, title, description, labels, state}`); any labels it
+     * prints are added to the issue and reported. `--no-label-advisor` skips it
+     * for one create. Fail-closed on labels: any advisor failure warns and
+     * creates the issue without extra labels. See `label-advisor.ts`.
+     *
+     * Like `identity.resolver`, this names a binary el-linear spawns, so it is
+     * honored only from personal config or `EL_LINEAR_LABEL_ADVISOR` — never
+     * from the shared team layer.
+     */
+    labelAdvisor?: {
+        command?: string[];
+        /** Milliseconds before the advisor is treated as failed (default 5000). */
+        timeoutMs?: number;
+    };
     /**
      * Term-enforcement rules. Each rule has a canonical form and a list of
      * rejected forms; rejected forms in issue titles/descriptions are flagged
@@ -152,6 +169,19 @@ export interface ElLinearConfig {
         intakeDecisionGate?: false | "warn" | "block";
         /** Headers accepted for the intake section. Defaults to `["Intake decision"]`. */
         intakeSectionHeaders?: string[];
+        /**
+         * OPT-IN consent-label receipt gate (DEV-10372). When `true`, applying a
+         * consent label (see `consentLabels`) is refused unless the issue
+         * description carries exactly one valid `el-intake-decision:v1`
+         * automatic-implementation receipt for that issue. `issues create`
+         * always refuses an explicit consent label (the receipt must name an
+         * issue that does not exist yet) and drops an advisor-proposed one with
+         * a warning. Independent of `enabled` and `--skip-validation`. See
+         * `consent-receipt.ts`.
+         */
+        consentReceiptGate?: boolean;
+        /** Labels treated as consent for the receipt gate. Defaults to `["bot"]`. */
+        consentLabels?: string[];
     };
     /**
      * Optional override for the Linear workspace URL key (the part after

package/dist/config/config.js

@@ -154,6 +154,9 @@ export function loadConfig() {
     // into their personal config at setup time; that keeps the decision with the
     // machine's owner instead of with whoever can land a commit upstream.
     delete teamRaw.identity;
+    // Same reasoning for the label advisor (DEV-10372): it is a binary el-linear
+    // spawns on every `issues create`, so only the operator's own files choose it.
+    delete teamRaw.labelAdvisor;
     // Merge order: defaults → team config → personal config.
     // Arrays (terms, defaultLabels, etc.) are concatenated so personal entries
     // extend team entries rather than replace them.

package/dist/config/consent-receipt.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Consent-label receipt gate (DEV-10372).
+ *
+ * Some workspaces treat a label as **consent** for unattended work: an
+ * automation picks up any issue carrying it. Consent there is not the label
+ * alone — the automation also requires exactly one machine-readable intake
+ * receipt in the issue description:
+ *
+ *   <!-- el-intake-decision:v1 {"policyVersion":"intake-policy/v1", …} -->
+ *
+ * An issue that carries the label without a valid receipt is silently skipped
+ * by that automation, which is the failure this gate removes: el-linear refuses
+ * to apply a consent label unless the resulting description carries a receipt
+ * for that issue, and names what is missing.
+ *
+ * Why el-linear refuses rather than writes the receipt: the receipt names the
+ * target repository, and whether a (team, project) maps to an admissible
+ * repository — and whether that repository is review-only — is policy owned
+ * by the automation, not by a generic Linear CLI. Writing a receipt with a
+ * guessed repository would manufacture consent the policy never granted. The
+ * receipt must also name the issue identifier, which does not exist before
+ * `issues create`, so a create can never carry a valid receipt: the consent
+ * label is applied with `issues update` once the receipt is written.
+ *
+ * The receipt shape mirrors the canonical `intake-policy/v1` wire format
+ * (`validateIntakeDecisionReceipt` in the automation's shared contracts). This
+ * is a strict structural check; the automation's own evaluator remains the
+ * admission authority and additionally checks the repository mapping.
+ *
+ * OPT-IN: dormant unless `validation.consentReceiptGate` is `true`. It is
+ * deliberately independent of `validation.enabled` and `--skip-validation`:
+ * it guards consent integrity, not field hygiene.
+ */
+export declare const DEFAULT_CONSENT_LABELS: string[];
+export declare const INTAKE_POLICY_VERSION = "intake-policy/v1";
+export interface ConsentReceiptGateConfig {
+    enabled: boolean;
+    labels: string[];
+}
+export declare function getConsentReceiptGateConfig(): ConsentReceiptGateConfig;
+/** Consent labels present in `names`, matched case-insensitively. */
+export declare function consentLabelsIn(names: readonly string[], consentLabels: readonly string[]): string[];
+export type ConsentReceiptEvaluation = {
+    ok: true;
+} | {
+    ok: false;
+    problem: string;
+};
+/**
+ * Does `description` carry exactly one valid automatic-implementation receipt
+ * for `identifier`? An `issue-triage` receipt must name this issue; a receipt
+ * copied from another issue is not consent for this one.
+ */
+export declare function evaluateConsentReceipt(description: string, identifier: string): ConsentReceiptEvaluation;
+/** Refusal for `issues create` carrying a consent label. */
+export declare function formatCreateConsentRefusal(labels: readonly string[]): string;
+/** Refusal for `issues update` applying a consent label without a receipt. */
+export declare function formatUpdateConsentRefusal(labels: readonly string[], identifier: string, problem: string): string;
+export interface ConsentReceiptFields {
+    /** Repository the organization's intake policy maps the issue to. */
+    repo: string;
+    /** Why that policy consents to unattended work. */
+    reason: string;
+    /** The acting Linear user, as named by the API. */
+    actor: string;
+    /** The issue identifier the receipt is for. */
+    issue: string;
+}
+/**
+ * The canonical `issue-triage` receipt marker for `fields` (DEV-10455). The
+ * caller supplies every policy field; this only serializes them in the
+ * `intake-policy/v1` shape that `evaluateConsentReceipt` accepts.
+ */
+export declare function formatConsentReceipt(fields: ConsentReceiptFields): string;
+/** `description` with `receipt` appended as its final paragraph. */
+export declare function appendConsentReceipt(description: string, receipt: string): string;

package/dist/config/consent-receipt.js

@@ -0,0 +1,219 @@
+/**
+ * Consent-label receipt gate (DEV-10372).
+ *
+ * Some workspaces treat a label as **consent** for unattended work: an
+ * automation picks up any issue carrying it. Consent there is not the label
+ * alone — the automation also requires exactly one machine-readable intake
+ * receipt in the issue description:
+ *
+ *   <!-- el-intake-decision:v1 {"policyVersion":"intake-policy/v1", …} -->
+ *
+ * An issue that carries the label without a valid receipt is silently skipped
+ * by that automation, which is the failure this gate removes: el-linear refuses
+ * to apply a consent label unless the resulting description carries a receipt
+ * for that issue, and names what is missing.
+ *
+ * Why el-linear refuses rather than writes the receipt: the receipt names the
+ * target repository, and whether a (team, project) maps to an admissible
+ * repository — and whether that repository is review-only — is policy owned
+ * by the automation, not by a generic Linear CLI. Writing a receipt with a
+ * guessed repository would manufacture consent the policy never granted. The
+ * receipt must also name the issue identifier, which does not exist before
+ * `issues create`, so a create can never carry a valid receipt: the consent
+ * label is applied with `issues update` once the receipt is written.
+ *
+ * The receipt shape mirrors the canonical `intake-policy/v1` wire format
+ * (`validateIntakeDecisionReceipt` in the automation's shared contracts). This
+ * is a strict structural check; the automation's own evaluator remains the
+ * admission authority and additionally checks the repository mapping.
+ *
+ * OPT-IN: dormant unless `validation.consentReceiptGate` is `true`. It is
+ * deliberately independent of `validation.enabled` and `--skip-validation`:
+ * it guards consent integrity, not field hygiene.
+ */
+import { loadConfig } from "./config.js";
+export const DEFAULT_CONSENT_LABELS = ["bot"];
+export const INTAKE_POLICY_VERSION = "intake-policy/v1";
+const RECEIPT_RE = /<!--\s*el-intake-decision:v1\s+([^\r\n]+?)\s*-->/g;
+const LINEAR_ISSUE_RE = /^[A-Z][A-Z0-9]*-\d+$/;
+const SENTRY_SOURCE_ISSUE_RE = /^[A-Za-z0-9_.-]+:[A-Za-z0-9_.-]+$/;
+/** True when `text` has no ASCII control character (U+0000–U+001F, U+007F). */
+function isSafeText(text) {
+    for (let i = 0; i < text.length; i++) {
+        const code = text.charCodeAt(i);
+        if (code < 0x20 || code === 0x7f)
+            return false;
+    }
+    return text.length > 0;
+}
+/**
+ * Linear stores descriptions as normalized markdown and backslash-escapes
+ * characters such as `[` and `]`, so a receipt read back from an issue can
+ * contain `\[`. No JSON escape starts with those characters, so dropping a
+ * backslash before a non-JSON-escape character recovers the written receipt
+ * and leaves `\"` and `\\` intact (mirrors the canonical parser).
+ */
+const JSON_ESCAPE_CHARACTERS = new Set([
+    '"',
+    "\\",
+    "/",
+    "b",
+    "f",
+    "n",
+    "r",
+    "t",
+    "u",
+]);
+export function getConsentReceiptGateConfig() {
+    const validation = loadConfig().validation;
+    const labels = validation?.consentLabels && validation.consentLabels.length > 0
+        ? validation.consentLabels
+        : DEFAULT_CONSENT_LABELS;
+    return { enabled: validation?.consentReceiptGate === true, labels };
+}
+/** Consent labels present in `names`, matched case-insensitively. */
+export function consentLabelsIn(names, consentLabels) {
+    const wanted = new Set(consentLabels.map((label) => label.toLowerCase()));
+    return names.filter((name) => wanted.has(name.trim().toLowerCase()));
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function parseReceiptJson(raw) {
+    return JSON.parse(raw.replace(/\\(.)/g, (sequence, character) => JSON_ESCAPE_CHARACTERS.has(character) ? sequence : character));
+}
+/** First structural problem with a parsed receipt, or `null` when valid. */
+function receiptError(value) {
+    if (!isRecord(value))
+        return "receipt is not a JSON object";
+    if (value.policyVersion !== INTAKE_POLICY_VERSION) {
+        return "unsupported policy version";
+    }
+    if (value.decision !== "automatic-implementation") {
+        return `receipt decision is ${JSON.stringify(value.decision)}, not "automatic-implementation"`;
+    }
+    const capabilities = value.capabilities;
+    if (!Array.isArray(capabilities) || capabilities.length === 0) {
+        return "capabilities must be a non-empty array";
+    }
+    const allowed = new Set(["manual-review", "automatic-implementation"]);
+    if (capabilities.some((capability) => typeof capability !== "string" || !allowed.has(capability)) ||
+        new Set(capabilities).size !== capabilities.length) {
+        return "capabilities must be unique known values";
+    }
+    if (!capabilities.includes("manual-review") ||
+        !capabilities.includes("automatic-implementation")) {
+        return "capabilities must include manual-review and automatic-implementation";
+    }
+    if (typeof value.reason !== "string" ||
+        value.reason.trim().length === 0 ||
+        value.reason.length > 500) {
+        return "reason must be a non-empty string of at most 500 characters";
+    }
+    const provenance = value.provenance;
+    if (!isRecord(provenance))
+        return "provenance must be an object";
+    if (provenance.source !== "issue-triage" &&
+        provenance.source !== "sentry-registry") {
+        return "provenance.source is not recognized";
+    }
+    if (typeof provenance.actor !== "string" ||
+        provenance.actor.trim().length === 0 ||
+        provenance.actor.length > 160) {
+        return "provenance.actor must be a non-empty string of at most 160 characters";
+    }
+    if (typeof provenance.issue !== "string" ||
+        provenance.issue.length > 200 ||
+        !isSafeText(provenance.issue) ||
+        (provenance.source === "issue-triage" &&
+            !LINEAR_ISSUE_RE.test(provenance.issue)) ||
+        (provenance.source === "sentry-registry" &&
+            !SENTRY_SOURCE_ISSUE_RE.test(provenance.issue))) {
+        return "provenance.issue has an invalid shape";
+    }
+    if (typeof provenance.repo !== "string" ||
+        provenance.repo.trim().length === 0 ||
+        provenance.repo.length > 200 ||
+        !isSafeText(provenance.repo)) {
+        return "provenance.repo must be a non-empty safe string of at most 200 characters";
+    }
+    return null;
+}
+/**
+ * Does `description` carry exactly one valid automatic-implementation receipt
+ * for `identifier`? An `issue-triage` receipt must name this issue; a receipt
+ * copied from another issue is not consent for this one.
+ */
+export function evaluateConsentReceipt(description, identifier) {
+    const matches = [...description.matchAll(RECEIPT_RE)];
+    if (matches.length === 0) {
+        return {
+            ok: false,
+            problem: "the description has no el-intake-decision:v1 receipt",
+        };
+    }
+    if (matches.length > 1) {
+        return {
+            ok: false,
+            problem: "the description has more than one el-intake-decision:v1 receipt",
+        };
+    }
+    let parsed;
+    try {
+        parsed = parseReceiptJson(matches[0]?.[1] ?? "");
+    }
+    catch {
+        return { ok: false, problem: "the receipt is not valid JSON" };
+    }
+    const error = receiptError(parsed);
+    if (error) {
+        return { ok: false, problem: `the receipt is invalid: ${error}` };
+    }
+    const provenance = parsed
+        .provenance;
+    if (provenance.source === "issue-triage" &&
+        provenance.issue.toUpperCase() !== identifier.toUpperCase()) {
+        return {
+            ok: false,
+            problem: `the receipt names ${provenance.issue}, not ${identifier}`,
+        };
+    }
+    return { ok: true };
+}
+function receiptTemplate(identifier) {
+    return `<!-- el-intake-decision:v1 {"policyVersion":"${INTAKE_POLICY_VERSION}","decision":"automatic-implementation","capabilities":["manual-review","automatic-implementation"],"reason":"<why unattended work is consented>","provenance":{"source":"issue-triage","actor":"<your name>","issue":"${identifier}","repo":"<namespace/repo>"}} -->`;
+}
+/** Refusal for `issues create` carrying a consent label. */
+export function formatCreateConsentRefusal(labels) {
+    const names = labels.map((label) => `"${label}"`).join(", ");
+    return `Label ${names} is consent for unattended work and requires an el-intake-decision:v1 receipt naming the issue, which cannot exist before the issue does. Create the issue without ${names}, then apply it with the receipt in one update:\n\n  el-linear issues update <ID> --labels ${labels.join(",")} --description-file <body-with-receipt>\n\nwhere the body ends with:\n\n${receiptTemplate("<ID>")}`;
+}
+/** Refusal for `issues update` applying a consent label without a receipt. */
+export function formatUpdateConsentRefusal(labels, identifier, problem) {
+    const names = labels.map((label) => `"${label}"`).join(", ");
+    return `Label ${names} is consent for unattended work and requires an el-intake-decision:v1 receipt for ${identifier}, but ${problem}. Include the receipt in the same update (--description / --description-file / --append-description), e.g.:\n\n${receiptTemplate(identifier)}`;
+}
+/**
+ * The canonical `issue-triage` receipt marker for `fields` (DEV-10455). The
+ * caller supplies every policy field; this only serializes them in the
+ * `intake-policy/v1` shape that `evaluateConsentReceipt` accepts.
+ */
+export function formatConsentReceipt(fields) {
+    return `<!-- el-intake-decision:v1 ${JSON.stringify({
+        policyVersion: INTAKE_POLICY_VERSION,
+        decision: "automatic-implementation",
+        capabilities: ["manual-review", "automatic-implementation"],
+        reason: fields.reason,
+        provenance: {
+            source: "issue-triage",
+            actor: fields.actor,
+            issue: fields.issue,
+            repo: fields.repo,
+        },
+    })} -->`;
+}
+/** `description` with `receipt` appended as its final paragraph. */
+export function appendConsentReceipt(description, receipt) {
+    const body = description.trimEnd();
+    return body ? `${body}\n\n${receipt}` : receipt;
+}

package/dist/config/label-advisor.d.ts

@@ -0,0 +1,53 @@
+import type { ElLinearConfig } from "./config.js";
+export interface LabelAdvisorInput {
+    team: string | null;
+    project: string | null;
+    title: string | null;
+    description: string | null;
+    labels: string[];
+    state: string | null;
+}
+/**
+ * Receipt policy fields an advisor may return with a consent label
+ * (DEV-10455). el-linear never guesses these: `repo` is the repository the
+ * organization's intake policy maps this issue to, and `reason` is why that
+ * policy consents to unattended work. el-linear adds only what it knows
+ * itself (the new issue's identifier and the acting Linear user) and writes
+ * the receipt after the issue exists. See `consent-receipt.ts`.
+ */
+export interface LabelAdvisorReceipt {
+    repo: string;
+    reason: string;
+}
+export type LabelAdvisorResult = {
+    ok: true;
+    labels: string[];
+    reason: string | null;
+    receipt: LabelAdvisorReceipt | null;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * The configured advisor argv, or `null` when the hook is off. Env wins over
+ * config so one invocation can point elsewhere or disable it without editing
+ * files.
+ */
+export declare function labelAdvisorCommand(config: Pick<ElLinearConfig, "labelAdvisor">, env?: NodeJS.ProcessEnv): string[] | null;
+/**
+ * Parse what the advisor printed. Returns an error string for anything that is
+ * not exactly a well-formed answer — a malformed answer is a failure, and a
+ * failure adds no labels. Partial acceptance (keep the valid elements, drop the
+ * rest) is deliberately not offered: an advisor emitting garbage is broken, and
+ * trusting half of its output is how a wrong label slips in.
+ */
+export declare function parseLabelAdvisorOutput(stdout: string): LabelAdvisorResult;
+/**
+ * Run the configured advisor. Returns `null` when no advisor is configured,
+ * otherwise the parsed advice or a failure. Never throws.
+ *
+ * Synchronous for the same reason as the identity resolver: it sits on the
+ * critical path of a short-lived CLI, and a single failure site is easier to
+ * reason about than a promise race.
+ */
+export declare function runLabelAdvisor(input: LabelAdvisorInput, config: Pick<ElLinearConfig, "labelAdvisor">, env?: NodeJS.ProcessEnv): LabelAdvisorResult | null;

package/dist/config/label-advisor.js

@@ -0,0 +1,245 @@
+import { spawnSync } from "node:child_process";
+/**
+ * Optional **label advisor hook** (DEV-10372).
+ *
+ * An organization may have a rubric that knows which labels a new issue should
+ * carry — for example "this Tools issue is small and well specified, so it
+ * belongs in the unattended-automation lane". el-linear can consult it on
+ * `issues create`, but it must never learn *what* the rubric is or how to run
+ * it. So the hook is a **command**, modelled on the identity resolver
+ * (DEV-5628, `identity-resolver.ts`):
+ *
+ *   "labelAdvisor": { "command": ["my-rubric", "--advise"] }
+ *
+ * Contract:
+ *
+ *   - stdin: one JSON object describing the proposed issue —
+ *     `{team, project, title, description, labels, state}`.
+ *   - stdout: JSON. Either a bare array of label names (`["bot"]`) or an
+ *     object `{"labels": ["bot"], "reason": "…"}`; one level of `{data: …}`
+ *     envelope is unwrapped (the el-* CLI shape). `{"labels": []}` means
+ *     "nothing to add". With a consent label (see `consent-receipt.ts`) the
+ *     object may also carry `"receipt": {"repo": "…", "reason": "…"}`; then
+ *     el-linear applies the consent label after create together with an
+ *     `el-intake-decision:v1` receipt naming the new issue.
+ *   - exit 0 on success.
+ *
+ * **Fail-closed on labels.** A label may carry meaning — in some workspaces a
+ * label is consent for unattended work — so a broken advisor must never add
+ * one. Non-zero exit, timeout, missing binary, unparseable or malformed output
+ * all return a failure; the caller warns and creates the issue with exactly
+ * the labels the author asked for. The hook never throws.
+ *
+ * The issue text is untrusted input (agents create issues from arbitrary
+ * prose), so it travels on stdin, never in argv, and the command runs with
+ * `shell: false`.
+ */
+/** Env override — a whitespace-separated command; `""` is an explicit OFF. */
+const ADVISOR_ENV = "EL_LINEAR_LABEL_ADVISOR";
+/** An advisor that hasn't answered in this long is not going to. */
+const DEFAULT_TIMEOUT_MS = 5000;
+/** Advice for more labels than this is a confused advisor, not a rubric. */
+const MAX_LABELS = 10;
+const MAX_LABEL_LENGTH = 80;
+const MAX_REASON_LENGTH = 300;
+const MAX_RECEIPT_REPO_LENGTH = 200;
+const MAX_RECEIPT_REASON_LENGTH = 500;
+/** True when `text` has no ASCII control character (U+0000–U+001F, U+007F). */
+function isSafeText(text) {
+    for (let i = 0; i < text.length; i++) {
+        const code = text.charCodeAt(i);
+        if (code < 0x20 || code === 0x7f)
+            return false;
+    }
+    return text.length > 0;
+}
+/**
+ * The configured advisor argv, or `null` when the hook is off. Env wins over
+ * config so one invocation can point elsewhere or disable it without editing
+ * files.
+ */
+export function labelAdvisorCommand(config, env = process.env) {
+    const fromEnv = env[ADVISOR_ENV];
+    if (fromEnv !== undefined) {
+        const argv = fromEnv.trim().split(/\s+/).filter(Boolean);
+        return argv.length > 0 ? argv : null;
+    }
+    const configured = config.labelAdvisor?.command;
+    if (!Array.isArray(configured) || configured.length === 0) {
+        return null;
+    }
+    return configured;
+}
+/**
+ * Resolve the effective timeout. Node treats `timeout <= 0` as *no timeout*,
+ * which would turn a hung advisor into a hung CLI — so non-positive values
+ * fall back to the default, exactly like the identity resolver.
+ */
+function resolveTimeoutMs(config) {
+    const configured = config.labelAdvisor?.timeoutMs;
+    return typeof configured === "number" && configured > 0
+        ? configured
+        : DEFAULT_TIMEOUT_MS;
+}
+/** The advisor classifies issue text; it never needs Linear's token. */
+function advisorEnv(env) {
+    const { LINEAR_API_TOKEN: _dropped, ...rest } = env;
+    return rest;
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/**
+ * Parse what the advisor printed. Returns an error string for anything that is
+ * not exactly a well-formed answer — a malformed answer is a failure, and a
+ * failure adds no labels. Partial acceptance (keep the valid elements, drop the
+ * rest) is deliberately not offered: an advisor emitting garbage is broken, and
+ * trusting half of its output is how a wrong label slips in.
+ */
+export function parseLabelAdvisorOutput(stdout) {
+    const trimmed = stdout.trim();
+    if (!trimmed) {
+        return { ok: false, error: "advisor printed nothing (expected JSON)" };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(trimmed);
+    }
+    catch {
+        return { ok: false, error: "advisor output is not valid JSON" };
+    }
+    if (isRecord(parsed) && isRecord(parsed.data)) {
+        parsed = parsed.data;
+    }
+    let rawLabels;
+    let rawReason = null;
+    let rawReceipt = null;
+    if (Array.isArray(parsed)) {
+        rawLabels = parsed;
+    }
+    else if (isRecord(parsed)) {
+        rawLabels = parsed.labels;
+        rawReason = parsed.reason ?? null;
+        rawReceipt = parsed.receipt ?? null;
+    }
+    else {
+        return {
+            ok: false,
+            error: "advisor output must be a label array or an object",
+        };
+    }
+    if (!Array.isArray(rawLabels)) {
+        return { ok: false, error: 'advisor output has no "labels" array' };
+    }
+    if (rawLabels.length > MAX_LABELS) {
+        return {
+            ok: false,
+            error: `advisor returned ${rawLabels.length} labels (limit ${MAX_LABELS})`,
+        };
+    }
+    const labels = [];
+    for (const label of rawLabels) {
+        if (typeof label !== "string" ||
+            label.trim().length === 0 ||
+            label.length > MAX_LABEL_LENGTH ||
+            !isSafeText(label) ||
+            label.includes(",")) {
+            return {
+                ok: false,
+                error: "advisor returned a label that is not a plain label name",
+            };
+        }
+        const name = label.trim();
+        if (!labels.some((seen) => seen.toLowerCase() === name.toLowerCase())) {
+            labels.push(name);
+        }
+    }
+    if (rawReason !== null && typeof rawReason !== "string") {
+        return { ok: false, error: "advisor reason must be a string" };
+    }
+    const reason = typeof rawReason === "string" && rawReason.trim()
+        ? rawReason.replace(/\s+/g, " ").trim().slice(0, MAX_REASON_LENGTH)
+        : null;
+    const receipt = parseReceiptFields(rawReceipt);
+    if (typeof receipt === "string") {
+        return { ok: false, error: receipt };
+    }
+    return { ok: true, labels, reason, receipt };
+}
+/**
+ * Validate the optional `receipt` object. A malformed one fails the whole
+ * answer (returned as an error string): a receipt is consent, so half of one
+ * is never used.
+ */
+function parseReceiptFields(raw) {
+    if (raw === null) {
+        return null;
+    }
+    if (!isRecord(raw)) {
+        return "advisor receipt must be an object";
+    }
+    const { repo, reason } = raw;
+    if (typeof repo !== "string" ||
+        repo.trim().length === 0 ||
+        repo.length > MAX_RECEIPT_REPO_LENGTH ||
+        !isSafeText(repo)) {
+        return "advisor receipt.repo must be a non-empty plain string";
+    }
+    if (typeof reason !== "string" ||
+        reason.trim().length === 0 ||
+        reason.length > MAX_RECEIPT_REASON_LENGTH ||
+        !isSafeText(reason)) {
+        return `advisor receipt.reason must be a non-empty plain string of at most ${MAX_RECEIPT_REASON_LENGTH} characters`;
+    }
+    return { repo: repo.trim(), reason: reason.trim() };
+}
+/**
+ * Run the configured advisor. Returns `null` when no advisor is configured,
+ * otherwise the parsed advice or a failure. Never throws.
+ *
+ * Synchronous for the same reason as the identity resolver: it sits on the
+ * critical path of a short-lived CLI, and a single failure site is easier to
+ * reason about than a promise race.
+ */
+export function runLabelAdvisor(input, config, env = process.env) {
+    const argv = labelAdvisorCommand(config, env);
+    if (!argv) {
+        return null;
+    }
+    const [command, ...args] = argv;
+    if (!command) {
+        return null;
+    }
+    try {
+        const result = spawnSync(command, args, {
+            encoding: "utf8",
+            input: JSON.stringify(input),
+            timeout: resolveTimeoutMs(config),
+            // A trapped SIGTERM would let a broken advisor wedge the CLI past
+            // its time budget; see the identical note in identity-resolver.ts.
+            killSignal: "SIGKILL",
+            shell: false,
+            stdio: ["pipe", "pipe", "pipe"],
+            env: advisorEnv(env),
+        });
+        // Check `error` before `status`: a timeout that leaves a grandchild
+        // holding the pipe reports ETIMEDOUT with status 0 (identity-resolver.ts).
+        if (result.error) {
+            return { ok: false, error: `${command}: ${result.error.message}` };
+        }
+        if (result.status !== 0) {
+            const stderr = (result.stderr ?? "").trim().split("\n")[0] ?? "";
+            return {
+                ok: false,
+                error: `${command} exited ${result.status ?? `on ${result.signal}`}${stderr ? `: ${stderr}` : ""}`,
+            };
+        }
+        return parseLabelAdvisorOutput(result.stdout ?? "");
+    }
+    catch (err) {
+        return {
+            ok: false,
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+}

package/package.json

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