dev-loops 0.2.6 → 0.2.7

package/scripts/projects/reorder-queue-item.mjs

@@ -2,20 +2,35 @@
 import { formatCliError, isDirectCliRun, parseJsonText } from "../_core-helpers.mjs";
 import { runChild as _runChild } from "../_cli-primitives.mjs";
 
-const USAGE = `Usage: dev-loops project reorder --repo <owner/name> --project <number|id> --item <number|node-id> [--after <number|node-id>]
+const USAGE = `Usage:
+  dev-loops project reorder --repo <owner/name> --project <number|id> --item <number|node-id> [--after <number|node-id>]
+  dev-loops project reorder move-to-top <ref> --repo <owner/name> --project <number|id>
+  dev-loops project reorder move-after <ref> <after-ref> --repo <owner/name> --project <number|id>
+  dev-loops project reorder order <ref1> <ref2> ... --repo <owner/name> --project <number|id>
 
-Reorder a GitHub Projects V2 item by board position via updateProjectV2ItemPosition.
-Moves item to top when no --after is provided, or after the specified item.
+Reorder GitHub Projects V2 items by board position via updateProjectV2ItemPosition.
+
+Forms:
+  (no subcommand)   Flag form. Moves --item to top, or after --after when provided.
+  move-to-top <ref> Move <ref> to the first position in its current Status column.
+  move-after <ref> <after-ref>
+                    Move <ref> immediately after <after-ref>.
+  order <ref1> ...  Set explicit ordering: ref1 first, ref2 after ref1, and so on.
+
+A <ref> is an issue/PR number OR a project item node ID. Works for both issues and PRs.
 
 Options:
   --repo <owner/name>         Required. Repository to scope the project search.
   --project <number|id>       Required. Project number (integer) or node ID.
-  --item <number|node-id>     Required. Item to reorder: issue/PR number, or project item node ID.
-  --after <number|node-id>    Position after this item. When omitted, move to top.
+  --item <number|node-id>     Flag form: item to reorder.
+  --after <number|node-id>    Flag form: position after this item. When omitted, move to top.
+  --dry-run                   Print the intended GraphQL mutation(s) without executing.
   --help, -h                  Show this help.
 
 Output (stdout):
-  JSON: { ok: true, item: { itemId, issueNumber, prNumber, status, position }, after: { itemId, issueNumber, prNumber } | null }
+  JSON. Move/move-to-top: { ok, item, after_ref|null, before, after }.
+        order: { ok, moves: [...], before, after }.
+        dry-run: { ok, dryRun: true, mutations: [{ query, variables }], before }.
 
 Exit codes:
   0 — success
