dev-loops 0.2.5 → 0.2.7

package/agents/dev-loop.agent.md

@@ -25,7 +25,11 @@ The envelope is the primary handoff artifact — it is derived from resolver out
 - `acceptance` — self-validation criteria for declaring completion
 
 **Construction sequence:**
-1. Run the deterministic startup resolver to produce the authoritative state bundle: `npx dev-loops loop startup --issue <n>` for issues, or `npx dev-loops loop startup --pr <n>` for PRs.
+<!-- pi-only -->
+**CLI invocation (`<dev-loops-package-root>`):** dev-loop CLI commands 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 agent's own installed path: this agent is installed at `<package-root>/.pi/agents/dev-loop.agent.md`, so the package root is `../..` from this agent's directory (`agents` → `.pi` → package root). (The `dev-loop` skill resolves it analogously from its own installed path.)
+<!-- /pi-only -->
+
+1. Run the deterministic startup resolver to produce the authoritative state bundle: `node <dev-loops-package-root>/cli/index.mjs loop startup --issue <n>` for issues, or `node <dev-loops-package-root>/cli/index.mjs loop startup --pr <n>` for PRs.
 2. Pass the resolver output, resolved settings (merged from `.devloops` and `.pi/dev-loop/defaults.yaml`), and current gate state to `buildDevLoopHandoffEnvelope()`.
 3. **Validate the envelope** with `validateHandoffEnvelope()` before consuming any field. If validation returns `ok: false`, reject the handoff with the structured error — do not load requiredReads, do not execute nextAction, do not delegate.
 4. Read the envelope as the first artifact.

package/cli/index.mjs

@@ -52,6 +52,7 @@ 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",
     ensure:  "scripts/projects/ensure-queue-board.mjs",
   },
   queue: {
@@ -113,7 +114,8 @@ 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",
     ensure: "Create/repair queue board bootstrap surface",
   },
   queue: {

package/package.json

@@ -68,7 +68,7 @@
   },
   "dependencies": {
     "mermaid": "11.15.0",
-    "@dev-loops/core": "^0.2.5"
+    "@dev-loops/core": "^0.2.7"
   },
   "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.5",
+  "version": "0.2.7",
   "files": [
     "cli/",
     "lib/",

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/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 }) });
     }
   }
 
@@ -60,9 +70,54 @@ export function collectGeneratedAssets({ repoRoot = process.cwd() } = {}) {
     assets.push(...collectBundle(repoRoot, srcRel, targetRel));
   }
 
+  // Self-contained hook bundle (#843). The PreToolUse/PostToolUse hook scripts under
+  // .claude/hooks/ ship inside the Claude plugin, which has no node_modules — so they cannot
+  // import `@dev-loops/core` (it is unresolvable from the plugin cache and crashes the hook on
+  // load). Vendor the pure deciders/classifiers they need as self-contained relative `_*.mjs`
+  // modules generated from the canonical core sources, with cross-module imports rewritten to
+  // local paths. The no-drift check keeps them in sync with packages/core/src.
+  assets.push(...collectHookBundle(repoRoot));
+
   return assets;
 }
 
