@awebai/oats 0.22.0

package/capabilities/oats-linear/bin/oats-linear.mjs

@@ -0,0 +1,344 @@
+#!/usr/bin/env node
+/**
+ * JSON-first Linear task operations for OATS.
+ *
+ * Uses Linear's official GraphQL API directly. No third-party Linear CLI or
+ * SDK is required; authentication is a personal key in LINEAR_API_KEY.
+ */
+import { readFileSync } from "node:fs";
+
+const API_URL = process.env.LINEAR_API_URL || "https://api.linear.app/graphql";
+const argv = process.argv.slice(2);
+const command = argv.shift();
+
+function die(message, details) {
+  process.stderr.write(JSON.stringify({ error: String(message), ...(details ? { details } : {}) }, null, 2) + "\n");
+  process.exit(1);
+}
+function print(value) { process.stdout.write(JSON.stringify(value, null, 2) + "\n"); }
+function parseArgs(values) {
+  const options = new Map();
+  const positional = [];
+  for (let i = 0; i < values.length; i++) {
+    const value = values[i];
+    if (!value.startsWith("--")) { positional.push(value); continue; }
+    const name = value.slice(2);
+    const next = values[i + 1];
+    const parsed = next !== undefined && !next.startsWith("--") ? values[++i] : true;
+    const previous = options.get(name) || [];
+    previous.push(parsed);
+    options.set(name, previous);
+  }
+  return {
+    positional,
+    has: (name) => options.has(name),
+    one: (name) => options.get(name)?.at(-1),
+    many: (name) => options.get(name) || [],
+  };
+}
+const args = parseArgs(argv);
+
+async function graphql(query, variables = {}) {
+  const key = process.env.LINEAR_API_KEY;
+  if (!key) die("LINEAR_API_KEY is not set", "Create a personal API key in Linear Settings → Security & access → API keys, export it, then run `oats linear auth`.");
+  let response;
+  try {
+    response = await fetch(API_URL, {
+      method: "POST",
+      headers: {
+        "Authorization": key,
+        "Content-Type": "application/json",
+        "User-Agent": "oats-linear/0.1",
+      },
+      body: JSON.stringify({ query, variables }),
+      signal: AbortSignal.timeout(30000),
+    });
+  } catch (error) {
+    die(`Linear API request failed: ${error.message || error}`);
+  }
+  const text = await response.text();
+  let payload;
+  try { payload = JSON.parse(text); }
+  catch { die(`Linear API returned HTTP ${response.status} with non-JSON content`, text.slice(0, 500)); }
+  if (!response.ok || payload.errors?.length) {
+    const errors = (payload.errors || []).map((error) => ({
+      message: error.extensions?.userPresentableMessage || error.message,
+      code: error.extensions?.code,
+      path: error.path,
+    }));
+    const hint = response.status === 401 ? "Check LINEAR_API_KEY and run `oats linear auth`." : undefined;
+    die(`Linear API request failed (HTTP ${response.status})`, { errors, ...(hint ? { hint } : {}) });
+  }
+  return payload.data;
+}
+
+const PAGE_INFO = "pageInfo { hasNextPage endCursor }";
+const ISSUE_FIELDS = `
+  id identifier title description url priority priorityLabel
+  team { id key name }
+  state { id name type }
+  project { id name slugId }
+  parent { id identifier title }
+  assignee { id name email }
+  labels(first: 100) { nodes { id name } }
+`;
+
+async function teamByKey(key) {
+  if (!key || key === true) die("--team <KEY> is required");
+  const data = await graphql(`
+    query OatsLinearTeam($key: String!) {
+      teams(first: 2, filter: { key: { eqIgnoreCase: $key } }) { nodes { id key name } }
+    }
+  `, { key });
+  if (data.teams.nodes.length === 0) die(`Linear team "${key}" was not found`, "Run `oats linear teams` and use its key.");
+  if (data.teams.nodes.length > 1) die(`Linear team key "${key}" is ambiguous`);
+  return data.teams.nodes[0];
+}
+
+async function statesForTeam(team) {
+  const data = await graphql(`
+    query OatsLinearStates($id: String!) {
+      team(id: $id) { states(first: 100) { nodes { id name type position } } }
+    }
+  `, { id: team.id });
+  return data.team.states.nodes.sort((a, b) => a.position - b.position);
+}
+async function stateByName(team, name) {
+  const states = await statesForTeam(team);
+  const matches = states.filter((state) => state.id === name || state.name.toLowerCase() === String(name).toLowerCase());
+  if (matches.length !== 1) die(`Workflow state "${name}" was not found for team ${team.key}`, { available: states.map((state) => `${state.name} (${state.type})`) });
+  return matches[0];
+}
+
+async function labelsForTeam(team) {
+  const data = await graphql(`
+    query OatsLinearLabels($teamId: ID!) {
+      issueLabels(first: 250, filter: { or: [
+        { team: { null: true } },
+        { team: { id: { eq: $teamId } } }
+      ] }) {
+        nodes { id name color isGroup team { id key } }
+      }
+    }
+  `, { teamId: team.id });
+  return data.issueLabels.nodes;
+}
+async function findLabel(team, name) {
+  const labels = await labelsForTeam(team);
+  const matches = labels.filter((label) => !label.isGroup && label.name.toLowerCase() === String(name).toLowerCase());
+  const scoped = matches.find((label) => label.team?.id === team.id);
+  return scoped || matches.find((label) => !label.team);
+}
+async function ensureAgentLabel(team, alias) {
+  const name = `agent-${alias}`;
+  const existing = await findLabel(team, name);
+  if (existing) return existing;
+  const data = await graphql(`
+    mutation OatsLinearCreateLabel($input: IssueLabelCreateInput!) {
+      issueLabelCreate(input: $input) { success issueLabel { id name color team { id key } } }
+    }
+  `, { input: { name, teamId: team.id, color: "#5E6AD2", description: "OATS agent instance identity" } });
+  if (!data.issueLabelCreate.success) die(`Linear did not create label "${name}"`);
+  return data.issueLabelCreate.issueLabel;
+}
+async function labelByName(team, name) {
+  const label = await findLabel(team, name);
+  if (!label) die(`Label "${name}" was not found for team ${team.key}`, "Create it in Linear first. Agent labels are created automatically by --agent.");
+  return label;
+}
+
+async function projectsForTeam(team) {
+  const data = await graphql(`
+    query OatsLinearProjects($teamId: ID!) {
+      projects(first: 250, filter: { accessibleTeams: { some: { id: { eq: $teamId } } } }) {
+        nodes { id name slugId status { id name type } teams(first: 20) { nodes { id key name } } }
+      }
+    }
+  `, { teamId: team.id });
+  return data.projects.nodes;
+}
+async function projectByRef(team, ref) {
+  const projects = await projectsForTeam(team);
+  const needle = String(ref).toLowerCase();
+  const matches = projects.filter((project) =>
+    project.id === ref || project.slugId.toLowerCase() === needle || project.name.toLowerCase() === needle);
+  if (matches.length !== 1) die(`Project "${ref}" ${matches.length ? "is ambiguous" : "was not found"} for team ${team.key}`, { available: projects.map((project) => ({ name: project.name, slug: project.slugId })) });
+  return matches[0];
+}
+
+async function issueById(id) {
+  if (!id || id === true) die("an issue identifier such as ENG-123 is required");
+  const data = await graphql(`
+    query OatsLinearIssue($id: String!) { issue(id: $id) { ${ISSUE_FIELDS} } }
+  `, { id });
+  return data.issue;
+}
+
+function textOption(name) {
+  const inline = args.one(name);
+  const file = args.one(`${name}-file`);
+  if (inline !== undefined && file !== undefined) die(`use only one of --${name} or --${name}-file`);
+  if (file !== undefined) {
+    if (file === true) die(`--${name}-file needs a path`);
+    try { return readFileSync(file, "utf8").trim(); }
+    catch (error) { die(`cannot read --${name}-file ${file}: ${error.message}`); }
+  }
+  return inline;
+}
+function assertTerminalAllowed(state) {
+  if (["completed", "canceled", "duplicate"].includes(state.type) && !args.has("allow-terminal")) {
+    die(`refusing terminal state "${state.name}" without --allow-terminal`, "Agents should hand work to review, not close or cancel it. Use --allow-terminal only with explicit human authorization.");
+  }
+}
+
+async function auth() {
+  const data = await graphql(`
+    query OatsLinearAuth { viewer { id name email } organization { id name urlKey } }
+  `);
+  print({ authenticated: true, endpoint: API_URL, viewer: data.viewer, workspace: data.organization });
+}
+async function teams() {
+  const data = await graphql(`
+    query OatsLinearTeams { teams(first: 100) { nodes { id key name } } }
+  `);
+  print(data.teams.nodes);
+}
+async function states() {
+  const team = await teamByKey(args.one("team"));
+  print(await statesForTeam(team));
+}
+async function projects() {
+  const team = await teamByKey(args.one("team"));
+  print(await projectsForTeam(team));
+}
+async function labels() {
+  const team = await teamByKey(args.one("team"));
+  print(await labelsForTeam(team));
+}
+
+async function listIssues() {
+  const team = await teamByKey(args.one("team"));
+  const requestedLimit = Number(args.one("limit") || 100);
+  if (!Number.isInteger(requestedLimit) || requestedLimit < 1 || requestedLimit > 250) die("--limit must be an integer from 1 to 250");
+  const filter = { team: { id: { eq: team.id } } };
+  if (!args.has("all")) filter.state = { type: { nin: ["completed", "canceled", "duplicate"] } };
+  if (args.one("agent")) filter.labels = { some: { name: { eqIgnoreCase: `agent-${args.one("agent")}` } } };
+  if (args.one("project")) {
+    const project = await projectByRef(team, args.one("project"));
+    filter.project = { id: { eq: project.id } };
+  }
+  const data = await graphql(`
+    query OatsLinearIssues($first: Int!, $filter: IssueFilter) {
+      issues(first: $first, filter: $filter) { nodes { ${ISSUE_FIELDS} } ${PAGE_INFO} }
+    }
+  `, { first: requestedLimit, filter });
+  print({ issues: data.issues.nodes, pageInfo: data.issues.pageInfo });
+}
+async function createIssue() {
+  const team = await teamByKey(args.one("team"));
+  const title = args.one("title");
+  if (!title || title === true) die("--title <text> is required");
+  let description = textOption("description");
+  const input = { teamId: team.id, title };
+  if (description !== undefined) input.description = description;
+  if (args.one("project")) input.projectId = (await projectByRef(team, args.one("project"))).id;
+  if (args.one("parent")) input.parentId = args.one("parent");
+  if (args.one("state")) {
+    const state = await stateByName(team, args.one("state"));
+    assertTerminalAllowed(state);
+    input.stateId = state.id;
+  }
+  const issueLabels = [];
+  if (args.one("agent")) {
+    const alias = args.one("agent");
+    issueLabels.push(await ensureAgentLabel(team, alias));
+    if (!/^Agent:/mi.test(description || "")) {
+      description = `${description ? `${description.trim()}\n\n` : ""}---\nAgent: ${alias}`;
+      input.description = description;
+    }
+  }
+  for (const name of args.many("label")) issueLabels.push(await labelByName(team, name));
+  if (issueLabels.length) input.labelIds = [...new Set(issueLabels.map((label) => label.id))];
+  const data = await graphql(`
+    mutation OatsLinearIssueCreate($input: IssueCreateInput!) {
+      issueCreate(input: $input) { success issue { ${ISSUE_FIELDS} } }
+    }
+  `, { input });
+  if (!data.issueCreate.success || !data.issueCreate.issue) die("Linear did not create the issue");
+  print(data.issueCreate.issue);
+}
+async function updateIssue(id) {
+  const current = await issueById(id);
+  const team = current.team;
+  const input = {};
+  if (args.has("title")) input.title = args.one("title");
+  const description = textOption("description");
+  if (description !== undefined) input.description = description;
+  if (args.one("state")) {
+    const state = await stateByName(team, args.one("state"));
+    assertTerminalAllowed(state);
+    input.stateId = state.id;
+  }
+  const added = [];
+  if (args.one("agent")) added.push((await ensureAgentLabel(team, args.one("agent"))).id);
+  for (const name of args.many("add-label")) added.push((await labelByName(team, name)).id);
+  const removed = [];
+  for (const name of args.many("remove-label")) removed.push((await labelByName(team, name)).id);
+  if (added.length) input.addedLabelIds = [...new Set(added)];
+  if (removed.length) input.removedLabelIds = [...new Set(removed)];
+  if (Object.keys(input).length === 0) die("no update supplied", "Use --title, --description[-file], --state, --agent, --add-label, or --remove-label.");
+  const data = await graphql(`
+    mutation OatsLinearIssueUpdate($id: String!, $input: IssueUpdateInput!) {
+      issueUpdate(id: $id, input: $input) { success issue { ${ISSUE_FIELDS} } }
+    }
+  `, { id, input });
+  if (!data.issueUpdate.success || !data.issueUpdate.issue) die(`Linear did not update ${id}`);
+  print(data.issueUpdate.issue);
+}
+async function commentIssue(id) {
+  const body = textOption("body");
+  if (!body || body === true) die("--body <markdown> or --body-file <path> is required");
+  const data = await graphql(`
+    mutation OatsLinearComment($input: CommentCreateInput!) {
+      commentCreate(input: $input) { success comment { id body createdAt url user { id name } } }
+    }
+  `, { input: { issueId: id, body } });
+  if (!data.commentCreate.success) die(`Linear did not comment on ${id}`);
+  print(data.commentCreate.comment);
+}
+
+function usage() {
+  process.stderr.write(`oats linear commands (all output JSON):
+  auth
+  teams
+  states --team <KEY>
+  projects --team <KEY>
+  labels --team <KEY>
+  issue list --team <KEY> [--agent <alias>] [--project <name|slug>] [--all] [--limit 100]
+  issue get <KEY-123>
+  issue create --team <KEY> --title <text> [--description <md>|--description-file <path>]
+      [--project <name|slug>] [--parent <KEY-123>] [--state <name>] [--agent <alias>]
+      [--label <name> ...]
+  issue update <KEY-123> [--title <text>] [--description <md>|--description-file <path>]
+      [--state <name>] [--agent <alias>] [--add-label <name> ...] [--remove-label <name> ...]
+      [--allow-terminal]
+  issue comment <KEY-123> (--body <md>|--body-file <path>)
+`);
+  process.exit(1);
+}
+
+if (command === "auth") await auth();
+else if (command === "teams") await teams();
+else if (command === "states") await states();
+else if (command === "projects") await projects();
+else if (command === "labels") await labels();
+else if (command === "issue") {
+  const subcommand = args.positional[0];
+  const id = args.positional[1];
+  if (subcommand === "list") await listIssues();
+  else if (subcommand === "get") print(await issueById(id));
+  else if (subcommand === "create") await createIssue();
+  else if (subcommand === "update") await updateIssue(id);
+  else if (subcommand === "comment") await commentIssue(id);
+  else usage();
+} else usage();

