@indigoai-us/hq-cli 5.77.13 → 5.78.0

package/src/commands/skill.ts

@@ -1,796 +0,0 @@
-/**
- * `hq skill` subcommand group (US-017).
- *
- * Terminal / scriptable access to the skill collaboration loop:
- *
- *   hq skill suggest <uid|path>   Propose a change to a skill from working edits.
- *   hq skill list-suggestions     Show the review inbox (suggestions on skills you own).
- *   hq skill review <sgn_…>       Accept (merge) or decline a pending suggestion.
- *
- * This is a THIN front-end over the SAME wired hq-pro routes the MCP surface
- * (US-007) and the console merge path (US-009) use — there is NO forked
- * suggestion or merge logic here. The CLI reads the local working SKILL.md,
- * computes the proposed content (+ its base for a diff), and POSTs to:
- *
- *   CREATE  POST /v1/files/skills/company/{slug}/{skillUid}/suggestions
- *   LIST    POST /v1/files/skills/company/{slug}/suggestions/list
- *   ACCEPT  POST /v1/files/skills/company/{slug}/{skillUid}/suggestions/{id}/accept
- *   DECLINE POST /v1/files/skills/company/{slug}/{skillUid}/suggestions/{id}/decline
- *
- * The skill routes are keyed on the company SLUG (path param, resolved
- * server-side via findEntityBySlug) — NOT the companyUid the vault/ACL routes
- * use — so this module resolves a slug (from `--company` or the active company)
- * and passes it straight through.
- *
- * Lock semantics (AC3): a suggest against a skill the caller cannot WRITE still
- * SUCCEEDS as a proposal. The CREATE route is MEMBER-gated (never write-gated),
- * so this command performs NO client-side lock/permission pre-check — it always
- * posts and renders whatever the server returns. A locked-out member lands a
- * suggestion, never a hard permission error.
- *
- * Attribution (AC4): the invoking identity (from the Cognito JWT) is the server-
- * derived `authorPersonUid`; the CLI never sends an author. An optional
- * `--note` rides as `authorNote` (the change's rationale / failure context).
- */
-
-import * as fs from "node:fs";
-import * as path from "node:path";
-import { createHash } from "node:crypto";
-import { Command } from "commander";
-import chalk from "chalk";
-import yaml from "js-yaml";
-import simpleGit from "simple-git";
-import { ensureCognitoToken, DEFAULT_HQ_ROOT } from "../utils/cognito-session.js";
-import { vaultApiFetch } from "../utils/vault-api.js";
-
-// ---------------------------------------------------------------------------
-// Patterns
-// ---------------------------------------------------------------------------
-
-/**
- * A `skl_…` argument to `suggest` is a skill UID (resolve the local file from
- * it); anything else is a filesystem path. Lenient on the suffix (the strict
- * `skl_<ulid>` shape is `isSkillUid` on the server) so a hand-typed / fixture
- * uid still routes to the uid branch.
- */
-export const SKILL_UID_PATTERN = /^skl_[A-Za-z0-9]+$/;
-/** A `sgn_…` suggestion id — the `review` target and the LIST row key. */
-export const SUGGESTION_ID_PATTERN = /^sgn_[A-Za-z0-9]+$/;
-
-const VALID_LIST_STATUSES = ["open", "accepted", "declined", "all"] as const;
-type ListStatus = (typeof VALID_LIST_STATUSES)[number];
-
-// ---------------------------------------------------------------------------
-// Pure helpers (exported for unit tests)
-// ---------------------------------------------------------------------------
-
-const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/;
-
-/**
- * Read the top-level `skill_uid` from a SKILL.md's YAML frontmatter. Mirrors
- * hq-pro's `parseSkillFrontmatter` (block extraction → YAML parse → read the
- * top-level `skill_uid` string). Returns `undefined` when there is no
- * frontmatter, it fails to parse, or `skill_uid` is absent / not a `skl_…`
- * string. Never throws.
- */
-export function parseSkillUid(md: string): string | undefined {
-  const match = md.match(FRONTMATTER_RE);
-  if (!match) return undefined;
-  let doc: unknown;
-  try {
-    doc = yaml.load(match[1]);
-  } catch {
-    return undefined;
-  }
-  if (!doc || typeof doc !== "object" || Array.isArray(doc)) return undefined;
-  const uid = (doc as Record<string, unknown>).skill_uid;
-  return typeof uid === "string" && SKILL_UID_PATTERN.test(uid) ? uid : undefined;
-}
-
-/** sha256 hex of a string — the base-version fingerprint the server records (AC2). */
-export function sha256Hex(content: string): string {
-  return createHash("sha256").update(content, "utf8").digest("hex");
-}
-
-export interface SuggestionCreateBody {
-  proposedContent: string;
-  baseContent?: string;
-  baseContentHash?: string;
-  authorNote?: string;
-}
-
-/**
- * Build the CREATE request body from the resolved proposed content and an
- * optional base. Mirrors the server's two payload shapes:
- *   - `baseContent` present → the server derives the unified diff + base hash
- *     (the diff-by-default path). A no-op (base === proposed) is rejected here
- *     rather than round-tripped to an EmptySuggestion 400.
- *   - no base → a `full-file` proposal; the server REQUIRES a `baseContentHash`,
- *     so we fingerprint the proposed content (a "here is my whole file" proposal
- *     with no base to diff against).
- * An empty / whitespace-only note is dropped (kept absent, not blank).
- */
-export function buildSuggestionCreateBody(input: {
-  proposedContent: string;
-  baseContent?: string;
-  note?: string;
-}): SuggestionCreateBody {
-  const body: SuggestionCreateBody = { proposedContent: input.proposedContent };
-  if (input.baseContent !== undefined) {
-    if (input.baseContent === input.proposedContent) {
-      throw new Error(
-        "No changes to propose — the working SKILL.md matches its base.",
-      );
-    }
-    body.baseContent = input.baseContent;
-  } else {
-    body.baseContentHash = sha256Hex(input.proposedContent);
-  }
-  const note = input.note?.trim();
-  if (note) body.authorNote = note;
-  return body;
-}
-
-/**
- * Map an hq-pro skill route error to a single user-facing line. Pure so the
- * status → copy mapping is unit-tested independently of the network. Prefers the
- * server's own `error` / `message` (they carry the actionable specifics — e.g.
- * "Skill not found", "You need write access to this skill…").
- */
-export function mapSkillError(status: number, body: Record<string, unknown>): string {
-  const server =
-    (typeof body.error === "string" && body.error) ||
-    (typeof body.message === "string" && body.message) ||
-    "";
-  if (status === 401) return "Not authenticated — please run `hq login`";
-  if (status === 403) return server || "Not authorized";
-  if (status === 404) return server || "Not found";
-  if (status === 409) return server || "Conflict — please retry";
-  if (status === 422) return server || "Company vault not provisioned";
-  if (status >= 500) return `Server error: ${server || status}`;
-  return server || `Request failed (${status})`;
-}
-
-/** LIST inbox row shape returned by `suggestionToWire` on the server. */
-export interface SuggestionRow {
-  suggestionId: string;
-  skillUid: string;
-  authorPersonUid: string;
-  status: string;
-  baseChanged: boolean;
-  presentation?: string;
-  unifiedDiff?: string;
-  fullContent?: string;
-  baseContentHash?: string;
-  currentContentHash?: string;
-  authorNote?: string;
-  createdAt: string;
-  path: string;
-}
-
-function shortDate(iso: string): string {
-  return typeof iso === "string" ? iso.slice(0, 10) : "";
-}
-
-/**
- * Render the review inbox as a table (one row per suggestion), optionally
- * printing each suggestion's unified diff (or full proposed file, when the base
- * drifted / the proposal is full-file) beneath its row. Pure → snapshot-testable.
- */
-export function formatSuggestionsList(
-  suggestions: SuggestionRow[],
-  opts: { showDiff?: boolean } = {},
-): string {
-  if (suggestions.length === 0) {
-    return chalk.gray("No suggestions match — the review inbox is empty.");
-  }
-  const idW = Math.max(13, ...suggestions.map((s) => s.suggestionId.length));
-  const skillW = Math.max(8, ...suggestions.map((s) => s.skillUid.length));
-  const authW = Math.max(6, ...suggestions.map((s) => s.authorPersonUid.length));
-  const statusW = Math.max(6, ...suggestions.map((s) => s.status.length));
-
-  const lines: string[] = [];
-  lines.push(
-    chalk.bold(
-      [
-        "SUGGESTION_ID".padEnd(idW),
-        "SKILL".padEnd(skillW),
-        "AUTHOR".padEnd(authW),
-        "STATUS".padEnd(statusW),
-        "BASE",
-        "CREATED",
-      ].join("  "),
-    ),
-  );
-  for (const s of suggestions) {
-    lines.push(
-      [
-        s.suggestionId.padEnd(idW),
-        s.skillUid.padEnd(skillW),
-        s.authorPersonUid.padEnd(authW),
-        s.status.padEnd(statusW),
-        s.baseChanged ? chalk.yellow("changed") : "ok".padEnd(7),
-        shortDate(s.createdAt),
-      ].join("  "),
-    );
-    if (s.authorNote) {
-      lines.push(chalk.dim(`    note: ${s.authorNote}`));
-    }
-    if (opts.showDiff) {
-      const diff =
-        s.presentation === "diff" && s.unifiedDiff
-          ? s.unifiedDiff
-          : (s.fullContent ?? "");
-      const label =
-        s.presentation === "diff" && s.unifiedDiff
-          ? "diff"
-          : `full file${s.baseChanged ? " (base changed)" : ""}`;
-      lines.push(chalk.dim(`    ── ${label} ──`));
-      for (const dl of diff.split("\n")) {
-        lines.push(colorizeDiffLine(`    ${dl}`));
-      }
-    }
-  }
-  return lines.join("\n");
-}
-
-/** Colour a unified-diff line (green add / red del / dim header). Pure. */
-function colorizeDiffLine(line: string): string {
-  const trimmed = line.trimStart();
-  if (trimmed.startsWith("+")) return chalk.green(line);
-  if (trimmed.startsWith("-")) return chalk.red(line);
-  if (trimmed.startsWith("@@")) return chalk.cyan(line);
-  return chalk.dim(line);
-}
-
-// ---------------------------------------------------------------------------
-// Company slug + local skill resolution
-// ---------------------------------------------------------------------------
-
-/** Read `.hq/config.json`'s `activeCompany` (mirrors signals/sources). */
-export function readActiveCompanySlug(hqRoot: string): string | undefined {
-  const configPath = path.join(hqRoot, ".hq", "config.json");
-  if (!fs.existsSync(configPath)) return undefined;
-  try {
-    const cfg = JSON.parse(fs.readFileSync(configPath, "utf-8")) as {
-      activeCompany?: unknown;
-    };
-    return typeof cfg.activeCompany === "string" && cfg.activeCompany.length > 0
-      ? cfg.activeCompany
-      : undefined;
-  } catch {
-    return undefined;
-  }
-}
-
-/**
- * The skill routes are keyed on the company SLUG. Precedence: explicit
- * `--company` → `.hq/config.json` activeCompany. Throws with actionable copy
- * when neither is available.
- */
-export function resolveCompanySlug(
-  flag: string | undefined,
-  hqRoot: string = DEFAULT_HQ_ROOT,
-): string {
-  const slug = flag ?? readActiveCompanySlug(hqRoot);
-  if (!slug) {
-    throw new Error(
-      "No company specified. Pass --company <slug> (or set an active company in .hq/config.json).",
-    );
-  }
-  return slug;
-}
-
-export interface ResolvedSkillTarget {
-  /** Absolute path to the SKILL.md. */
-  filePath: string;
-  /** The `skl_…` uid read from its frontmatter (or the uid arg). */
-  skillUid: string;
-  /** The working-tree SKILL.md content — the proposed content. */
-  content: string;
-}
-
-/**
- * Recursively find a SKILL.md whose frontmatter `skill_uid` equals `uid`,
- * searching each root breadth-first with a bounded depth (skips VCS / build /
- * dependency dirs). Returns the first match's absolute path, or null.
- */
-export function findSkillFileByUid(
-  roots: string[],
-  uid: string,
-  maxDepth = 6,
-): string | null {
-  const SKIP = new Set([
-    "node_modules",
-    ".git",
-    "dist",
-    "build",
-    ".next",
-    "coverage",
-  ]);
-  const queue: Array<{ dir: string; depth: number }> = [];
-  for (const r of roots) {
-    if (fs.existsSync(r)) queue.push({ dir: r, depth: 0 });
-  }
-  while (queue.length > 0) {
-    const { dir, depth } = queue.shift()!;
-    let entries: fs.Dirent[];
-    try {
-      entries = fs.readdirSync(dir, { withFileTypes: true });
-    } catch {
-      continue;
-    }
-    for (const entry of entries) {
-      const full = path.join(dir, entry.name);
-      if (entry.isDirectory()) {
-        if (depth < maxDepth && !SKIP.has(entry.name)) {
-          queue.push({ dir: full, depth: depth + 1 });
-        }
-      } else if (entry.isFile() && entry.name === "SKILL.md") {
-        let content: string;
-        try {
-          content = fs.readFileSync(full, "utf-8");
-        } catch {
-          continue;
-        }
-        if (parseSkillUid(content) === uid) return full;
-      }
-    }
-  }
-  return null;
-}
-
-/**
- * Resolve a `suggest` target (a `skl_…` uid OR a filesystem path) to the local
- * SKILL.md, its uid, and its content. A uid is resolved by scanning the company
- * skills dir and the cwd; a path is read directly (a directory → its SKILL.md),
- * with the uid read from the file's frontmatter.
- */
-export function resolveSkillTarget(
-  target: string,
-  deps: { cwd: string; hqRoot: string; companySlug: string },
-): ResolvedSkillTarget {
-  if (SKILL_UID_PATTERN.test(target)) {
-    const roots = Array.from(
-      new Set([
-        path.join(deps.hqRoot, "companies", deps.companySlug, "skills"),
-        deps.cwd,
-      ]),
-    );
-    const filePath = findSkillFileByUid(roots, target);
-    if (!filePath) {
-      throw new Error(
-        `Could not find a local SKILL.md with skill_uid '${target}' under ${roots.join(", ")}. ` +
-          "Pass the path to the edited SKILL.md instead.",
-      );
-    }
-    return { filePath, skillUid: target, content: fs.readFileSync(filePath, "utf-8") };
-  }
-
-  // Filesystem path — accept either a SKILL.md file or a directory containing one.
-  let filePath = path.resolve(deps.cwd, target);
-  if (fs.existsSync(filePath) && fs.statSync(filePath).isDirectory()) {
-    filePath = path.join(filePath, "SKILL.md");
-  }
-  if (!fs.existsSync(filePath)) {
-    throw new Error(
-      `No SKILL.md found at '${target}'. Pass the path to a SKILL.md (or its directory), or a skl_… uid.`,
-    );
-  }
-  const content = fs.readFileSync(filePath, "utf-8");
-  const skillUid = parseSkillUid(content);
-  if (!skillUid) {
-    throw new Error(
-      `The SKILL.md at '${filePath}' has no skill_uid in its frontmatter — it is not registered yet. ` +
-        "Sync / reindex the skill first so it has a stable identity, then suggest against it.",
-    );
-  }
-  return { filePath, skillUid, content };
-}
-
-/**
- * Read the committed (HEAD) version of a file from its git repo — the diff base
- * for "propose my working changes". Returns null when the file is untracked, not
- * in a repo, or git is unavailable (the caller then falls back to full-file, or
- * errors under `--diff`). Never throws.
- */
-export async function readGitBase(filePath: string): Promise<string | null> {
-  try {
-    const git = simpleGit(path.dirname(filePath));
-    const top = (await git.revparse(["--show-toplevel"])).trim();
-    const rel = path.relative(top, filePath);
-    return await git.show([`HEAD:${rel}`]);
-  } catch {
-    return null;
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Network helpers
-// ---------------------------------------------------------------------------
-
-async function readJsonBody(res: Response): Promise<Record<string, unknown>> {
-  return (await res.json().catch(() => ({}))) as Record<string, unknown>;
-}
-
-/** Print the mapped error for a non-2xx response and exit(1). Returns never. */
-async function failFromResponse(res: Response): Promise<never> {
-  const body = await readJsonBody(res);
-  console.error(chalk.red(mapSkillError(res.status, body)));
-  process.exit(1);
-}
-
-function skillRoutePrefix(slug: string): string {
-  return `/v1/files/skills/company/${encodeURIComponent(slug)}`;
-}
-
-/** Injectable git-base seam so `suggest` is testable without a real repo. */
-export type GitBaseReader = (filePath: string) => Promise<string | null>;
-
-// ---------------------------------------------------------------------------
-// Command registration
-// ---------------------------------------------------------------------------
-
-export function registerSkillCommand(
-  program: Command,
-  deps: { gitBase?: GitBaseReader } = {},
-): Command {
-  const gitBase = deps.gitBase ?? readGitBase;
-
-  const skill = program
-    .command("skill")
-    .description("Propose, review, and merge skill changes from the terminal")
-    .option("--company <slug>", "Company slug (defaults to the active company)");
-
-  // ── suggest ────────────────────────────────────────────────────────────────
-  skill
-    .command("suggest <target>")
-    .description(
-      "Create a suggestion from a local SKILL.md (a skl_… uid or a path). Never blocked by a skill lock — a suggestion is always a proposal.",
-    )
-    .option(
-      "--diff",
-      "Require a diff base (git HEAD, or --base): fail if none is found. Default falls back to a full-file proposal.",
-    )
-    .option("--base <file>", "Explicit base file to diff the working SKILL.md against")
-    .option(
-      "--note <text>",
-      "Author note — the rationale / failure context attached to the suggestion",
-    )
-    .action(
-      async (
-        target: string,
-        opts: { diff?: boolean; base?: string; note?: string },
-      ) => {
-        try {
-          const companySlug = resolveCompanySlug(
-            skill.opts().company as string | undefined,
-          );
-          const resolved = resolveSkillTarget(target, {
-            cwd: process.cwd(),
-            hqRoot: DEFAULT_HQ_ROOT,
-            companySlug,
-          });
-
-          // Base resolution: explicit --base wins; otherwise diff against git
-          // HEAD when the file is tracked. No base + --diff → hard error; no
-          // base without --diff → a full-file proposal.
-          let baseContent: string | undefined;
-          let baseSource = "";
-          if (opts.base !== undefined) {
-            const basePath = path.resolve(process.cwd(), opts.base);
-            if (!fs.existsSync(basePath)) {
-              console.error(chalk.red(`Base file not found: ${opts.base}`));
-              process.exit(1);
-            }
-            baseContent = fs.readFileSync(basePath, "utf-8");
-            baseSource = opts.base;
-          } else {
-            const fromGit = await gitBase(resolved.filePath);
-            if (fromGit !== null) {
-              baseContent = fromGit;
-              baseSource = "git HEAD";
-            }
-          }
-
-          if (baseContent === undefined && opts.diff) {
-            console.error(
-              chalk.red(
-                `--diff needs a base, but none was found for ${resolved.filePath}. ` +
-                  "Pass --base <file>, or commit a base version first.",
-              ),
-            );
-            process.exit(1);
-          }
-          if (baseContent !== undefined && baseContent === resolved.content) {
-            console.error(
-              chalk.red(
-                `No changes to propose — the working SKILL.md matches its base (${baseSource}).`,
-              ),
-            );
-            process.exit(1);
-          }
-
-          const body = buildSuggestionCreateBody({
-            proposedContent: resolved.content,
-            baseContent,
-            note: opts.note,
-          });
-
-          const token = await ensureCognitoToken();
-          const res = await vaultApiFetch({
-            token,
-            path: `${skillRoutePrefix(companySlug)}/${encodeURIComponent(resolved.skillUid)}/suggestions`,
-            method: "POST",
-            body: body as unknown as Record<string, unknown>,
-          });
-          if (!res.ok) await failFromResponse(res);
-
-          const data = (await res.json()) as {
-            suggestionId: string;
-            skillUid: string;
-            status: string;
-            authorPersonUid: string;
-            payloadFormat: string;
-            authorNote?: string;
-          };
-
-          console.log(chalk.green(`Suggestion created: ${data.suggestionId}`));
-          console.log(`  Skill:   ${data.skillUid}`);
-          console.log(`  Status:  ${data.status}`);
-          // AC4 — attribution is server-derived from the invoking identity.
-          console.log(`  Author:  ${data.authorPersonUid}`);
-          console.log(
-            `  Change:  ${data.payloadFormat === "diff" ? `diff vs ${baseSource || "base"}` : "full file"}`,
-          );
-          if (data.authorNote) console.log(`  Note:    ${data.authorNote}`);
-          console.log(
-            chalk.dim(
-              `  The skill owner can review it: hq skill review ${data.suggestionId} --accept|--decline`,
-            ),
-          );
-        } catch (err) {
-          console.error(
-            chalk.red("Error:"),
-            err instanceof Error ? err.message : String(err),
-          );
-          process.exit(1);
-        }
-      },
-    );
-
-  // ── list-suggestions ─────────────────────────────────────────────────────────
-  skill
-    .command("list-suggestions")
-    .description(
-      "List the review inbox — open suggestions on skills you own (or one skill via --skill)",
-    )
-    .option("--skill <skillUid>", "Scope to one skill (skl_…); requires write access on it")
-    .option(
-      "--status <status>",
-      "open | accepted | declined | all (default: open)",
-    )
-    .option("--show-diff", "Print each suggestion's unified diff / proposed file")
-    .option("--json", "Emit raw JSON instead of a table")
-    .action(
-      async (opts: {
-        skill?: string;
-        status?: string;
-        showDiff?: boolean;
-        json?: boolean;
-      }) => {
-        try {
-          const companySlug = resolveCompanySlug(
-            skill.opts().company as string | undefined,
-          );
-          const status = (opts.status ?? "open") as ListStatus;
-          if (!VALID_LIST_STATUSES.includes(status)) {
-            console.error(
-              chalk.red(
-                `Invalid --status '${opts.status}': must be one of ${VALID_LIST_STATUSES.join(", ")}`,
-              ),
-            );
-            process.exit(1);
-          }
-          if (opts.skill !== undefined && !SKILL_UID_PATTERN.test(opts.skill)) {
-            console.error(chalk.red(`Invalid --skill '${opts.skill}': must be a skl_… uid`));
-            process.exit(1);
-          }
-
-          const body: Record<string, unknown> = { status };
-          if (opts.skill !== undefined) body.skillUid = opts.skill;
-
-          const token = await ensureCognitoToken();
-          const res = await vaultApiFetch({
-            token,
-            path: `${skillRoutePrefix(companySlug)}/suggestions/list`,
-            method: "POST",
-            body,
-          });
-          if (!res.ok) await failFromResponse(res);
-
-          const data = (await res.json()) as {
-            suggestions: SuggestionRow[];
-            count: number;
-          };
-          if (opts.json) {
-            console.log(JSON.stringify(data, null, 2));
-            return;
-          }
-          console.log(formatSuggestionsList(data.suggestions, { showDiff: opts.showDiff }));
-        } catch (err) {
-          console.error(
-            chalk.red("Error:"),
-            err instanceof Error ? err.message : String(err),
-          );
-          process.exit(1);
-        }
-      },
-    );
-
-  // ── review ─────────────────────────────────────────────────────────────────
-  skill
-    .command("review <suggestionId>")
-    .description("Accept (merge) or decline a pending suggestion")
-    .option("--accept", "Accept the suggestion — merges the proposed change into the skill")
-    .option("--decline", "Decline the suggestion — leaves the skill unchanged")
-    .option("--reason <text>", "Reason recorded on a decline")
-    .option("--skill <skillUid>", "Scope the lookup to one skill (skl_…)")
-    .option(
-      "--acknowledge-base-changed",
-      "On accept: overwrite with the full proposed file even if the skill changed since the suggestion",
-    )
-    .action(
-      async (
-        suggestionId: string,
-        opts: {
-          accept?: boolean;
-          decline?: boolean;
-          reason?: string;
-          skill?: string;
-          acknowledgeBaseChanged?: boolean;
-        },
-      ) => {
-        try {
-          if (!SUGGESTION_ID_PATTERN.test(suggestionId)) {
-            console.error(
-              chalk.red(`Invalid suggestion id '${suggestionId}': must be a sgn_… id`),
-            );
-            process.exit(1);
-          }
-          const accept = opts.accept === true;
-          const decline = opts.decline === true;
-          if (accept === decline) {
-            console.error(
-              chalk.red("Pass exactly one of --accept or --decline."),
-            );
-            process.exit(1);
-          }
-          if (opts.skill !== undefined && !SKILL_UID_PATTERN.test(opts.skill)) {
-            console.error(chalk.red(`Invalid --skill '${opts.skill}': must be a skl_… uid`));
-            process.exit(1);
-          }
-
-          const companySlug = resolveCompanySlug(
-            skill.opts().company as string | undefined,
-          );
-          const token = await ensureCognitoToken();
-
-          // Resolve the suggestion's skillUid + live path from the SAME LIST route
-          // the console uses — accept/decline are path↔uid guarded, so the path
-          // must come from the authoritative row, never guessed. `all` so an
-          // already-resolved suggestion yields a precise "already <status>" error.
-          const listBody: Record<string, unknown> = { status: "all" };
-          if (opts.skill !== undefined) listBody.skillUid = opts.skill;
-          const listRes = await vaultApiFetch({
-            token,
-            path: `${skillRoutePrefix(companySlug)}/suggestions/list`,
-            method: "POST",
-            body: listBody,
-          });
-          if (!listRes.ok) await failFromResponse(listRes);
-          const { suggestions } = (await listRes.json()) as {
-            suggestions: SuggestionRow[];
-          };
-          const row = suggestions.find((s) => s.suggestionId === suggestionId);
-          if (!row) {
-            console.error(
-              chalk.red(
-                `Suggestion ${suggestionId} is not in your review inbox. ` +
-                  "If it targets a skill you don't own, scope the lookup with --skill <skl_…>.",
-              ),
-            );
-            process.exit(1);
-          }
-          if (row.status !== "open") {
-            console.error(
-              chalk.yellow(`Suggestion ${suggestionId} is already ${row.status} — nothing to do.`),
-            );
-            process.exit(1);
-          }
-
-          if (accept) {
-            if (!row.path) {
-              console.error(
-                chalk.red(
-                  "Could not resolve the live skill path for this suggestion — the skill may have been removed.",
-                ),
-              );
-              process.exit(1);
-            }
-            const acceptBody: Record<string, unknown> = { path: row.path };
-            if (opts.acknowledgeBaseChanged) acceptBody.acknowledgeBaseChanged = true;
-            const res = await vaultApiFetch({
-              token,
-              path: `${skillRoutePrefix(companySlug)}/${encodeURIComponent(row.skillUid)}/suggestions/${encodeURIComponent(suggestionId)}/accept`,
-              method: "POST",
-              body: acceptBody,
-            });
-            if (!res.ok) {
-              const errBody = await readJsonBody(res);
-              // AC4 (US-009): the base drifted — guide the operator to re-run
-              // with acknowledgement rather than silently overwriting.
-              if (
-                res.status === 409 &&
-                errBody.code === "WRITE_SKILL_SUGGESTION_BASE_CHANGED"
-              ) {
-                console.error(
-                  chalk.yellow(
-                    "The skill changed since this suggestion was written. Re-run with " +
-                      "--acknowledge-base-changed to overwrite it with the full proposed file.",
-                  ),
-                );
-                process.exit(1);
-              }
-              console.error(chalk.red(mapSkillError(res.status, errBody)));
-              process.exit(1);
-            }
-            const data = (await res.json()) as {
-              skillUid: string;
-              suggestionId: string;
-              acceptedBy: string;
-            };
-            console.log(
-              chalk.green("Suggestion accepted — merged and closed."),
-            );
-            console.log(`  Skill:       ${data.skillUid}`);
-            console.log(`  Suggestion:  ${data.suggestionId}`);
-            console.log(`  Accepted by: ${data.acceptedBy}`);
-            return;
-          }
-
-          // Decline.
-          const declineBody: Record<string, unknown> = {};
-          if (opts.reason !== undefined) declineBody.reason = opts.reason;
-          const res = await vaultApiFetch({
-            token,
-            path: `${skillRoutePrefix(companySlug)}/${encodeURIComponent(row.skillUid)}/suggestions/${encodeURIComponent(suggestionId)}/decline`,
-            method: "POST",
-            body: declineBody,
-          });
-          if (!res.ok) await failFromResponse(res);
-          const data = (await res.json()) as {
-            skillUid: string;
-            suggestionId: string;
-            declinedBy: string;
-            reason?: string;
-          };
-          console.log(
-            chalk.green("Suggestion declined — the skill was left unchanged."),
-          );
-          console.log(`  Skill:       ${data.skillUid}`);
-          console.log(`  Suggestion:  ${data.suggestionId}`);
-          console.log(`  Declined by: ${data.declinedBy}`);
-          if (data.reason) console.log(`  Reason:      ${data.reason}`);
-        } catch (err) {
-          console.error(
-            chalk.red("Error:"),
-            err instanceof Error ? err.message : String(err),
-          );
-          process.exit(1);
-        }
-      },
-    );
-
-  return skill;
-}