dev-loops 0.6.0 → 0.7.1

package/cli/index.mjs

@@ -17,6 +17,34 @@ import { createPiAdapter } from "@dev-loops/core/harness";
 
 const REPO_ROOT = fileURLToPath(new URL("..", import.meta.url));
 
+// `project` is an alias for `queue` minus the run driver — derived, not duplicated.
+const QUEUE_ROUTES = {
+  run:            "scripts/loop/run-queue.mjs",
+  list:    "scripts/projects/list-queue-items.mjs",
+  add:     "scripts/projects/add-queue-item.mjs",
+  move:    "scripts/projects/move-queue-item.mjs",
+  reorder: "scripts/projects/reorder-queue-item.mjs",
+  "archive-done": "scripts/projects/archive-done-items.mjs",
+  "sync-status": "scripts/projects/sync-item-status.mjs",
+  ensure:  "scripts/projects/ensure-queue-board.mjs",
+  "resolve-active": "scripts/projects/resolve-active-board-item.mjs",
+  reconcile: "scripts/projects/reconcile-queue.mjs",
+};
+const { run: _queueRunRoute, ...PROJECT_ROUTES } = QUEUE_ROUTES;
+
+const QUEUE_DESCRIPTIONS = {
+  run: "Run queue driver",
+  list: "List queue board items",
+  add: "Add issue/PR to queue board",
+  move: "Move queue item between Status columns",
+  reorder: "Reorder items (move-to-top/move-after/order, --dry-run)",
+  "archive-done": "Archive closed Done items older than a duration",
+  "sync-status": "Sync a queued issue/PR's board Status column (best-effort)",
+  ensure: "Create/repair queue board bootstrap surface",
+  reconcile: "Reconcile board Status columns from live GitHub state (idempotent)",
+};
+const { run: _queueRunDescription, ...PROJECT_DESCRIPTIONS } = QUEUE_DESCRIPTIONS;
+
 const SUBCOMMAND_ROUTES = {
   gate: {
     "upsert-verdict":     "scripts/github/upsert-checkpoint-verdict.mjs",
@@ -50,27 +78,8 @@ const SUBCOMMAND_ROUTES = {
     "ready-for-review": "scripts/github/ready-for-review.mjs",
     "reconcile-draft":  "scripts/github/reconcile-draft-gate.mjs",
   },
-  project: {
-    list:    "scripts/projects/list-queue-items.mjs",
-    add:     "scripts/projects/add-queue-item.mjs",
-    move:    "scripts/projects/move-queue-item.mjs",
-    reorder: "scripts/projects/reorder-queue-item.mjs",
-    "archive-done": "scripts/projects/archive-done-items.mjs",
-    "sync-status": "scripts/projects/sync-item-status.mjs",
-    ensure:  "scripts/projects/ensure-queue-board.mjs",
-    "resolve-active": "scripts/projects/resolve-active-board-item.mjs",
-  },
-  queue: {
-    run:            "scripts/loop/run-queue.mjs",
-    list:    "scripts/projects/list-queue-items.mjs",
-    add:     "scripts/projects/add-queue-item.mjs",
-    move:    "scripts/projects/move-queue-item.mjs",
-    reorder: "scripts/projects/reorder-queue-item.mjs",
-    "archive-done": "scripts/projects/archive-done-items.mjs",
-    "sync-status": "scripts/projects/sync-item-status.mjs",
-    ensure:  "scripts/projects/ensure-queue-board.mjs",
-    "resolve-active": "scripts/projects/resolve-active-board-item.mjs",
-  },
+  queue: QUEUE_ROUTES,
+  project: PROJECT_ROUTES,
   inspect: {
     run:    "scripts/loop/inspect-run.mjs",
     viewer: "scripts/loop/inspect-run-viewer.mjs",
@@ -143,25 +152,8 @@ const SUBCOMMAND_DESCRIPTIONS = {
     "ready-for-review": "Mark PR ready for review",
     "reconcile-draft": "Reconcile non-draft PR",
   },
-  project: {
-    list: "List queue board items",
-    add: "Add issue/PR to queue board",
-    move: "Move queue item between Status columns",
-    reorder: "Reorder items (move-to-top/move-after/order, --dry-run)",
-    "archive-done": "Archive closed Done items older than a duration",
-    "sync-status": "Sync a queued issue/PR's board Status column (best-effort)",
-    ensure: "Create/repair queue board bootstrap surface",
-  },
-  queue: {
-    run: "Run queue driver",
-    list: "List queue board items",
-    add: "Add issue/PR to queue board",
-    move: "Move queue item between Status columns",
-    reorder: "Reorder items (move-to-top/move-after/order, --dry-run)",
-    "archive-done": "Archive closed Done items older than a duration",
-    "sync-status": "Sync a queued issue/PR's board Status column (best-effort)",
-    ensure: "Create/repair queue board bootstrap surface",
-  },
+  queue: QUEUE_DESCRIPTIONS,
+  project: PROJECT_DESCRIPTIONS,
   inspect: {
     run: "Inspect run state",
     viewer: "Start inspection viewer",
@@ -252,7 +244,8 @@ function buildCliHelpLines() {
     "Use `dev-loops <category> <subcommand> --help` for per-subcommand usage.",
     "",
     "`/dev-loops hide` remains an extension-only Pi command.",
-    "Run via `npx dev-loops` (or `npm install -g dev-loops` for the shell command); see the",
+    "Run via `npx dev-loops@<version>` pinned to your plugin/extension version (a global",
+    "`npm install -g dev-loops` can drift and is not the supported invocation path); see the",
     "README for Pi-extension and Claude Code plugin setup.",
   ];
 }
@@ -275,7 +268,7 @@ function orderedCliSetupSteps(checks) {
   return [
     "1. Use `/dev-loop` (Claude Code) or `/skill:dev-loop` (Pi) to start or continue a dev loop — the single public entry.",
     "2. Run `dev-loops status` whenever you want a concise readiness snapshot.",
-    "3. Run via `npx dev-loops` (or `npm install -g dev-loops` for the shell command); see the README for Pi-extension and Claude Code plugin setup.",
+    "3. Run via `npx dev-loops@<version>` pinned to your plugin/extension version (a global `npm install -g dev-loops` can drift and is not the supported invocation path); see the README for Pi-extension and Claude Code plugin setup.",
   ];
 }
 

package/extension/README.md

@@ -9,6 +9,8 @@ Installing the package exposes two thin wrappers over one shared deterministic c
 
 Installing the package with `pi install git:github.com/mfittko/dev-loops` exposes the packaged skills through `package.json` `pi.skills`, and the extension syncs packaged agent files (`agents/*.agent.md`) into `~/.agents/` on `session_start`.
 
+**Version pinning (no global-install skew).** The extension resolves both the CLI and `@dev-loops/core` from the installed, pinned package (module imports, not a global `dev-loops` binary), and updates itself via the pinned `pi update git:github.com/mfittko/dev-loops` seam above. It never depends on a separately-updated global install, so it stays in lockstep with the installed version by construction (#1036).
+
 ## Command surface
 
 - `/dev-loops`
@@ -144,7 +146,6 @@ autonomy:
 
 workflow:
   requireRetrospective: true
-  requireRetrospectiveGate: true
   requireDraftFirst: true
   devModeDefault: true
 ```
@@ -178,13 +179,12 @@ The optional `workflow` family carries repo-level workflow posture without hardc
 ```yaml
 workflow:
   requireRetrospective: false
-  requireRetrospectiveGate: false
   requireDraftFirst: false
   devModeDefault: false
 ```
 
 - `requireRetrospective` — when enabled by repo settings, the next qualifying GitHub-first async start/resume must honor the retrospective checkpoint gate
-- `requireRetrospectiveGate` — when enabled by repo settings, merge readiness after `pre_approval_gate` requires a completed retrospective checkpoint that explicitly approves merge. The retrospective must include: `state: "complete"`, `mergeApproved: true`, `followedWorkingAgreement` (boolean), `gateQuality` (string), `unexpectedFindings` (string), and `mergeRecommendation` (string). A `SKIPPED` retrospective does not satisfy the merge gate when this flag is enabled.
+- `requireRetrospectiveGate` — **removed (issue #1077)**. The retrospective is now advisory: it always runs and returns findings to the conductor via the envelope's `retrospectiveFindings` field and an advisory PR comment, never blocking merge or any transition. There is no longer a merge-gate config key for the retrospective.
 - `requireDraftFirst` — marks draft-first PR creation as required workflow policy for repos that opt in
 - `devModeDefault` — declares that local implementation should default to formal dev mode; this is config-only for now and establishes source-of-truth config plus docs for future runtime consumers
 
@@ -222,7 +222,7 @@ Current Phase 3+ contract:
 
 Root verification and test commands are intentionally explicit:
 - `npm run verify` is the canonical root verification path (`npm test` + `npm run test:dev-loop`)
-- `npm test` runs the current root test suite (`test:assets`, `test:extension`, `test:scripts`, and `test:core`)
+- `npm test` runs the current root test suite (`test:assets`, `test:extension`, `test:scripts`, `test:core`, and `test:docs`)
 - `npm run test:extension`
 - `npm run test:extension` currently expands to one `node --import tsx --test ...` invocation in `package.json`; prefer the script entrypoint over copying the file list into downstream docs or runbooks
 - `npm run test:scripts`

package/extension/checks.ts

@@ -1,4 +1,4 @@
-import { collectDevLoopChecks as collectSharedDevLoopChecks, DEV_LOOP_CHECK_IDS } from '../lib/dev-loops-core.mjs';
+import { DEV_LOOP_CHECK_IDS } from '../lib/dev-loops-core.mjs';
 import { createInspectRunViewerLifecycleManager } from '../scripts/loop/inspect-run-viewer/managed-instance.mjs';
 import type { ExtensionHarnessAdapter } from './harness-types.ts';
 
@@ -77,7 +77,3 @@ export function createExtensionCoreRuntime(
     },
   };
 }
-
-export async function collectDevLoopChecks(adapter: ExtensionHarnessAdapter): Promise<DevLoopCheck[]> {
-  return collectSharedDevLoopChecks(createExtensionCoreRuntime(adapter));
-}

package/extension/harness-types.ts

@@ -29,6 +29,7 @@ export type HarnessContext = {
   cwd: string;
   hasUI: boolean;
   ui: HarnessUi;
+  sendUserMessage?: (message: string, options?: Record<string, unknown>) => unknown;
 };
 
 export type HarnessLifecycleEvent = 'session_start' | 'tool_result' | 'user_bash' | 'agent_end';

package/extension/index.ts

@@ -26,6 +26,10 @@ const STATUS_KEY = 'dev-loops';
 const WIDGET_KEY = 'dev-loops.setup';
 const PACKAGED_AGENTS_ROOT = new URL('../agents/', import.meta.url);
 
+async function dispatchDevLoopIntent(ctx: { sendUserMessage?: (message: string) => unknown }, intent: string) {
+  await ctx.sendUserMessage?.(`/skill:dev-loop ${intent}`);
+}
+
 export function syncPackagedAgents({
   sourceRoot = fileURLToPath(PACKAGED_AGENTS_ROOT),
   targetRoot = path.join(os.homedir(), '.agents'),
@@ -92,10 +96,12 @@ export default function (pi: ExtensionAPI, runtimeOverrides: ExtensionRuntimeOve
           return;
         case 'entrypoint':
           ctx.ui.setWidget(WIDGET_KEY, buildEntrypointLines(result.action, result.intent), { placement: 'belowEditor' });
+          await dispatchDevLoopIntent(ctx, result.intent);
           ctx.ui.notify(`dev-loops ${result.action}: ${result.intent}`, 'info');
           return;
         case 'start_spike':
           ctx.ui.setWidget(WIDGET_KEY, buildEntrypointLines('start-spike', result.intent), { placement: 'belowEditor' });
+          await dispatchDevLoopIntent(ctx, result.intent);
           ctx.ui.notify(`dev-loops start-spike: ${result.intent}`, 'info');
           return;
         case 'checks':

package/extension/pi-extension-adapter.ts

@@ -26,6 +26,7 @@ import type {
 
 export function toHarnessContext(ctx: Partial<ExtensionContext> | undefined): HarnessContext {
   const ui = ctx?.ui;
+  const sender = (ctx as { sendUserMessage?: (message: string, options?: Record<string, unknown>) => unknown } | undefined)?.sendUserMessage;
   return {
     cwd: (ctx?.cwd as string) ?? process.cwd(),
     hasUI: Boolean(ctx?.hasUI),
@@ -34,6 +35,7 @@ export function toHarnessContext(ctx: Partial<ExtensionContext> | undefined): Ha
       setWidget: (key, lines, options) => ui?.setWidget?.(key, lines as never, options as never),
       setStatus: (key, text) => ui?.setStatus?.(key, text as never),
     },
+    sendUserMessage: sender ? (message, options) => sender.call(ctx, message, options) : undefined,
   };
 }
 

package/extension/presentation.ts

@@ -19,7 +19,7 @@ function checkMap(checks: DevLoopCheck[]): Map<DevLoopCheckId, DevLoopCheck> {
   return new Map(checks.map((check) => [check.id, check]));
 }
 
-export function orderedSetupSteps(checks: DevLoopCheck[]): string[] {
+function orderedSetupSteps(checks: DevLoopCheck[]): string[] {
   const byId = checkMap(checks);
   const uniqueSteps = [...new Set(DEV_LOOP_CHECK_IDS.filter((id) => byId.get(id)?.ok === false).map((id) => SETUP_GUIDANCE[id]))];
   const steps = uniqueSteps.map((step, index) => `${index + 1}. ${step}`);
@@ -47,24 +47,12 @@ export function buildEntrypointLines(action: string, intent: string): string[] {
 export function buildHelpLines(): string[] {
   return [
     'dev-loops help',
-    'Workflow entry:',
-    '- /skill:dev-loop — single public entrypoint; routing handles the rest',
-    'Direct entrypoints:',
-    '- /dev-loops start <issue>',
-    '- /dev-loops auto <issue>',
-    '- /dev-loops continue [issue|pr]',
-    '- /dev-loops start-spike <question>',
-    '- /dev-loops info <issue|pr>',
-    'Commands:',
-    '- /dev-loops status',
-    '- /dev-loops doctor',
-    '- /dev-loops hide',
-    '- /dev-loops inspect open [--repo <owner/name>]',
-    '- /dev-loops inspect resume [--repo <owner/name>]',
-    '- /dev-loops inspect status [--repo <owner/name>]',
-    '- /dev-loops inspect stop [--repo <owner/name>]',
-    '- /dev-loops inspect restart [--repo <owner/name>]',
-    'Use `pi install git:github.com/mfittko/dev-loops` to install skills and agents; packaged agents sync into `~/.agents/` on session start.',
+    '/skill:dev-loop <intent> starts the public loop',
+    '/dev-loops start <issue> | /dev-loops auto <issue>',
+    '/dev-loops continue [issue|pr] | /dev-loops info <issue|pr>',
+    '/dev-loops start-spike <question>',
+    '/dev-loops inspect open|resume|status|stop|restart',
+    '/dev-loops status | /dev-loops doctor | /dev-loops hide',
   ];
 }
 

package/package.json

@@ -24,15 +24,15 @@
     "verify": "npm test && npm run test:dev-loop",
     "test": "npm run test:assets && npm run test:extension && npm run test:scripts && npm run test:core && npm run test:docs",
     "test:assets": "node --test --test-reporter ./test/failure-summary-reporter.mjs test/dev-loop-init-phase-smoke.test.mjs test/contracts/*.test.mjs test/workflow-handoff-contract.test.mjs",
-    "test:extension": "node --import tsx --test --test-reporter ./test/failure-summary-reporter.mjs test/extension-checks.test.mjs test/extension-post-merge-update.test.mjs test/extension-command-contract.test.mjs test/extension-package-contract.test.mjs test/extension-pi-adapter.test.mjs test/extension-claude-adapter.test.mjs test/dev-loops-core.test.mjs test/dev-loops-cli.test.mjs",
-    "test:scripts": "node --test --test-reporter ./test/failure-summary-reporter.mjs test/github/*.test.mjs test/loop/*.test.mjs test/docs/*.test.mjs test/projects/*.test.mjs test/pages/*.test.mjs",
+    "test:extension": "node --import tsx --test --test-reporter ./test/failure-summary-reporter.mjs test/extension-checks.test.mjs test/extension-post-merge-update.test.mjs test/extension-command-contract.test.mjs test/extension-package-contract.test.mjs test/extension-pi-adapter.test.mjs test/dev-loops-core.test.mjs test/dev-loops-cli.test.mjs",
+    "test:scripts": "GIT_CONFIG_COUNT=2 GIT_CONFIG_KEY_0=core.fsync GIT_CONFIG_VALUE_0=none GIT_CONFIG_KEY_1=core.fsyncObjectFiles GIT_CONFIG_VALUE_1=false node --test --test-reporter ./test/failure-summary-reporter.mjs test/github/*.test.mjs test/loop/*.test.mjs test/docs/*.test.mjs test/projects/*.test.mjs test/pages/*.test.mjs",
     "test:core": "node --test --test-reporter ./test/failure-summary-reporter.mjs packages/core/test/*.test.mjs",
     "test:dev-loop": "node --test --test-reporter ./test/failure-summary-reporter.mjs skills/dev-loop/scripts/dev-mode-context.test.mjs skills/dev-loop/scripts/render-template.test.mjs skills/dev-loop/scripts/post-gate-verdict-fallback.test.mjs",
-    "test:playwright:viewer": "playwright test -c playwright.inspect-run-viewer.config.mjs",
-    "test:playwright:deep-dive": "playwright test -c playwright.dev-loops-deep-dive.config.mjs",
-    "test:playwright:intro-deck": "playwright test -c playwright.intro-deck.config.mjs",
-    "test:playwright:intro-article": "playwright test -c playwright.intro-article.config.mjs",
-    "test:playwright:deep-dive-article": "playwright test -c playwright.deep-dive-article.config.mjs",
+    "test:playwright:viewer": "PW_UI_SLICE=inspect-run-viewer playwright test --project=inspect-run-viewer",
+    "test:playwright:deep-dive": "PW_UI_SLICE=deep-dive-deck playwright test --project=deep-dive-deck",
+    "test:playwright:intro-deck": "PW_UI_SLICE=intro-deck playwright test --project=intro-deck",
+    "test:playwright:intro-article": "PW_UI_SLICE=intro-article playwright test --project=intro-article",
+    "test:playwright:deep-dive-article": "PW_UI_SLICE=deep-dive-article playwright test --project=deep-dive-article",
     "smoke:headless": "node scripts/claude/headless-info-smoke.mjs",
     "test:docs": "node scripts/docs/validate-links.mjs && node scripts/docs/validate-no-duplicate-rules.mjs",
     "repo-wiki": "node scripts/repo-wiki.mjs",
@@ -71,8 +71,7 @@
     ]
   },
   "dependencies": {
-    "mermaid": "11.15.0",
-    "@dev-loops/core": "^0.6.0"
+    "@dev-loops/core": "^0.7.1"
   },
   "repository": {
     "type": "git",
@@ -82,7 +81,7 @@
     "url": "https://github.com/mfittko/dev-loops/issues"
   },
   "homepage": "https://github.com/mfittko/dev-loops#readme",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "files": [
     "cli/",
     "lib/",

package/scripts/github/capture-review-threads.mjs

@@ -11,7 +11,7 @@ import {
 import { parseArgs } from "node:util";
 import { parsePrNumber, requireTokenValue, runChild } from "../_cli-primitives.mjs";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
-import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult } from "../lib/jq-output.mjs";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
 export const REVIEW_THREADS_QUERY = [
   "query($owner: String!, $name: String!, $pr: Int!) {",
   "  repository(owner: $owner, name: $name) {",
@@ -103,14 +103,7 @@ export function parseCaptureCliArgs(argv) {
       options.pr = parsePrNumber(requireTokenValue(token));
       continue;
     }
-    if (token.name === "jq") {
-      options.jq = requireTokenValue(token);
-      continue;
-    }
-    if (token.name === "silent") {
-      options.silent = true;
-      continue;
-    }
+    if (matchJqOutputToken(token, options, (t) => requireTokenValue(t))) continue;
     throw new Error(`Unknown argument: ${token.rawName}`);
   }
   const hasLiveArgs = options.repo !== undefined || options.pr !== undefined;

package/scripts/github/comment-issue.mjs

@@ -4,7 +4,7 @@ import { buildParseError, formatCliError, isDirectCliRun } from "../_core-helper
 import { parseIssueNumber, requireTokenValue, runChild } from "../_cli-primitives.mjs";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
 import { parseArgs } from "node:util";
-import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult } from "../lib/jq-output.mjs";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
 
 const USAGE = `Usage: comment-issue.mjs --repo <owner/name> --issue <number> (--body <text> | --body-file <path>)
 Post a comment on a GitHub issue. Thin wrapper over \`gh issue comment\` — use this
@@ -82,14 +82,7 @@ export function parseCommentIssueCliArgs(argv) {
       options.bodyFile = rawPath;
       continue;
     }
-    if (token.name === "jq") {
-      options.jq = requireTokenValue(token, parseError);
-      continue;
-    }
-    if (token.name === "silent") {
-      options.silent = true;
-      continue;
-    }
+    if (matchJqOutputToken(token, options, (t) => requireTokenValue(t, parseError))) continue;
     throw parseError(`Unknown argument: ${token.rawName}`);
   }
   if (options.repo === undefined || options.issue === undefined) {

package/scripts/github/create-label.mjs

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+import { execFileSync } from "node:child_process";
+import { parseArgs } from "node:util";
+import { buildParseError, formatCliError, isDirectCliRun } from "../_core-helpers.mjs";
+import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult } from "../lib/jq-output.mjs";
+
+const USAGE = `Usage: create-label.mjs --repo <owner/name> --name <label> [--color <hex>] [--description <text>] [--force]
+Create (or idempotently reuse) a GitHub label. Thin wrapper over \`gh label create\`
+— use this instead of an agent-level raw \`gh label create\` so the loop's
+internal-tooling record stays clean (siblings: comment-issue.mjs, edit-pr.mjs).
+Required:
+  --repo <owner/name>           Repository slug (e.g. owner/repo)
+  --name <label>                Label name to create
+Optional:
+  --color <hex>                 Hex color without '#' (default: d73a4a)
+  --description <text>          Label description
+  --force                       Update the label if it already exists
+Output (stdout, JSON):
+  { "ok": true, "created": true, "name": "gate:full", "color": "d73a4a", "repo": "owner/repo" }
+  { "ok": true, "created": false, "alreadyExists": true, "name": "gate:full" }
+Error output (stderr, JSON):
+  { "ok": false, "error": "...", "usage"?: "..." }
+${JQ_OUTPUT_USAGE}
+Exit codes:
+  0  Success (created or already exists)
+  1  Argument error or gh failure
+  2  Invalid --jq filter`.trim();
+const parseError = buildParseError(USAGE);
+
+export function parseCreateLabelCliArgs(argv) {
+  const { values } = parseArgs({
+    args: [...argv],
+    options: {
+      help: { type: "boolean", short: "h" },
+      repo: { type: "string" },
+      name: { type: "string" },
+      color: { type: "string" },
+      description: { type: "string" },
+      force: { type: "boolean" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
+    },
+    allowPositionals: false,
+    strict: false,
+  });
+  if (values.help) {
+    return { help: true };
+  }
+  const repo = typeof values.repo === "string" ? values.repo.trim() : undefined;
+  const name = typeof values.name === "string" ? values.name.trim() : undefined;
+  if (!repo || !name) {
+    throw parseError("Creating a label requires both --repo <owner/name> and --name <label>");
+  }
+  try {
+    parseRepoSlug(repo);
+  } catch (error) {
+    throw parseError(error instanceof Error ? error.message : String(error));
+  }
+  const color = typeof values.color === "string" && values.color.trim().length > 0 ? values.color.trim() : "d73a4a";
+  const description =
+    typeof values.description === "string" && values.description.length > 0 ? values.description : undefined;
+  return {
+    help: false,
+    repo,
+    name,
+    color,
+    description,
+    force: values.force === true,
+    jq: values.jq,
+    silent: values.silent === true,
+  };
+}
+
+// Pure: assemble the `gh label create` argv. Exported so the arg shape can be
+// tested without spawning gh.
+export function buildLabelArgs({ repo, name, color, description, force }) {
+  const args = ["label", "create", name, "--repo", repo, "--color", color];
+  if (description !== undefined) {
+    args.push("--description", description);
+  }
+  if (force) {
+    args.push("--force");
+  }
+  return args;
+}
+
+export function createLabel(options, { ghCommand = "gh", exec = execFileSync } = {}) {
+  const args = buildLabelArgs(options);
+  try {
+    exec(ghCommand, args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+  } catch (error) {
+    const stderr = typeof error?.stderr === "string" ? error.stderr : String(error?.stderr ?? "");
+    // Without --force, gh errors if the label exists. Treat that as idempotent
+    // success so re-runs are safe; any other failure propagates.
+    if (!options.force && /already exists/i.test(stderr)) {
+      return { ok: true, created: false, alreadyExists: true, name: options.name };
+    }
+    const detail = stderr.trim() || (error instanceof Error ? error.message : String(error));
+    throw new Error(`gh label create failed: ${detail}`);
+  }
+  return { ok: true, created: true, name: options.name, color: options.color, repo: options.repo };
+}
+
+export function run(
+  argv = process.argv.slice(2),
+  { stdout = process.stdout, stderr = process.stderr, ghCommand = "gh", exec = execFileSync } = {},
+) {
+  let options;
+  try {
+    options = parseCreateLabelCliArgs(argv);
+  } catch (error) {
+    stderr.write(`${formatCliError(error)}\n`);
+    return 1;
+  }
+  if (options.help) {
+    stdout.write(`${USAGE}\n`);
+    return 0;
+  }
+  let result;
+  try {
+    result = createLabel(options, { ghCommand, exec });
+  } catch (error) {
+    stderr.write(`${JSON.stringify({ ok: false, error: error instanceof Error ? error.message : String(error) })}\n`);
+    return 1;
+  }
+  return emitResult(result, { jq: options.jq, silent: options.silent, stdout, stderr });
+}
+
+export const main = run;
+
+if (isDirectCliRun(import.meta.url)) {
+  process.exitCode = run();
+}