package/capabilities/oats-linear/injects/linear.md

@@ -0,0 +1,8 @@
+## Tasks: Linear
+
+Your tasks layer is **Linear**, operated through the JSON-first `oats linear`
+commands. You are identified by the label `agent-<your-instance-name>`, not
+by changing the human assignee. Load the **linear-tasks** skill before reading
+your queue, creating or updating issues/sub-issues, changing status, or posting
+handoffs. Tasks only: status and outcomes live in Linear; conversation lives
+in your deployment's messaging layer.

package/capabilities/oats-linear/oats.json

@@ -0,0 +1,24 @@
+{
+  "capability": "oats.linear",
+  "command": "linear",
+  "version": "1.0.0",
+  "compatibility": { "oats": ">=0.6.2" },
+  "layer": "tasks",
+  "description": "Tasks layer via Linear: JSON-first GraphQL commands, project/issue/sub-issue workflow, label-based agent identity.",
+  "requires": [],
+  "skills": [
+    "skills"
+  ],
+  "commands": {
+    "auth": "bin/oats-linear.mjs auth",
+    "teams": "bin/oats-linear.mjs teams",
+    "states": "bin/oats-linear.mjs states",
+    "projects": "bin/oats-linear.mjs projects",
+    "labels": "bin/oats-linear.mjs labels",
+    "issue": "bin/oats-linear.mjs issue"
+  },
+  "inject": "injects/linear.md",
+  "hooks": {
+    "spawn": "bin/oats-linear-hook.mjs spawn"
+  }
+}