+/**
+ * The core modules vendored into `.claude/hooks/` for the self-contained hook bundle (#843).
+ * `rewrites` rewrites cross-module import specifiers to the sibling vendored copies; node:
+ * builtins are left untouched.
+ */
+const HOOK_BUNDLE = [
+  { source: "packages/core/src/loop/bash-command-classify.mjs", target: ".claude/hooks/_bash-command-classify.mjs", rewrites: [] },
+  { source: "packages/core/src/loop/run-context.mjs", target: ".claude/hooks/_run-context.mjs", rewrites: [] },
+  {
+    source: "packages/core/src/claude/hook-decisions.mjs",
+    target: ".claude/hooks/_hook-decisions.mjs",
+    rewrites: [
+      ['"../loop/run-context.mjs"', '"./_run-context.mjs"'],
+      ['"../loop/bash-command-classify.mjs"', '"./_bash-command-classify.mjs"'],
+    ],
+  },
+];
+
+/** Marker that identifies a generated hook-bundle module (a JS comment, distinct from the
+ * markdown `<!-- GENERATED -->` banner used by generated skills/agents/docs). Used both to
+ * stamp generated bundle modules and to scope orphan detection to them within `.claude/hooks/`. */
+const HOOK_BUNDLE_BANNER_PREFIX = "// GENERATED from ";
+
+/** Collect the vendored self-contained hook bundle modules (#843). */
+function collectHookBundle(repoRoot) {
+  const out = [];
+  for (const { source, target, rewrites } of HOOK_BUNDLE) {
+    const abs = path.join(repoRoot, source);
+    if (!fs.existsSync(abs)) continue; // no-op when core sources are absent (e.g. consumer tree)
+    let body = fs.readFileSync(abs, "utf8");
+    for (const [from, to] of rewrites) body = body.split(from).join(to);
+    const banner = `${HOOK_BUNDLE_BANNER_PREFIX}${source} by scripts/claude/generate-claude-assets.mjs — do not edit; edit the source and regenerate.\n`;
+    out.push({ target, content: banner + body });
+  }
+  return out;
+}
+
 /**
  * Recursively collect `*.md` files under a source dir as {target, content} bundle assets.
  * Bodies are passed through `stripPiOnlyBlocks` so bundled contract docs can scope Pi-runtime
@@ -114,10 +169,23 @@ function listFilesRecursive(repoRoot, rel) {
  * bundled docs/templates whose source was removed — are detected, not just SKILL.md files.
  */
 function listExistingAssetFiles(repoRoot) {
-  return [
+  const files = [
     ...listFilesRecursive(repoRoot, ".claude/agents"),
     ...listFilesRecursive(repoRoot, ".claude/skills"),
   ];
+  // `.claude/hooks/` mixes hand-authored scripts (hooks.json, _hook-io.mjs, the three hook
+  // scripts) with generated bundle modules (#843). Only the generated ones — identified by the
+  // generator banner — participate in orphan detection, so a dropped/renamed HOOK_BUNDLE entry
+  // is caught without false-flagging the hand-authored files.
+  for (const rel of listFilesRecursive(repoRoot, ".claude/hooks")) {
+    const abs = path.join(repoRoot, rel);
+    try {
+      if (fs.readFileSync(abs, "utf8").startsWith(HOOK_BUNDLE_BANNER_PREFIX)) files.push(rel);
+    } catch {
+      // unreadable — skip
+    }
+  }
+  return files;
 }
 
 /**

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;

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

@@ -8,7 +8,8 @@ import {
   parseReviewThreads,
   readInput,
 } from "../_core-helpers.mjs";
-import { parsePrNumber, requireOptionValue, runChild } from "../_cli-primitives.mjs";
+import { parseArgs } from "node:util";
+import { parsePrNumber, requireTokenValue, runChild } from "../_cli-primitives.mjs";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
 export const REVIEW_THREADS_QUERY = [
   "query($owner: String!, $name: String!, $pr: Int!) {",
@@ -49,7 +50,19 @@ Exit codes:
   1   Error
 `;
 export function parseCaptureCliArgs(argv) {
-  const args = [...argv];
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: {
+      help: { type: "boolean", short: "h" },
+      input: { type: "string" },
+      output: { type: "string" },
+      repo: { type: "string" },
+      pr: { type: "string" },
+    },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
   const options = {
     inputPath: undefined,
     outputPath: undefined,
@@ -57,29 +70,34 @@ export function parseCaptureCliArgs(argv) {
     pr: undefined,
     help: false,
   };
-  while (args.length > 0) {
-    const token = args.shift();
-    if (token === "--help" || token === "-h") {
+  for (const token of tokens) {
+    if (token.kind === "positional") {
+      throw new Error(`Unknown argument: ${token.value}`);
+    }
+    if (token.kind !== "option") {
+      continue;
+    }
+    if (token.name === "help") {
       options.help = true;
       return options;
     }
-    if (token === "--input") {
-      options.inputPath = requireOptionValue(args, "--input");
+    if (token.name === "input") {
+      options.inputPath = requireTokenValue(token);
       continue;
     }
-    if (token === "--output") {
-      options.outputPath = requireOptionValue(args, "--output");
+    if (token.name === "output") {
+      options.outputPath = requireTokenValue(token);
       continue;
     }
-    if (token === "--repo") {
-      options.repo = requireOptionValue(args, "--repo");
+    if (token.name === "repo") {
+      options.repo = requireTokenValue(token);
       continue;
     }
-    if (token === "--pr") {
-      options.pr = parsePrNumber(requireOptionValue(args, "--pr"));
+    if (token.name === "pr") {
+      options.pr = parsePrNumber(requireTokenValue(token));
       continue;
     }
-    throw new Error(`Unknown argument: ${token}`);
+    throw new Error(`Unknown argument: ${token.rawName}`);
   }
   const hasLiveArgs = options.repo !== undefined || options.pr !== undefined;
   const hasCompleteLiveArgs = options.repo !== undefined && options.pr !== undefined;

package/scripts/github/detect-checkpoint-evidence.mjs

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { parseArgs } from "node:util";
 import {
   buildParseError,
   formatCliError,
@@ -8,7 +9,7 @@ import {
   summarizeGateReviewCommentMarkers,
   summarizeGateReviewComments,
 } from "../_core-helpers.mjs";
-import { parsePrNumber, requireOptionValue, runChild } from "../_cli-primitives.mjs";
+import { parsePrNumber, requireTokenValue, runChild } from "../_cli-primitives.mjs";
 import { fetchGithubReviewThreadsPayload } from "./capture-review-threads.mjs";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
 import { ensureAsyncRunnerOwnership } from "../loop/_pr-runner-coordination.mjs";
@@ -84,30 +85,46 @@ Exit codes:
   1  Argument error, gh failure, malformed gh JSON, or missing required pre-merge gate evidence.`.trim();
 const parseError = buildParseError(USAGE);
 export function parseDetectCheckpointEvidenceCliArgs(argv) {
-  const args = [...argv];
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: {
+      help: { type: "boolean", short: "h" },
+      repo: { type: "string" },
+      pr: { type: "string" },
+      "require-before-merge": { type: "boolean" },
+    },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
   const options = {
     help: false,
     repo: undefined,
     pr: undefined,
   };
-  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 === "--repo") {
-      options.repo = requireOptionValue(args, "--repo", parseError).trim();
+    if (token.name === "repo") {
+      options.repo = requireTokenValue(token, parseError).trim();
       continue;
     }
-    if (token === "--pr") {
-      options.pr = parsePrNumber(requireOptionValue(args, "--pr", parseError), parseError);
+    if (token.name === "pr") {
+      options.pr = parsePrNumber(requireTokenValue(token, parseError), parseError);
       continue;
     }
-    if (token === "--require-before-merge") {
+    if (token.name === "require-before-merge") {
       throw parseError(`--require-before-merge has been removed: gate evidence enforcement is now always-on by default. Omit the flag.`);
     }
-    throw parseError(`Unknown argument: ${token}`);
+    throw parseError(`Unknown argument: ${token.rawName}`);
   }
   if (options.repo === undefined || options.pr === undefined) {
     throw parseError("detect-checkpoint-evidence requires both --repo <owner/name> and --pr <number>");

package/scripts/github/detect-linked-issue-pr.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
+import { parseArgs } from "node:util";
 import { buildParseError, formatCliError, isDirectCliRun, parseJsonText } from "../_core-helpers.mjs";
-import { parseIssueNumber, requireOptionValue, runChild } from "../_cli-primitives.mjs";
+import { parseIssueNumber, requireTokenValue, runChild } from "../_cli-primitives.mjs";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
 export const LINKED_ISSUE_PR_QUERY = [
   "query($owner:String!, $name:String!, $issue:Int!, $after:String) {",
@@ -75,27 +76,38 @@ Error output (stderr, JSON):
     { "ok": false, "error": "..." }`.trim();
 const parseError = buildParseError(USAGE);
 export function parseDetectLinkedIssuePrCliArgs(argv) {
-  const args = [...argv];
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: { help: { type: "boolean", short: "h" }, repo: { type: "string" }, issue: { type: "string" } },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
   const options = {
     help: false,
     repo: undefined,
     issue: undefined,
   };
-  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 === "--repo") {
-      options.repo = requireOptionValue(args, "--repo", parseError).trim();
+    if (token.name === "repo") {
+      options.repo = requireTokenValue(token, parseError).trim();
       continue;
     }
-    if (token === "--issue") {
-      options.issue = parseIssueNumber(requireOptionValue(args, "--issue", parseError), parseError);
+    if (token.name === "issue") {
+      options.issue = parseIssueNumber(requireTokenValue(token, parseError), parseError);
       continue;
     }
-    throw parseError(`Unknown argument: ${token}`);
+    throw parseError(`Unknown argument: ${token.rawName}`);
   }
   if (options.repo === undefined || options.issue === undefined) {
     throw parseError("Linked PR detection requires both --repo <owner/name> and --issue <number>");

package/scripts/github/manage-sub-issues.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
+import { parseArgs } from "node:util";
 import { buildParseError, formatCliError, isDirectCliRun, parseJsonText } from "../_core-helpers.mjs";
-import { parsePositiveInteger, requireOptionValue, runChild } from "../_cli-primitives.mjs";
+import { parsePositiveInteger, requireTokenValue, runChild } from "../_cli-primitives.mjs";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
 const USAGE = `Usage: manage-sub-issues.mjs <command> --repo <owner/name> --issue <number> [options]
 Deterministic helper for reading, linking, ordering, and verifying GitHub sub-issue trees.
@@ -76,37 +77,57 @@ export function parseManageSubIssuesCliArgs(argv) {
     expected: undefined,
     ordered: false,
   };
-  while (args.length > 0) {
-    const token = args.shift();
-    if (token === "--help" || token === "-h") {
+  const { tokens } = parseArgs({
+    args,
+    options: {
+      help: { type: "boolean", short: "h" },
+      repo: { type: "string" },
+      issue: { type: "string" },
+      child: { type: "string" },
+      order: { type: "string" },
+      expected: { type: "string" },
+      ordered: { type: "boolean" },
+    },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
+  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 === "--repo") {
-      options.repo = requireOptionValue(args, "--repo", parseError).trim();
+    if (token.name === "repo") {
+      options.repo = requireTokenValue(token, parseError).trim();
       continue;
     }
-    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 === "--child") {
-      options.child = parsePositiveInteger(requireOptionValue(args, "--child", parseError), "Issue number", parseError);
+    if (token.name === "child") {
+      options.child = parsePositiveInteger(requireTokenValue(token, parseError), "Issue number", parseError);
       continue;
     }
-    if (token === "--order") {
-      options.order = parseIssueList(requireOptionValue(args, "--order", parseError));
+    if (token.name === "order") {
+      options.order = parseIssueList(requireTokenValue(token, parseError));
       continue;
     }
-    if (token === "--expected") {
-      options.expected = parseIssueList(requireOptionValue(args, "--expected", parseError));
+    if (token.name === "expected") {
+      options.expected = parseIssueList(requireTokenValue(token, parseError));
       continue;
     }
-    if (token === "--ordered") {
+    if (token.name === "ordered") {
       options.ordered = true;
       continue;
     }
-    throw parseError(`Unknown argument: ${token}`);
+    throw parseError(`Unknown argument: ${token.rawName}`);
   }
   if (options.repo === undefined || options.issue === undefined) {
     throw parseError("Both --repo <owner/name> and --issue <number> are required");

package/scripts/github/probe-copilot-review.mjs

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 import { setTimeout as delay } from "node:timers/promises";
 import { buildParseError, formatCliError, isCopilotLogin, isDirectCliRun, parseJsonText, parseReviewThreads } 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 { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
 import {
   DEFAULT_POLL_INTERVAL_MS,
@@ -88,7 +89,13 @@ function rejectRemovedFlag(token) {
   );
 }
 export function parseWatchCliArgs(argv) {
-  const args = [...argv];
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: { help: { type: "boolean", short: "h" }, repo: { type: "string" }, pr: { type: "string" } },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
   const options = {
     help: false,
     repo: undefined,
@@ -96,24 +103,29 @@ export function parseWatchCliArgs(argv) {
     pollIntervalMs: DEFAULT_POLL_INTERVAL_MS,
     timeoutMs: COPILOT_REVIEW_WAIT_TIMEOUT_MS,
   };
-  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 (REMOVED_FLAGS.has(token)) {
-      rejectRemovedFlag(token);
+    if (REMOVED_FLAGS.has(token.rawName)) {
+      rejectRemovedFlag(token.rawName);
     }
-    if (token === "--repo") {
-      options.repo = requireOptionValue(args, "--repo", parseError).trim();
+    if (token.name === "repo") {
+      options.repo = requireTokenValue(token, parseError).trim();
       continue;
     }
-    if (token === "--pr") {
-      options.pr = parsePositiveInteger(requireOptionValue(args, "--pr", parseError), "--pr", parseError);
+    if (token.name === "pr") {
+      options.pr = parsePositiveInteger(requireTokenValue(token, parseError), "--pr", parseError);
       continue;
     }
-    throw parseError(`Unknown argument: ${token}`);
+    throw parseError(`Unknown argument: ${token.rawName}`);
   }
   if (options.repo === undefined || options.pr === undefined) {
     throw parseError("Watching Copilot review requires both --repo <owner/name> and --pr <number>");

package/scripts/github/ready-for-review.mjs

@@ -1,21 +1,31 @@
 #!/usr/bin/env node
+import { parseArgs } from "node:util";
 import { buildParseError, formatCliError, isDirectCliRun, parseJsonText, summarizeGateReviewComments, summarizeGateReviewCommentMarkers } from "../_core-helpers.mjs";
-import { parsePrNumber, requireOptionValue, runChild } from "../_cli-primitives.mjs";
+import { parsePrNumber, requireTokenValue, runChild } from "../_cli-primitives.mjs";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
 import { loadDevLoopConfig, resolveGateConfig } from "@dev-loops/core/config";
+import { findBlockingTitleMarkers } from "@dev-loops/core/loop/pr-title-markers";
 
 const USAGE = `Usage: ready-for-review.mjs --repo <owner/name> --pr <number>\nWrapper around gh pr ready that enforces gate-evidence validation.`;
 const parseError = buildParseError(USAGE);
-const PR_VIEW_QUERY = `query($owner:String!, $name:String!, $number:Int!) { repository(owner:$owner, name:$name) { pullRequest(number:$number) { id, isDraft, headRefOid, state, mergeStateStatus } } }`;
+const PR_VIEW_QUERY = `query($owner:String!, $name:String!, $number:Int!) { repository(owner:$owner, name:$name) { pullRequest(number:$number) { id, isDraft, headRefOid, state, mergeStateStatus, title } } }`;
 
 export function parseReadyForReviewCliArgs(argv) {
-  const args = [...argv], opts = { help: false, repo: undefined, pr: undefined };
-  while (args.length > 0) {
-    const token = args.shift();
-    if (token === "--help" || token === "-h") { opts.help = true; return opts; }
-    if (token === "--repo") { opts.repo = requireOptionValue(args, "--repo", parseError).trim(); continue; }
-    if (token === "--pr") { opts.pr = parsePrNumber(requireOptionValue(args, "--pr", parseError), parseError); continue; }
-    throw parseError(`Unknown argument: ${token}`);
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: { help: { type: "boolean", short: "h" }, repo: { type: "string" }, pr: { type: "string" } },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
+  const opts = { help: false, repo: undefined, pr: undefined };
+  for (const token of tokens) {
+    if (token.kind === "positional") throw parseError(`Unknown argument: ${token.value}`);
+    if (token.kind !== "option") continue;
+    if (token.name === "help") { opts.help = true; return opts; }
+    if (token.name === "repo") { opts.repo = requireTokenValue(token, parseError).trim(); continue; }
+    if (token.name === "pr") { opts.pr = parsePrNumber(requireTokenValue(token, parseError), parseError); continue; }
+    throw parseError(`Unknown argument: ${token.rawName}`);
   }
   if (!opts.repo || opts.pr === undefined) throw parseError("ready-for-review requires --repo and --pr");
   parseRepoSlug(opts.repo);
@@ -33,7 +43,7 @@ async function fetchPrState({ repo, pr }, { env, ghCommand }) {
   const r = await runGhJson(["api", "graphql", "-f", `query=${PR_VIEW_QUERY}`, "-f", `owner=${owner}`, "-f", `name=${name}`, "-F", `number=${pr}`], { env, ghCommand });
   const d = r?.data?.repository?.pullRequest;
   if (!d) throw new Error(`Could not fetch PR #${pr}`);
-  return { id: d.id, isDraft: d.isDraft === true, headRefOid: typeof d.headRefOid === "string" ? d.headRefOid.trim() : null, state: typeof d.state === "string" ? d.state.trim() : null, mergeStateStatus: typeof d.mergeStateStatus === "string" ? d.mergeStateStatus.trim() : null };
+  return { id: d.id, isDraft: d.isDraft === true, headRefOid: typeof d.headRefOid === "string" ? d.headRefOid.trim() : null, state: typeof d.state === "string" ? d.state.trim() : null, mergeStateStatus: typeof d.mergeStateStatus === "string" ? d.mergeStateStatus.trim() : null, title: typeof d.title === "string" ? d.title : null };
 }
 
 async function fetchCiStatus({ repo, pr }, { env, ghCommand }) {
@@ -71,6 +81,8 @@ export async function readyForReview(options, { env = process.env, ghCommand = "
   const headSha = prState.headRefOid;
   if (!headSha) throw new Error(`Could not resolve head SHA`);
   if (!prState.isDraft) throw new Error(`PR #${options.pr} is not in draft state`);
+  const titleMarkers = findBlockingTitleMarkers(prState.title);
+  if (titleMarkers.length > 0) throw new Error(`PR #${options.pr} cannot be marked ready: title contains merge-blocking marker(s): ${titleMarkers.join(", ")}. Remove them from the title first.`);
   if (requireCi) { const ci = await fetchCiStatus({ repo: options.repo, pr: options.pr }, { env, ghCommand }); if (ci.status === "blocked") throw new Error(`PR #${options.pr} has blocking CI checks`); if (ci.status !== "success") throw new Error(`PR #${options.pr} CI is not green`); }
   const gate = await fetchGateEvidence({ repo: options.repo, pr: options.pr, headSha }, { env, ghCommand });
   if (!gate.cleanEvidenceExists && !gate.effectiveHeadClean) throw new Error(`No visible clean draft_gate evidence on ${headSha.slice(0,7)}`);