@@ -24,13 +39,27 @@ Exit codes:
   3 — project, item, or after-item not found
 `.trim();
 
-const VALID_ARGS = new Set(["--repo", "--project", "--item", "--after", "--help", "-h"]);
+const SUBCOMMANDS = new Set(["move-to-top", "move-after", "order"]);
+const VALID_ARGS = new Set(["--repo", "--project", "--item", "--after", "--dry-run", "--help", "-h"]);
 
 function parseArgs(argv) {
-  const args = {};
-  for (let i = 0; i < argv.length; i++) {
+  const args = { _positional: [] };
+  let i = 0;
+
+  // Optional leading positional subcommand.
+  if (argv.length > 0 && SUBCOMMANDS.has(argv[0])) {
+    args._subcommand = argv[0];
+    i = 1;
+  }
+
+  for (; i < argv.length; i++) {
     const arg = argv[i];
-    if (!VALID_ARGS.has(arg) && arg.startsWith("-")) {
+    if (!arg.startsWith("-")) {
+      // Positional ref (only meaningful with a subcommand).
+      args._positional.push(arg);
+      continue;
+    }
+    if (!VALID_ARGS.has(arg)) {
       throw Object.assign(
         new Error(`Unknown flag: ${arg}`),
         { code: "INVALID_ARGS", usage: USAGE },
@@ -56,6 +85,8 @@ function parseArgs(argv) {
         throw Object.assign(new Error("--after requires a value (number or node ID)"), { code: "INVALID_AFTER" });
       }
       args.after = argv[++i];
+    } else if (arg === "--dry-run") {
+      args.dryRun = true;
     } else if (arg === "--help" || arg === "-h") {
       args.help = true;
     } else {
@@ -296,6 +327,94 @@ async function listAllProjects(login, kind, env, runChild) {
   return projects;
 }
 
+// ── Fetch all project items (paginated, position order) ────────────────
+
+async function fetchAllItems(projectId, env, runChild) {
+  const allItems = [];
+  let after = null;
+  while (true) {
+    const vars = { projectId };
+    if (after) vars.after = after;
+    const itemsPayload = await ghGraphql(GET_PROJECT_ITEMS_BY_CONTENT, vars, env, runChild);
+    const connection = itemsPayload?.data?.node?.items;
+    const nodes = connection?.nodes ?? [];
+    allItems.push(...nodes);
+    const pageInfo = connection?.pageInfo ?? {};
+    if (!pageInfo.hasNextPage) break;
+    if (!pageInfo.endCursor) {
+      throw Object.assign(
+        new Error("Invalid items payload: hasNextPage is true but endCursor is missing"),
+        { code: "GH_API_ERROR" },
+      );
+    }
+    after = pageInfo.endCursor;
+  }
+  return allItems;
+}
+
+function statusOf(node) {
+  const fvs = node?.fieldValues?.nodes ?? [];
+  for (const fv of fvs) {
+    if (fv && fv.field && fv.field.name === "Status") return fv.name;
+  }
+  return null;
+}
+
+function describeItem(node) {
+  return {
+    itemId: node.id,
+    issueNumber: node.content?.__typename === "Issue" ? node.content.number : null,
+    prNumber: node.content?.__typename === "PullRequest" ? node.content.number : null,
+    status: statusOf(node),
+  };
+}
+
+// Build a diff-friendly snapshot of items in `repo` (optionally a single Status
+// column), in board position order, from a pre-fetched item list.
+function snapshotFromItems(items, repo, statusFilter) {
+  return items
+    .filter((it) => it.content && it.content.repository?.nameWithOwner === repo)
+    .filter((it) => (statusFilter == null ? true : statusOf(it) === statusFilter))
+    .map(describeItem);
+}
+
+async function snapshotOrder(projectId, repo, statusFilter, env, runChild) {
+  const items = await fetchAllItems(projectId, env, runChild);
+  return snapshotFromItems(items, repo, statusFilter);
+}
+
+// Resolve a ref (number or item node ID) against a pre-fetched item list,
+// enforcing the same repo scope for BOTH number and id refs so a cross-project
+// ref fails closed with ITEM_NOT_FOUND.
+function resolveFromItems(items, itemRef, repo) {
+  let match;
+  if (itemRef.kind === "id") {
+    match = items.find(
+      (it) => it.id === itemRef.value && it.content?.repository?.nameWithOwner === repo,
+    );
+    if (!match) {
+      throw Object.assign(
+        new Error(`Item "${itemRef.value}" not found in project for repo "${repo}"`),
+        { code: "ITEM_NOT_FOUND" },
+      );
+    }
+  } else {
+    match = items.find(
+      (it) =>
+        it.content &&
+        it.content.repository?.nameWithOwner === repo &&
+        it.content.number === itemRef.value,
+    );
+    if (!match) {
+      throw Object.assign(
+        new Error(`Item #${itemRef.value} not found in project for repo "${repo}"`),
+        { code: "ITEM_NOT_FOUND" },
+      );
+    }
+  }
+  return describeItem(match);
+}
+
 // ── Resolve an item in a project by reference (number or node ID) ──────
 
 async function resolveProjectItem(projectId, itemRef, owner, repoName, repo, env, runChild) {
@@ -335,25 +454,7 @@ async function resolveProjectItem(projectId, itemRef, owner, repoName, repo, env
   } else {
     // Look up by issue/PR number in the project (paginated)
     const targetNumber = itemRef.value;
-    let allItems = [];
-    let after = null;
-    while (true) {
-      const vars = { projectId };
-      if (after) vars.after = after;
-      const itemsPayload = await ghGraphql(GET_PROJECT_ITEMS_BY_CONTENT, vars, env, runChild);
-      const connection = itemsPayload?.data?.node?.items;
-      const nodes = connection?.nodes ?? [];
-      allItems.push(...nodes);
-      const pageInfo = connection?.pageInfo ?? {};
-      if (!pageInfo.hasNextPage) break;
-      if (!pageInfo.endCursor) {
-        throw Object.assign(
-          new Error("Invalid items payload: hasNextPage is true but endCursor is missing"),
-          { code: "GH_API_ERROR" },
-        );
-      }
-      after = pageInfo.endCursor;
-    }
+    const allItems = await fetchAllItems(projectId, env, runChild);
 
     // Filter by matching repo AND number exactly
     const matchingItems = allItems.filter((it) => {
@@ -400,70 +501,68 @@ function classifyExitCode(err) {
   return 2;
 }
 
-// ── Main logic ──────────────────────────────────────────────────────────
-
-async function main(args, { env = process.env, runChild } = {}) {
-  const child = runChild ?? _runChild;
-  const repo = validateRepo(args.repo);
-  const [owner, repoName] = repo.split("/");
-  const projectRef = parseProjectRef(args.project);
-  const itemRef = parseItemRef(args.item);
-
-  // --after is optional
-  let afterRef = null;
-  if (args.after !== undefined) {
-    afterRef = parseItemRef(args.after);
-  }
-
-  // 1. Resolve owner
-  const { id: ownerId, kind: ownerKind } = await resolveOwner(owner, env, child);
+// ── Resolve owner + project (shared) ──────────────────────────────────────
 
-  // 2. Resolve project
+async function resolveProject(owner, projectRef, env, child) {
+  const { kind: ownerKind } = await resolveOwner(owner, env, child);
   const projects = await listAllProjects(owner, ownerKind, env, child);
-  let project;
-  if (projectRef.kind === "id") {
-    project = projects.find((p) => p.id === projectRef.value);
-  } else {
-    project = projects.find((p) => p.number === projectRef.value);
-  }
+  const project = projectRef.kind === "id"
+    ? projects.find((p) => p.id === projectRef.value)
+    : projects.find((p) => p.number === projectRef.value);
   if (!project) {
     throw Object.assign(
       new Error(`Project ${projectRef.kind === "id" ? `"${projectRef.value}"` : `number ${projectRef.value}`} not found under owner "${owner}"`),
       { code: "PROJECT_NOT_FOUND" },
     );
   }
+  return project;
+}
+
+function executePosition(projectId, itemId, afterId) {
+  return {
+    query: UPDATE_ITEM_POSITION,
+    variables: afterId
+      ? { projectId, itemId, afterId }
+      : { projectId, itemId },
+  };
+}
+
+// ── Legacy flag form: --item [--after] ────────────────────────────────────
+
+async function mainFlagForm(args, { env, child, repo, owner, repoName, project }) {
+  const itemRef = parseItemRef(args.item);
+  let afterRef = null;
+  if (args.after !== undefined) afterRef = parseItemRef(args.after);
 
-  // 3. Resolve the item to move
   const item = await resolveProjectItem(project.id, itemRef, owner, repoName, repo, env, child);
 
-  // 4. Resolve the after-item (if provided)
   let afterItem = null;
   if (afterRef) {
     afterItem = await resolveProjectItem(project.id, afterRef, owner, repoName, repo, env, child);
-
-    // Fail closed: cannot reorder after itself
     if (afterItem.itemId === item.itemId) {
-      throw Object.assign(
-        new Error("Cannot reorder an item after itself"),
-        { code: "INVALID_AFTER" },
-      );
+      throw Object.assign(new Error("Cannot reorder an item after itself"), { code: "INVALID_AFTER" });
     }
   }
 
-  // 5. Execute reorder mutation
-  const mutationVars = {
-    projectId: project.id,
-    itemId: item.itemId,
-    afterId: afterItem ? afterItem.itemId : null,
-  };
-
-  const mutationPayload = await ghGraphql(UPDATE_ITEM_POSITION, mutationVars, env, child);
+  const mutation = executePosition(project.id, item.itemId, afterItem ? afterItem.itemId : null);
+
+  if (args.dryRun) {
+    // Include the before snapshot for parity with the subcommand dry-run form.
+    const before = await snapshotOrder(project.id, repo, item.status ?? null, env, child);
+    return {
+      ok: true,
+      dryRun: true,
+      mutations: [mutation],
+      before,
+    };
+  }
 
+  const mutationPayload = await ghGraphql(mutation.query, mutation.variables, env, child);
   if (!mutationPayload?.data?.updateProjectV2ItemPosition) {
     throw Object.assign(new Error("Failed to reorder item"), { code: "MUTATION_FAILED" });
   }
 
-  const result = {
+  return {
     ok: true,
     item: {
       itemId: item.itemId,
@@ -473,15 +572,174 @@ async function main(args, { env = process.env, runChild } = {}) {
       position: afterItem ? "after" : "top",
     },
     after: afterItem
-      ? {
-          itemId: afterItem.itemId,
-          issueNumber: afterItem.issueNumber,
-          prNumber: afterItem.prNumber,
-        }
+      ? { itemId: afterItem.itemId, issueNumber: afterItem.issueNumber, prNumber: afterItem.prNumber }
+      : null,
+  };
+}
+
+// ── Subcommand forms: move-to-top / move-after / order ────────────────────
+
+function requirePositionals(subcommand, positional) {
+  if (subcommand === "move-to-top") {
+    if (positional.length !== 1) {
+      throw Object.assign(new Error("move-to-top requires exactly one <ref>"), { code: "INVALID_ARGS", usage: USAGE });
+    }
+  } else if (subcommand === "move-after") {
+    if (positional.length !== 2) {
+      throw Object.assign(new Error("move-after requires <ref> <after-ref>"), { code: "INVALID_ARGS", usage: USAGE });
+    }
+  } else if (subcommand === "order") {
+    if (positional.length < 2) {
+      throw Object.assign(new Error("order requires at least two <ref> values"), { code: "INVALID_ARGS", usage: USAGE });
+    }
+  }
+}
+
+async function mainSubcommand(args, { env, child, repo, project }) {
+  const subcommand = args._subcommand;
+  const positional = args._positional ?? [];
+  requirePositionals(subcommand, positional);
+
+  // Fetch the board item list ONCE, then resolve every ref (number or id) from
+  // that single list — avoids N full-board scans for N refs and enforces the
+  // same repo scope for both ref kinds (cross-project refs fail closed).
+  const items = await fetchAllItems(project.id, env, child);
+
+  // Resolve all referenced items up-front (fail closed before any mutation).
+  const refs = positional.map((p) => parseItemRef(p));
+  const resolved = refs.map((ref) => resolveFromItems(items, ref, repo));
+
+  // Reordering positions within a single Status column. The before/after snapshot is scoped
+  // to one column, and a cross-column move plan is misleading/invalid — so fail closed unless
+  // every resolved ref shares the first ref's Status (multi-ref subcommands only).
+  if (resolved.length > 1) {
+    const primaryStatus = resolved[0].status ?? null;
+    const offender = resolved.find((it) => (it.status ?? null) !== primaryStatus);
+    if (offender) {
+      throw Object.assign(
+        new Error(
+          `All reordered items must be in the same Status column as the first item (${primaryStatus ?? "(none)"}); ` +
+            `${offender.itemId} is in ${offender.status ?? "(none)"}.`,
+        ),
+        { code: "MIXED_STATUS" },
+      );
+    }
+  }
+
+  // Build the ordered list of position moves, each { item, afterItem|null }.
+  let plan;
+  if (subcommand === "move-to-top") {
+    plan = [{ item: resolved[0], afterItem: null }];
+  } else if (subcommand === "move-after") {
+    const [item, afterItem] = resolved;
+    if (item.itemId === afterItem.itemId) {
+      throw Object.assign(new Error("Cannot reorder an item after itself"), { code: "INVALID_AFTER" });
+    }
+    plan = [{ item, afterItem }];
+  } else {
+    // order: ref1 to top, then each subsequent ref after its predecessor.
+    plan = resolved.map((item, idx) => ({
+      item,
+      afterItem: idx === 0 ? null : resolved[idx - 1],
+    }));
+  }
+
+  const mutations = plan.map((m) => executePosition(project.id, m.item.itemId, m.afterItem ? m.afterItem.itemId : null));
+
+  // Status column for the diff snapshot: use the primary moved item's status.
+  // Reuse the already-fetched list for the before-snapshot (no extra fetch).
+  const statusFilter = resolved[0].status ?? null;
+  const before = snapshotFromItems(items, repo, statusFilter);
+
+  if (args.dryRun) {
+    return { ok: true, dryRun: true, mutations, before };
+  }
+
+  // NOTE: `order` applies N sequential position mutations and is NOT atomic. A
+  // mid-sequence failure leaves the board partially reordered; re-running the
+  // same `order` command is idempotent and is the supported recovery path. The
+  // thrown error reports how many moves were applied before failing.
+  for (let i = 0; i < mutations.length; i++) {
+    const mutation = mutations[i];
+    let payload;
+    try {
+      payload = await ghGraphql(mutation.query, mutation.variables, env, child);
+    } catch (err) {
+      if (subcommand === "order") {
+        err.message = `${err.message} (order partially applied: ${i} of ${mutations.length} moves completed; re-run the same order command to recover)`;
+        err.appliedMoves = i;
+        err.totalMoves = mutations.length;
+      }
+      throw err;
+    }
+    if (!payload?.data?.updateProjectV2ItemPosition) {
+      const detail = subcommand === "order"
+        ? ` (order partially applied: ${i} of ${mutations.length} moves completed; re-run the same order command to recover)`
+        : "";
+      throw Object.assign(new Error(`Failed to reorder item${detail}`), {
+        code: "MUTATION_FAILED",
+        ...(subcommand === "order" ? { appliedMoves: i, totalMoves: mutations.length } : {}),
+      });
+    }
+  }
+
+  const after = await snapshotOrder(project.id, repo, statusFilter, env, child);
+
+  const moves = plan.map((m) => ({
+    itemId: m.item.itemId,
+    issueNumber: m.item.issueNumber,
+    prNumber: m.item.prNumber,
+    status: m.item.status,
+    position: m.afterItem ? "after" : "top",
+    afterId: m.afterItem ? m.afterItem.itemId : null,
+  }));
+
+  if (subcommand === "order") {
+    return { ok: true, moves, before, after };
+  }
+
+  // move-to-top / move-after: single move, richer shape.
+  const m = plan[0];
+  return {
+    ok: true,
+    item: {
+      itemId: m.item.itemId,
+      issueNumber: m.item.issueNumber,
+      prNumber: m.item.prNumber,
+      status: m.item.status,
+      position: m.afterItem ? "after" : "top",
+    },
+    after_ref: m.afterItem
+      ? { itemId: m.afterItem.itemId, issueNumber: m.afterItem.issueNumber, prNumber: m.afterItem.prNumber }
       : null,
+    before,
+    after,
   };
+}
+
+// ── Main logic ──────────────────────────────────────────────────────────
+
+async function main(args, { env = process.env, runChild } = {}) {
+  const child = runChild ?? _runChild;
+  const repo = validateRepo(args.repo);
+  const [owner, repoName] = repo.split("/");
+  const projectRef = parseProjectRef(args.project);
+
+  // Fail closed: the legacy flag form takes no positional arguments. A stray
+  // token (e.g. `reorder 630 --item ...`) must not be silently ignored.
+  if (!args._subcommand && (args._positional?.length ?? 0) > 0) {
+    throw Object.assign(
+      new Error(`Unexpected argument: ${args._positional[0]}`),
+      { code: "INVALID_ARGS", usage: USAGE },
+    );
+  }
 
-  return result;
+  const project = await resolveProject(owner, projectRef, env, child);
+
+  if (args._subcommand) {
+    return mainSubcommand(args, { env, child, repo, project });
+  }
+  return mainFlagForm(args, { env, child, repo, owner, repoName, project });
 }
 
 // ── CLI entrypoint ──────────────────────────────────────────────────────

package/scripts/refine/_refine-helpers.mjs

@@ -2,7 +2,8 @@
 import { readFile } from "node:fs/promises";
 
 import { buildParseError, formatCliError, isDirectCliRun, parseJsonText } from "../_core-helpers.mjs";
-import { parsePositiveInteger, requireOptionValue, runChild } from "../_cli-primitives.mjs";
+import { parseArgs } from "node:util";
+import { parsePositiveInteger, requireTokenValue, runChild } from "../_cli-primitives.mjs";
 import { detectRepoSlug, parseRepoSlug } from "@dev-loops/core/github/repo-slug";
 
 export const FORBIDDEN_PROSE_PATTERNS = [
@@ -23,23 +24,34 @@ export function normalizeIssueNumber(value, label, parseError) {
 
 export function parseCheckerCliArgs(argv, usage, checkerName) {
   const parseError = buildParseError(usage);
-  const args = [...argv];
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: { help: { type: "boolean", short: "h" }, input: { type: "string" }, json: { type: "boolean" } },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
   const options = { help: false, input: undefined, json: false };
-  while (args.length > 0) {
-    const token = args.shift();
-    if (token === "--help" || token === "-h") {
+  for (const token of tokens) {
+    if (token.kind === "positional") {
+      throw parseError(`Unknown argument: ${token.value}`);
+    }
+    if (token.kind !== "option") {
+      continue;
+    }
+    if (token.name === "help") {
       options.help = true;
       return options;
     }
-    if (token === "--input") {
-      options.input = requireOptionValue(args, "--input", parseError, { flagPattern: /^-/u });
+    if (token.name === "input") {
+      options.input = requireTokenValue(token, parseError, { flagPattern: /^-/u });
       continue;
     }
-    if (token === "--json") {
+    if (token.name === "json") {
       options.json = true;
       continue;
     }
-    throw parseError(`Unknown argument: ${token}`);
+    throw parseError(`Unknown argument: ${token.rawName}`);
   }
   if (typeof options.input !== "string" || options.input.trim().length === 0) {
     throw parseError(`${checkerName} requires --input <path>`);

package/scripts/refine/verify.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { buildParseError, formatCliError } from "../_core-helpers.mjs";
-import { parsePositiveInteger, requireOptionValue } from "../_cli-primitives.mjs";
+import { parseArgs } from "node:util";
+import { parsePositiveInteger, requireTokenValue } from "../_cli-primitives.mjs";
 import { detectRepoSlug, parseRepoSlug } from "@dev-loops/core/github/repo-slug";
 
 import { isDirectCliRun, loadTreeFromInput, loadTreeOnline } from "./_refine-helpers.mjs";
@@ -30,7 +31,19 @@ Optional:
 const parseError = buildParseError(USAGE);
 
 export function parseRefineVerifyCliArgs(argv) {
-  const args = [...argv];
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: {
+      help: { type: "boolean", short: "h" },
+      issue: { type: "string" },
+      repo: { type: "string" },
+      input: { type: "string" },
+      json: { type: "boolean" },
+    },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
   const options = {
     help: false,
     issue: undefined,
@@ -39,29 +52,34 @@ export function parseRefineVerifyCliArgs(argv) {
     json: false,
   };
 
-  while (args.length > 0) {
-    const token = args.shift();
-    if (token === "--help" || token === "-h") {
+  for (const token of tokens) {
+    if (token.kind === "positional") {
+      throw parseError(`Unknown argument: ${token.value}`);
+    }
+    if (token.kind !== "option") {
+      continue;
+    }
+    if (token.name === "help") {
       options.help = true;
       return options;
     }
-    if (token === "--issue") {
-      options.issue = parsePositiveInteger(requireOptionValue(args, "--issue", parseError), "Issue number", parseError);
+    if (token.name === "issue") {
+      options.issue = parsePositiveInteger(requireTokenValue(token, parseError), "Issue number", parseError);
       continue;
     }
-    if (token === "--repo") {
-      options.repo = requireOptionValue(args, "--repo", parseError, { flagPattern: /^-/u });
+    if (token.name === "repo") {
+      options.repo = requireTokenValue(token, parseError, { flagPattern: /^-/u });
       continue;
     }
-    if (token === "--input") {
-      options.input = requireOptionValue(args, "--input", parseError, { flagPattern: /^-/u });
+    if (token.name === "input") {
+      options.input = requireTokenValue(token, parseError, { flagPattern: /^-/u });
       continue;
     }
-    if (token === "--json") {
+    if (token.name === "json") {
       options.json = true;
       continue;
     }
-    throw parseError(`Unknown argument: ${token}`);
+    throw parseError(`Unknown argument: ${token.rawName}`);
   }
 
   const hasIssueMode = options.issue !== undefined;

package/skills/dev-loop/SKILL.md

@@ -34,7 +34,11 @@ For async-required routes (config `workflow.asyncStartMode`, default `required`)
 
 > Under the Claude Code harness the dev-loop runs as a single agent: run these steps directly — no read-only boundary and no separate async-subagent dispatch. See [Main Agent Contract](../docs/main-agent-contract.md).
 
-Resolve authoritative state via the startup resolver (`npx dev-loops loop startup --issue <n>` for issues, `npx dev-loops loop startup --pr <n>` for PRs), then immediately build the handoff envelope via `npx dev-loops loop build-envelope --input <resolver-output.json>`. The envelope determines `requiredReads`, `nextAction`, `stopRules`, and `acceptance` — load only those files, execute only that bounded task. It is the first handoff artifact consumed before loading any route pack. See [Workflow Handoff Contract](../docs/workflow-handoff-contract.md) for the derivation contract.
+<!-- pi-only -->
+**CLI invocation (`<dev-loops-package-root>`):** dev-loop CLI commands below are invoked as `node <dev-loops-package-root>/cli/index.mjs <verb...>` using the package-local CLI rather than `npx`, so they resolve unambiguously from the installed package without a global install. Resolve `<dev-loops-package-root>` from this skill's own installed path: this skill is installed at `<package-root>/.pi/skills/dev-loop/SKILL.md`, so the package root is `../../..` from this skill's directory. (The `dev-loop` agent resolves it analogously from its own installed path.)
+<!-- /pi-only -->
+
+Resolve authoritative state via the startup resolver (`node <dev-loops-package-root>/cli/index.mjs loop startup --issue <n>` for issues, `node <dev-loops-package-root>/cli/index.mjs loop startup --pr <n>` for PRs), then immediately build the handoff envelope via `node <dev-loops-package-root>/cli/index.mjs loop build-envelope --input <resolver-output.json>`. The envelope determines `requiredReads`, `nextAction`, `stopRules`, and `acceptance` — load only those files, execute only that bounded task. It is the first handoff artifact consumed before loading any route pack. See [Workflow Handoff Contract](../docs/workflow-handoff-contract.md) for the derivation contract.
 
 **Retrospective checkpoint gate:** the resolver reads `.pi/dev-loop-retrospective-checkpoint.json` and injects the state. When the checkpoint is `missing` and the repo config `workflow.requireRetrospective` (set via `.devloops` at repo root) is `true`, the resolver returns `needs_reconcile`. Complete or explicitly skip the retrospective before starting.
 
@@ -109,10 +113,10 @@ When `@dev-loops/core` is available again, switch back to the full helper. The f
 
 ## Read-only info shortcut
 
-Info/handoff requests can be served directly via `npx dev-loops loop info` (read-only; no full dev-loop run required):
-- `npx dev-loops loop info --issue <n>` — human-readable issue state summary (strategy, route, linked PR, next action)
-- `npx dev-loops loop info --pr <n>` — human-readable PR state summary (branch, CI, threads, rounds, action)
-- `npx dev-loops loop info --issue <n> --json` — machine-readable JSON output
+Info/handoff requests can be served directly via `node <dev-loops-package-root>/cli/index.mjs loop info` (read-only; no full dev-loop run required):
+- `node <dev-loops-package-root>/cli/index.mjs loop info --issue <n>` — human-readable issue state summary (strategy, route, linked PR, next action)
+- `node <dev-loops-package-root>/cli/index.mjs loop info --pr <n>` — human-readable PR state summary (branch, CI, threads, rounds, action)
+- `node <dev-loops-package-root>/cli/index.mjs loop info --issue <n> --json` — machine-readable JSON output
 
 ## Guard rules