package/capabilities/oats-linear/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@awebai/oats-linear",
+  "version": "0.1.0",
+  "description": "OATS tasks provider: Linear via its GraphQL API, with JSON-first commands and label-based agent identity",
+  "keywords": [
+    "pi-package",
+    "oats",
+    "linear",
+    "tasks"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/awebai/oats",
+    "directory": "capabilities/oats-linear"
+  },
+  "license": "MIT",
+  "type": "module",
+  "scripts": {
+    "test": "node --test"
+  },
+  "bin": {
+    "oats-linear": "./bin/oats-linear.mjs"
+  },
+  "pi": {
+    "skills": [
+      "./skills"
+    ]
+  }
+}

package/capabilities/oats-linear/skills/linear-tasks/SKILL.md

@@ -0,0 +1,217 @@
+---
+name: linear-tasks
+description: >-
+  Linear task tracking for OATS agent instances. Use when reading an agent's
+  Linear work queue, opening or inspecting an issue, creating issues or
+  sub-issues, claiming work with an agent label, posting progress/blocker/
+  handoff comments, or moving work through Linear workflow states. Also use
+  when asked about "my issue", "the project", "the board", a Linear issue key
+  such as ENG-123, or shared task status. Uses JSON-first `oats linear` commands.
+---
+
+# Agent task tracking in Linear
+
+Linear is your deployment's **tasks layer**: task status and outcomes live
+here. Conversation lives in the messaging layer; a message may nudge someone,
+but it never replaces the Linear update.
+
+## Deployment target and authentication
+
+Get the target from the `Tasks: Linear` line in your `TASK.md` briefing:
+
+- **team** is required and uses Linear's issue-prefix key (for example `ENG`).
+- **project** is an optional deployment default. Do not invent one when unset.
+- **alias** is your exact OATS instance name; your label is `agent-<alias>`.
+
+Before the first operation, run:
+
+```bash
+oats linear auth
+oats linear teams
+```
+
+If `LINEAR_API_KEY` is missing or rejected, **stop and ask the human** to create
+or export a personal API key (Linear Settings → Security & access → API keys).
+Never ask for the key's value, print it, put it in a command argument, or store
+it in OATS config/files. Never attempt an interactive login.
+
+Commands emit JSON. An error is JSON on stderr with a non-zero exit code; act
+on that error rather than retrying variants blindly.
+
+## Hierarchy
+
+- **Project** — an optional, human-owned outcome or initiative container. Do
+  not create, rename, change status, or close projects.
+- **Issue** — the normal bounded work item assigned to an agent.
+- **Sub-issue** — an issue with a parent, used only when the parent genuinely
+  decomposes into multiple independently verifiable pieces.
+
+Do not create placeholder parent issues for one child. Every issue belongs to
+a team; project membership is optional unless your briefing names a project.
+
+## Project context and documentation
+
+Use project-level and issue-level records deliberately:
+
+- **Project overview**: intent, scope/non-goals, ownership, constraints, human
+  gates, architecture, and success criteria.
+- **Project documents**: detailed designs, decisions, runbooks, and research.
+- **Issues/sub-issues**: bounded execution and acceptance criteria.
+- **Issue comments**: milestones, blockers, handoffs, verification, and links.
+
+The overview/documents explain the work; issues execute it. Link a governing
+project document from each affected issue rather than copying inconsistent
+versions. Keep task status in issues, not project prose or messaging.
+
+The current wrapper can discover project metadata but **cannot read or mutate
+project overview Markdown or Linear documents**:
+
+```bash
+oats linear projects --team <TEAM>
+```
+
+That output includes project IDs, names, slugs, status, and teams. Project
+creation, lifecycle/status, overview content, documents, and project updates
+remain human-owned in the Linear UI. If your task depends on unavailable
+project documentation, ask the human for its URL/content; never infer policy
+from an issue title.
+
+## Identity and ownership
+
+- Keep the **human assignee unchanged**. A personal API key acts as its human;
+  OATS agents are not Linear users.
+- Claim work with label `agent-<exact-instance-name>`. `--agent <alias>` creates
+  this team-scoped label on first use and applies it.
+- New issue descriptions also receive `Agent: <alias>`. On existing issues,
+  use the label and comments; do not rewrite a human's description merely to
+  add the line.
+- Never delete issues, labels, or comments. Do not change cycle, priority,
+  project, parent, or assignee unless explicitly directed.
+
+## Read before writing
+
+```bash
+# Your open queue (terminal states excluded by default)
+oats linear issue list --team <TEAM> --agent <alias>
+
+# Narrow to the deployment project when one is configured
+oats linear issue list --team <TEAM> --agent <alias> --project "<PROJECT>"
+
+# Read full task context before acting
+oats linear issue get <TEAM>-123
+
+# Discover this team's real workflow names; never guess them
+oats linear states --team <TEAM>
+```
+
+`issue get` includes team, status/type, project, parent, assignee, labels,
+description, and URL. Read the parent too when working a sub-issue. Record the
+issue key in instance memory (`STATE.md`) if your knowledge layer provides it.
+
+## Work an issue
+
+1. Read the issue and parent/project context.
+2. If not already claimed, apply your identity label:
+
+   ```bash
+   oats linear issue update <TEAM>-123 --agent <alias>
+   ```
+
+3. Move to the deployment's `started` workflow state (often `In Progress`),
+   using the exact name returned by `oats linear states`:
+
+   ```bash
+   oats linear issue update <TEAM>-123 --state "In Progress"
+   ```
+
+4. Post only useful durable events, prefixed with your alias:
+
+   ```bash
+   oats linear issue comment <TEAM>-123 \
+     --body "[<alias>] milestone: implemented parser; tests pass with node --test"
+   oats linear issue comment <TEAM>-123 \
+     --body "[<alias>] blocked: need API scope decision from @owner"
+   oats linear issue comment <TEAM>-123 \
+     --body "[<alias>] handoff → <next-alias>: branch agents/x, verify with npm test"
+   ```
+
+5. When implementation is review-ready, comment the outcome (branch/PR and
+   verification), then move to the team's review state. Do **not** mark it
+   completed:
+
+   ```bash
+   oats linear issue comment <TEAM>-123 \
+     --body "[<alias>] review-ready: PR <url>; verified npm test"
+   oats linear issue update <TEAM>-123 --state "In Review"
+   ```
+
+Workflow names vary. Agents may use backlog/unstarted/started states. The
+wrapper refuses `completed`, `canceled`, and `duplicate` state types unless
+`--allow-terminal` is supplied; use that override only after explicit human
+authorization and mention that authorization in a comment.
+
+## Create bounded work
+
+Use ≤12 words in the title. Describe requirements and acceptance checks, not a
+speculative implementation. For multiline Markdown, prefer a file so shell
+quoting cannot corrupt it.
+
+```bash
+cat > /tmp/linear-description.md <<'EOF'
+Why this is needed.
+
+Acceptance:
+- [ ] Observable outcome one
+- [ ] Verification command or evidence
+EOF
+
+oats linear issue create --team <TEAM> --project "<PROJECT>" \
+  --title "Bounded outcome" --description-file /tmp/linear-description.md \
+  --agent <alias>
+```
+
+Omit `--project` when the briefing has none. Create a sub-issue only for a real
+independent slice:
+
+```bash
+oats linear issue create --team <TEAM> --parent <TEAM>-123 \
+  --title "Independent child outcome" \
+  --description-file /tmp/linear-description.md --agent <alias>
+```
+
+`--project` sets project membership; `--parent` sets issue hierarchy. They are
+independent, so supply both when a sub-issue must explicitly carry the project:
+
+```bash
+oats linear issue create --team <TEAM> --project "<PROJECT>" \
+  --parent <TEAM>-123 --title "Independent child outcome" \
+  --description-file /tmp/linear-description.md --agent <alias>
+```
+
+Use an existing non-agent label only after discovery:
+
+```bash
+oats linear labels --team <TEAM>
+oats linear issue create --team <TEAM> --title "Fix token refresh" \
+  --label bug --agent <alias>
+```
+
+## Current command boundary
+
+Supported: discover teams/states/projects/labels; list/get/create/update/comment
+on issues; create sub-issues; claim work with agent labels.
+
+Not supported: create/update/close projects; read/edit project overviews;
+list/read/create/edit project documents; publish project updates; move an
+existing issue into/out of a project; reparent an existing issue; or create
+issue relations such as blocks/related. Those operations stay in the Linear
+UI with the human. **Do not invent GraphQL calls or command flags to bypass
+this boundary.**
+
+## Validate every mutation
+
+Mutation output is the resulting issue/comment. Check its identifier, status,
+project/parent, and labels immediately. Then run `issue get` for
+correctness-critical changes. If a GraphQL permission or validation error
+persists, post no partial workaround: preserve the task state and escalate to
+the human with the exact error (never the key).