dev-loops 0.2.6 → 0.3.0

package/cli/index.mjs

@@ -22,6 +22,7 @@ const SUBCOMMAND_ROUTES = {
     "upsert-verdict":     "scripts/github/upsert-checkpoint-verdict.mjs",
     "detect-evidence":    "scripts/github/detect-checkpoint-evidence.mjs",
     "write-findings-log": "scripts/github/write-gate-findings-log.mjs",
+    "post-findings":      "scripts/github/post-gate-findings.mjs",
     "request-copilot":    "scripts/github/request-copilot-review.mjs",
     "probe-copilot":      "scripts/github/probe-copilot-review.mjs",
     "capture-threads":    "scripts/github/capture-review-threads.mjs",
@@ -43,7 +44,7 @@ const SUBCOMMAND_ROUTES = {
     "debt-remediate":       "scripts/loop/debt-remediate.mjs",
   },
   pr: {
-    "create-draft":     "scripts/github/create-draft-pr.mjs",
+    create:             "scripts/github/create-pr.mjs",
     "ready-for-review": "scripts/github/ready-for-review.mjs",
     "reconcile-draft":  "scripts/github/reconcile-draft-gate.mjs",
   },
@@ -52,6 +53,8 @@ const SUBCOMMAND_ROUTES = {
     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",
   },
   queue: {
@@ -66,6 +69,22 @@ const SUBCOMMAND_ROUTES = {
   },
 };
 
+// Back-compat subcommand aliases: { category: { oldName: { canonical, notice } } }.
+// Aliases keep existing callers working while emitting a one-line deprecation
+// notice to stderr so they migrate to the canonical subcommand.
+const SUBCOMMAND_ALIASES = {
+  pr: {
+    "create-draft": {
+      canonical: "create",
+      notice: "[dev-loops] `pr create-draft` is deprecated; use `pr create` (always draft, self-assigned by default).",
+    },
+  },
+};
+
+function resolveSubcommandAlias(category, subcommand) {
+  return SUBCOMMAND_ALIASES[category]?.[subcommand] ?? null;
+}
+
 const TOP_LEVEL_COMMANDS = new Set(["help", "status", "doctor", "gates", "hide"]);
 
 const HELP_CATEGORY_LABELS = {
@@ -84,6 +103,7 @@ const SUBCOMMAND_DESCRIPTIONS = {
     "upsert-verdict": "Post/update gate review comment",
     "detect-evidence": "Check merge preconditions",
     "write-findings-log": "Write disposition ledger",
+    "post-findings": "Post gate fan-out findings comment",
     "request-copilot": "Request Copilot review",
     "probe-copilot": "Poll for Copilot review activity",
     "capture-threads": "Capture review threads",
@@ -105,7 +125,7 @@ const SUBCOMMAND_DESCRIPTIONS = {
     "debt-remediate": "File debt remediation issues",
   },
   pr: {
-    "create-draft": "Create draft PR",
+    create: "Create PR (always draft, self-assigned by default)",
     "ready-for-review": "Mark PR ready for review",
     "reconcile-draft": "Reconcile non-draft PR",
   },
@@ -113,7 +133,9 @@ const SUBCOMMAND_DESCRIPTIONS = {
     list: "List queue board items",
     add: "Add issue/PR to queue board",
     move: "Move queue item between Status columns",
-    reorder: "Reorder queue board items",
+    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: {
@@ -273,16 +295,19 @@ function resolveSubcommandRoute(args) {
     return { error: `Missing subcommand for '${category}'. Available: ${subs}` };
   }
 
-  const subcommand = args[1];
+  const requestedSubcommand = args[1];
+  const alias = resolveSubcommandAlias(category, requestedSubcommand);
+  const subcommand = alias ? alias.canonical : requestedSubcommand;
   const scriptPath = routes[subcommand];
   if (!scriptPath) {
     const subs = Object.keys(routes).join(", ");
-    return { error: `Unknown subcommand '${subcommand}' for '${category}'. Available: ${subs}` };
+    return { error: `Unknown subcommand '${requestedSubcommand}' for '${category}'. Available: ${subs}` };
   }
 
   return {
     scriptPath: path.resolve(REPO_ROOT, scriptPath),
     forwardedArgs: args.slice(2),
+    ...(alias ? { deprecationNotice: alias.notice } : {}),
   };
 }
 
@@ -311,9 +336,17 @@ function parseTopLevelCommand(argv) {
     }
     // Check if any remaining arg is --help — delegate to script
     if (args.slice(1).some((a) => a === "--help" || a === "-h")) {
-      const scriptPath = routes[sub];
+      const alias = resolveSubcommandAlias(cmd, sub);
+      const resolvedSub = alias ? alias.canonical : sub;
+      const scriptPath = routes[resolvedSub];
       if (!scriptPath) return { kind: "category_help", category: cmd };
-      return { kind: "subcommand_help", scriptPath: path.resolve(REPO_ROOT, scriptPath) };
+      return {
+        kind: "subcommand_help",
+        scriptPath: path.resolve(REPO_ROOT, scriptPath),
+        // Surface the deprecation notice on the --help fast-path too, so a
+        // deprecated alias signals migration in help mode (not only on dispatch).
+        ...(alias ? { deprecationNotice: alias.notice } : {}),
+      };
     }
     const route = resolveSubcommandRoute(args);
     if (route) return { kind: "subcommand", ...route };
@@ -343,6 +376,7 @@ export async function runCli({
       return 0;
     }
     case "subcommand_help": {
+      if (fromTop.deprecationNotice) { writeLines(stderr, [fromTop.deprecationNotice]); }
       const result = spawnSync("node", [fromTop.scriptPath, "--help"], {
         cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"],
       });
@@ -381,6 +415,7 @@ export async function runCli({
     }
     case "subcommand": {
       if (fromTop.error) { writeLines(stderr, [fromTop.error]); return 1; }
+      if (fromTop.deprecationNotice) { writeLines(stderr, [fromTop.deprecationNotice]); }
       const scriptArgs = fromTop.forwardedArgs || [];
       const result = spawnSync("node", [fromTop.scriptPath, ...scriptArgs], {
         cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"],

package/package.json

@@ -68,7 +68,7 @@
   },
   "dependencies": {
     "mermaid": "11.15.0",
-    "@dev-loops/core": "^0.2.6"
+    "@dev-loops/core": "^0.3.0"
   },
   "repository": {
     "type": "git",
@@ -78,7 +78,7 @@
     "url": "https://github.com/mfittko/dev-loops/issues"
   },
   "homepage": "https://github.com/mfittko/dev-loops#readme",
-  "version": "0.2.6",
+  "version": "0.3.0",
   "files": [
     "cli/",
     "lib/",

package/scripts/README.md

@@ -68,16 +68,17 @@ Failure behavior:
 - malformed arguments, invalid JSON, and `gh` failures emit `{ "ok": false, "error": "..." }` on stderr and exit non-zero
 - live capture is only allowed when both `--repo` and `--pr` are present
 
-### `scripts/github/create-draft-pr.mjs`
+### `scripts/github/create-pr.mjs`
 
-Thin wrapper around `gh pr create` for draft-first PR creation.
+Canonical wrapper around `gh pr create`. Every PR opened through this tool is ALWAYS a draft and is always assigned — self-assigned by default (`--assignee @me` when none is given), while still honoring an explicit `--assignee <login>`. Never call raw `gh pr create` to open a PR. (`dev-loops pr create` dispatches here; the legacy `dev-loops pr create-draft` subcommand still works as a deprecated alias.)
 
 Usage:
-- `node scripts/github/create-draft-pr.mjs [gh pr create args...]`
-- `node <resolved-skill-scripts>/github/create-draft-pr.mjs [gh pr create args...]`
+- `node scripts/github/create-pr.mjs [gh pr create args...]`
+- `node <resolved-skill-scripts>/github/create-pr.mjs [gh pr create args...]`
 
 Contract:
-- injects exactly one `--draft` when the caller did not already supply it
+- injects exactly one `--draft` when the caller did not already supply it (draft is the only mode)
+- self-assigns by default (defaults `--assignee @me` when no `--assignee` is provided); honors an explicit `--assignee <login>` when one is given
 - rejects `--ready` before invoking `gh`; use `gh pr ready` later after draft-gate approval
 - forwards every other argument to `gh pr create` unchanged and in order
 - preserves the underlying `gh pr create` stdout, stderr, and exit code without wrapping success output

package/scripts/_cli-primitives.mjs

@@ -1,6 +1,8 @@
 // Re-export from shared library (Phase 2, issue #548)
 export {
+  parseCliTokens,
   requireOptionValue,
+  requireTokenValue,
   parsePositiveInteger,
   parseNonNegativeInteger,
   parsePrNumber,

package/scripts/_core-helpers.mjs

@@ -19,6 +19,7 @@ export {
   normalizeTimestamp,
   parseGateReviewCommentBody,
   parseGateReviewCommentMarkerBody,
+  resolveDraftGateRoundResetMs,
   summarizeCopilotReviews,
   summarizeGateReviewCommentMarkers,
   summarizeGateReviewComments,

package/scripts/claude/generate-claude-assets.mjs

@@ -24,6 +24,16 @@ import { transformAgent, transformSkill, stripPiOnlyBlocks } from "@dev-loops/co
 export function collectGeneratedAssets({ repoRoot = process.cwd() } = {}) {
   const assets = [];
 
+  // The dev-loops package version pins the Claude `npx dev-loops@<version>` CLI invocation so the
+  // generated plugin tree cannot drift against the published version (#833). Read it once here.
+  // Falls back to `latest` when no repo-root package.json is present (e.g. a consumer/fixture tree
+  // that mirrors only agents/skills).
+  let version = "latest";
+  const pkgPath = path.join(repoRoot, "package.json");
+  if (fs.existsSync(pkgPath)) {
+    version = JSON.parse(fs.readFileSync(pkgPath, "utf8")).version ?? "latest";
+  }
+
   const agentsDir = path.join(repoRoot, "agents");
   if (fs.existsSync(agentsDir)) {
     for (const entry of fs.readdirSync(agentsDir).sort()) {
@@ -31,7 +41,7 @@ export function collectGeneratedAssets({ repoRoot = process.cwd() } = {}) {
       const source = `agents/${entry}`;
       const raw = fs.readFileSync(path.join(repoRoot, source), "utf8");
       const base = entry.slice(0, -".agent.md".length);
-      assets.push({ target: `.claude/agents/${base}.md`, content: transformAgent({ source, raw }) });
+      assets.push({ target: `.claude/agents/${base}.md`, content: transformAgent({ source, raw, version }) });
     }
   }
 
@@ -43,7 +53,7 @@ export function collectGeneratedAssets({ repoRoot = process.cwd() } = {}) {
       const abs = path.join(repoRoot, source);
       if (!fs.existsSync(abs)) continue; // e.g. skills/docs/ holds shared docs, not a SKILL.md
       const raw = fs.readFileSync(abs, "utf8");
-      assets.push({ target: `.claude/skills/${entry.name}/SKILL.md`, content: transformSkill({ source, raw }) });
+      assets.push({ target: `.claude/skills/${entry.name}/SKILL.md`, content: transformSkill({ source, raw, version }) });
     }
   }
 

package/scripts/claude/headless-dev-loop.mjs

@@ -20,6 +20,7 @@
 import { spawnSync } from "node:child_process";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { parseArgs } from "node:util";
 
 import { ensureRunId } from "@dev-loops/core/loop/run-context";
 import {
@@ -28,22 +29,61 @@ import {
   DEFAULT_CLAUDE_BIN,
 } from "@dev-loops/core/claude/headless-entry";
 
-function parseArgs(argv) {
+function parseCliArgs(argv) {
   const opts = { dryRun: false, claudeBin: DEFAULT_CLAUDE_BIN };
-  const requireValue = (name, i) => {
-    const v = argv[i + 1];
-    if (v === undefined || v.startsWith("--")) throw new Error(`${name} requires a value`);
+  const requireValue = (name, token) => {
+    const v = token.value;
+    if (typeof v !== "string" || v.length === 0 || v.startsWith("--")) {
+      throw new Error(`${name} requires a value`);
+    }
     return v;
   };
-  for (let i = 0; i < argv.length; i++) {
-    const a = argv[i];
-    if (a === "--dry-run") opts.dryRun = true;
-    else if (a === "--issue") { opts.issue = requireValue(a, i); i++; }
-    else if (a === "--pr") { opts.pr = requireValue(a, i); i++; }
-    else if (a === "--claude-bin") { opts.claudeBin = requireValue(a, i); i++; }
-    else if (a === "--prompt") { opts.prompt = requireValue(a, i); i++; }
-    else throw new Error(`unknown argument: ${a}`);
+
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: {
+      "dry-run": { type: "boolean" },
+      issue: { type: "string" },
+      pr: { type: "string" },
+      "claude-bin": { type: "string" },
+      prompt: { type: "string" },
+    },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
+
+  for (const token of tokens) {
+    if (token.kind === "positional") {
+      throw new Error(`unknown argument: ${token.value}`);
+    }
+    if (token.kind !== "option") {
+      continue;
+    }
+    switch (token.name) {
+      case "dry-run":
+        if (token.value !== undefined) {
+          throw new Error(`unknown argument: ${token.rawName}=${token.value}`);
+        }
+        opts.dryRun = true;
+        break;
+      case "issue":
+        opts.issue = requireValue("--issue", token);
+        break;
+      case "pr":
+        opts.pr = requireValue("--pr", token);
+        break;
+      case "claude-bin":
+        opts.claudeBin = requireValue("--claude-bin", token);
+        break;
+      case "prompt":
+        opts.prompt = requireValue("--prompt", token);
+        break;
+      default:
+        throw new Error(`unknown argument: ${token.rawName}`);
+    }
   }
+
   if (opts.issue != null && opts.pr != null) {
     throw new Error("--issue and --pr are mutually exclusive");
   }
@@ -53,7 +93,7 @@ function parseArgs(argv) {
 function main(argv) {
   let opts;
   try {
-    opts = parseArgs(argv);
+    opts = parseCliArgs(argv);
   } catch (error) {
     process.stderr.write(JSON.stringify({ ok: false, error: error.message }) + "\n");
     return 1;

package/scripts/claude/headless-info-smoke.mjs

@@ -18,21 +18,55 @@
 import { spawnSync } from "node:child_process";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { parseArgs } from "node:util";
 
-function parseArgs(argv) {
+function parseCliArgs(argv) {
   const opts = { loopInfo: false };
-  const requireValue = (name, i) => {
-    const v = argv[i + 1];
-    if (v === undefined || v.startsWith("--")) throw new Error(`${name} requires a value`);
+  const requireValue = (name, token) => {
+    const v = token.value;
+    if (typeof v !== "string" || v.length === 0 || v.startsWith("--")) {
+      throw new Error(`${name} requires a value`);
+    }
     return v;
   };
-  for (let i = 0; i < argv.length; i++) {
-    const a = argv[i];
-    if (a === "--loop-info") opts.loopInfo = true;
-    else if (a === "--issue") { opts.issue = requireValue(a, i); i++; }
-    else if (a === "--pr") { opts.pr = requireValue(a, i); i++; }
-    else throw new Error(`unknown argument: ${a}`);
+
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: {
+      "loop-info": { type: "boolean" },
+      issue: { type: "string" },
+      pr: { type: "string" },
+    },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
+
+  for (const token of tokens) {
+    if (token.kind === "positional") {
+      throw new Error(`unknown argument: ${token.value}`);
+    }
+    if (token.kind !== "option") {
+      continue;
+    }
+    switch (token.name) {
+      case "loop-info":
+        if (token.value !== undefined) {
+          throw new Error(`unknown argument: ${token.rawName}=${token.value}`);
+        }
+        opts.loopInfo = true;
+        break;
+      case "issue":
+        opts.issue = requireValue("--issue", token);
+        break;
+      case "pr":
+        opts.pr = requireValue("--pr", token);
+        break;
+      default:
+        throw new Error(`unknown argument: ${token.rawName}`);
+    }
   }
+
   if (opts.issue != null && opts.pr != null) {
     throw new Error("--issue and --pr are mutually exclusive");
   }
@@ -46,7 +80,7 @@ function runCli(cliEntry, repoRoot, args) {
 function main(argv) {
   let opts;
   try {
-    opts = parseArgs(argv);
+    opts = parseCliArgs(argv);
   } catch (error) {
     process.stderr.write(JSON.stringify({ ok: false, error: error.message }) + "\n");
     return 1;

package/scripts/docs/validate-links.mjs

@@ -2,9 +2,10 @@
 import { lstat, readdir, readFile, stat } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { parseArgs } from "node:util";
 
 import { isDirectCliRun } from "../_core-helpers.mjs";
-import { requireOptionValue } from "../_cli-primitives.mjs";
+import { requireTokenValue } from "../_cli-primitives.mjs";
 
 const DEFAULT_SCAN_PATHS = Object.freeze([
   "README.md",
@@ -52,26 +53,34 @@ function parseError(message) {
 }
 
 export function parseValidateLinksCliArgs(argv) {
-  const args = [...argv];
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: { help: { type: "boolean", short: "h" }, root: { type: "string" } },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
   const options = {
     help: false,
     repoRoot: resolveDefaultRepoRoot(),
   };
 
-  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 === "--root") {
-      options.repoRoot = path.resolve(requireOptionValue(args, "--root"));
+    if (token.name === "root") {
+      options.repoRoot = path.resolve(requireTokenValue(token));
       continue;
     }
-
-    throw parseError(`Unknown argument: ${token}`);
+    throw parseError(`Unknown argument: ${token.rawName}`);
   }
 
   return options;