dev-loops 0.3.0 → 0.5.0

package/scripts/loop/run-watch-cycle.mjs

@@ -5,13 +5,17 @@ import { buildParseError, formatCliError, isDirectCliRun } from "../_core-helper
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
 import { DEV_LOOP_CONTRACT_TRACE_CLASSIFICATION } from "@dev-loops/core/loop/public-dev-loop-routing";
 import { watchCopilotReview } from "../github/probe-copilot-review.mjs";
+import { watchCiStatus } from "../github/probe-ci-status.mjs";
 import { runHandoff } from "./copilot-pr-handoff.mjs";
+import { STATE } from "@dev-loops/core/loop/copilot-loop-state";
+import { DEFAULT_POLL_INTERVAL_MS } from "@dev-loops/core/loop/policy-constants";
 import { detectCopilotSessionActivity } from "./detect-copilot-session-activity.mjs";
 import { parseArgs } from "node:util";
 import {
   EXTERNAL_HEALTHY_WAIT_TIMEOUT_POLICY,
   enforceExternalHealthyWaitTimeout,
 } from "@dev-loops/core/loop/timeout-policy";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult } from "../lib/jq-output.mjs";
 const REMOVED_FLAGS = new Set([
   "--force-rerequest-review",
   "--probe-only",
@@ -43,9 +47,16 @@ Error output (stderr, JSON):
     { "ok": false, "error": "...", "usage": "..." }
   runtime failures:
     { "ok": false, "error": "..." }
+Concise mode:
+  --concise, --summary      Human-readable summary: loop state, copilot rounds,
+                            unresolved/actionable thread counts, round-cap-clean
+                            eligibility, CI status, next action, AND the current
+                            round's new Copilot comment bodies.
+${JQ_OUTPUT_USAGE}
 Exit codes:
   0  Success
-  1  Argument error or runtime failure`.trim();
+  1  Argument error or runtime failure
+  2  Invalid --jq filter`.trim();
 const parseError = buildParseError(USAGE);
 function rejectRemovedFlag(token) {
   throw parseError(
@@ -124,16 +135,33 @@ function buildWatchCycleContractTrace({
   cycleDisposition,
   sessionActivity = null,
   workflowRunWatch = null,
+  ciWatchArgs = null,
+  ciWatchStatus = null,
 }) {
-  const boundaryClassification = handoff.action !== "watch"
-    ? (handoff.loopDisposition === "blocked"
+  // The CI-watch branch (waiting_for_ci) routes through probe-ci-status.mjs even
+  // though handoff.action !== "watch". It is an observational wait, so it mirrors
+  // the Copilot watch classification: a quiet timeout is a HEALTHY_WAIT, while
+  // success/failure/changed route a follow-up. Without this the boundary-action
+  // path below would misclassify a CI timeout as routed_followup.
+  const isCiWatch = ciWatchArgs !== null;
+  const isWatchBoundary = handoff.action === "watch" || isCiWatch;
+  const observedStatus = isCiWatch ? ciWatchStatus : watchStatus;
+  const boundaryClassification = isWatchBoundary
+    ? (observedStatus === "timeout" || observedStatus === "idle"
+      ? DEV_LOOP_CONTRACT_TRACE_CLASSIFICATION.HEALTHY_WAIT
+      : DEV_LOOP_CONTRACT_TRACE_CLASSIFICATION.ROUTED_FOLLOWUP)
+    : handoff.loopDisposition === "blocked"
       ? DEV_LOOP_CONTRACT_TRACE_CLASSIFICATION.BLOCKED
       : handoff.terminal
         ? DEV_LOOP_CONTRACT_TRACE_CLASSIFICATION.TERMINAL
-        : DEV_LOOP_CONTRACT_TRACE_CLASSIFICATION.ROUTED_FOLLOWUP)
-    : watchStatus === "changed"
-      ? DEV_LOOP_CONTRACT_TRACE_CLASSIFICATION.ROUTED_FOLLOWUP
-      : DEV_LOOP_CONTRACT_TRACE_CLASSIFICATION.HEALTHY_WAIT;
+        : DEV_LOOP_CONTRACT_TRACE_CLASSIFICATION.ROUTED_FOLLOWUP;
+  const healthyWait = boundaryClassification === DEV_LOOP_CONTRACT_TRACE_CLASSIFICATION.HEALTHY_WAIT;
+  const helper = handoff.action === "watch"
+    ? "scripts/github/probe-copilot-review.mjs"
+    : isCiWatch
+      ? "scripts/github/probe-ci-status.mjs"
+      : null;
+  const effectiveArgs = isCiWatch ? ciWatchArgs : watchArgs;
   return {
     handoff: {
       action: handoff.action,
@@ -142,38 +170,37 @@ function buildWatchCycleContractTrace({
       terminal: Boolean(handoff.terminal),
     },
     waitStrategy: {
-      helper: handoff.action === "watch" ? "scripts/github/probe-copilot-review.mjs" : null,
-      mode: handoff.action === "watch"
-        ? "persistent_watch"
-        : "not_applicable",
-      effectiveTimeoutMs: watchArgs?.timeoutMs ?? null,
-      effectivePollIntervalMs: watchArgs?.pollIntervalMs ?? null,
+      helper,
+      mode: isWatchBoundary ? "persistent_watch" : "not_applicable",
+      effectiveTimeoutMs: effectiveArgs?.timeoutMs ?? null,
+      effectivePollIntervalMs: effectiveArgs?.pollIntervalMs ?? null,
       timeoutPolicyClassification: watchTimeoutPolicy?.classification ?? null,
     },
     orchestration: {
       emittedWatchArgs: handoff.watchArgs ?? null,
-      effectiveWatchArgs: watchArgs,
+      effectiveWatchArgs: effectiveArgs,
+      ciWatchArgs,
       sessionActivity,
       workflowRunWatch,
     },
-    stateRefresh: handoff.action === "watch"
+    stateRefresh: isWatchBoundary
       ? {
           boundaryKind: "post_watch_or_probe",
-          observedStatus: watchStatus,
+          observedStatus,
           refreshRequired: true,
-          refreshReason: watchStatus === "changed"
-            ? "Watch boundaries with fresh activity require an authoritative state refresh before routing the follow-up path."
-            : "Healthy watch boundaries are observational only; refresh authoritative state before treating timeout/idle as stop or completion.",
+          refreshReason: healthyWait
+            ? "Healthy watch boundaries are observational only; refresh authoritative state before treating timeout/idle as stop or completion."
+            : "Watch boundaries with fresh activity require an authoritative state refresh before routing the follow-up path.",
         }
       : null,
     stopReason: {
       classification: boundaryClassification,
       terminal: Boolean(handoff.terminal),
       cycleDisposition,
-      reason: handoff.action === "watch"
-        ? (watchStatus === "changed"
-          ? "Fresh watcher activity requires follow-up instead of staying in a healthy wait boundary."
-          : "Quiet watcher boundaries remain healthy waits and must not be treated as terminal completion by themselves.")
+      reason: isWatchBoundary
+        ? (healthyWait
+          ? "Quiet watcher boundaries remain healthy waits and must not be treated as terminal completion by themselves."
+          : "Fresh watcher activity requires follow-up instead of staying in a healthy wait boundary.")
         : handoff.nextAction,
     },
   };
@@ -183,6 +210,9 @@ export function parseWatchCycleCliArgs(argv) {
     help: false,
     repo: undefined,
     pr: undefined,
+    concise: false,
+    jq: undefined,
+    silent: false,
   };
   const { tokens } = parseArgs({
     args: [...argv],
@@ -190,6 +220,9 @@ export function parseWatchCycleCliArgs(argv) {
       help: { type: "boolean", short: "h" },
       repo: { type: "string" },
       pr: { type: "string" },
+      concise: { type: "boolean" },
+      summary: { type: "boolean" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
     strict: false,
@@ -217,6 +250,18 @@ export function parseWatchCycleCliArgs(argv) {
       options.pr = parsePrNumber(requireTokenValue(token, parseError), parseError);
       continue;
     }
+    if (token.name === "concise" || token.name === "summary") {
+      options.concise = true;
+      continue;
+    }
+    if (token.name === "jq") {
+      options.jq = requireTokenValue(token, parseError);
+      continue;
+    }
+    if (token.name === "silent") {
+      options.silent = true;
+      continue;
+    }
     throw parseError(`Unknown argument: ${token.rawName}`);
   }
   if (options.repo === undefined || options.pr === undefined) {
@@ -236,6 +281,7 @@ export async function runWatchCycle(
     ghCommand = "gh",
     runHandoffImpl = runHandoff,
     watchCopilotReviewImpl = watchCopilotReview,
+    watchCiStatusImpl = watchCiStatus,
     detectCopilotSessionActivityImpl = detectCopilotSessionActivity,
     fetchPrHeadBranchImpl = fetchPrHeadBranch,
     watchWorkflowRunImpl = watchWorkflowRun,
@@ -267,6 +313,39 @@ export async function runWatchCycle(
   if (handoff.watchTimeoutPolicy !== undefined) {
     result.watchTimeoutPolicy = handoff.watchTimeoutPolicy;
   }
+  // Provider-agnostic CI wait (#917): a waiting_for_ci boundary would otherwise
+  // dead-end at action:"stop". Route it to the helper-owned CI watcher
+  // (CircleCI / GH Actions / external commit-status), not gh run watch.
+  if (handoff.action !== "watch" && handoff.state === STATE.WAITING_FOR_CI) {
+    // Mirror determineWatchTimeout but with a CI-specific context label so
+    // timeout diagnostics read "CI wait" instead of "Copilot review wait".
+    const ciTimeoutMs = enforceExternalHealthyWaitTimeout({
+      timeoutMs: EXTERNAL_HEALTHY_WAIT_TIMEOUT_POLICY.defaultTimeoutMs,
+      contextLabel: "CI wait",
+    });
+    const ciWatchArgs = {
+      repo: options.repo,
+      pr: options.pr,
+      pollIntervalMs: DEFAULT_POLL_INTERVAL_MS,
+      timeoutMs: ciTimeoutMs,
+    };
+    const ciWatch = await watchCiStatusImpl(ciWatchArgs, { env, ghCommand });
+    result.ciWatchArgs = ciWatchArgs;
+    result.ciWatch = ciWatch;
+    result.watchStatus = ciWatch.status;
+    // success/failure/changed all need authoritative re-detection (follow-up);
+    // a quiet timeout stays a healthy pending wait.
+    result.cycleDisposition = ciWatch.status === "timeout" ? "pending" : "needs_followup";
+    result.terminal = false;
+    result.contractTrace = buildWatchCycleContractTrace({
+      handoff,
+      watchTimeoutPolicy: result.watchTimeoutPolicy ?? null,
+      cycleDisposition: result.cycleDisposition,
+      ciWatchArgs,
+      ciWatchStatus: ciWatch.status,
+    });
+    return result;
+  }
   if (handoff.action !== "watch") {
     result.contractTrace = buildWatchCycleContractTrace({
       handoff,
@@ -342,6 +421,46 @@ export async function runWatchCycle(
   });
   return result;
 }
+// Human-readable concise summary covering loop state, Copilot round count,
+// unresolved/actionable thread counts, round-cap-clean eligibility, CI status,
+// next action, AND the current round's new Copilot comment bodies (from the
+// embedded watch probe result). This is the field set the loop needs to read
+// without parsing the full JSON blob (issue #981).
+export function formatWatchCycleConcise(result) {
+  const snapshot = result.snapshot ?? {};
+  const lines = [
+    `Watch cycle: PR #${snapshot.prNumber ?? "?"}`,
+    `  loop state:          ${result.state}`,
+    `  handoff action:      ${result.handoffAction}`,
+    `  copilot rounds:      ${snapshot.copilotReviewRoundCount ?? 0}`,
+    `  unresolved threads:  ${snapshot.unresolvedThreadCount ?? 0}`,
+    `  actionable threads:  ${snapshot.actionableThreadCount ?? 0}`,
+    `  round-cap clean:     ${result.roundCapCleanEligible ? "yes" : "no"}`,
+    `  CI status:           ${snapshot.ciStatus ?? "none"}`,
+    `  loop disposition:    ${result.loopDisposition}`,
+    `  cycle disposition:   ${result.cycleDisposition}`,
+    `  watch status:        ${result.watchStatus ?? "(not watched)"}`,
+    `  terminal:            ${result.terminal ? "yes" : "no"}`,
+    `  next action:         ${result.nextAction}`,
+  ];
+  const watch = result.watch ?? {};
+  const bodies = [
+    ...(watch.newReviews ?? []).map((r) => ({ kind: "review", body: r.body })),
+    ...(watch.newComments ?? []).map((c) => ({ kind: "threadComment", body: c.body })),
+    ...(watch.newIssueComments ?? []).map((c) => ({ kind: "issueComment", body: c.body })),
+  ].filter((entry) => typeof entry.body === "string" && entry.body.trim().length > 0);
+  if (bodies.length > 0) {
+    lines.push("  new Copilot comment bodies this round:");
+    for (const entry of bodies) {
+      const indented = entry.body.trim().split("\n").map((l) => `      ${l}`).join("\n");
+      lines.push(`    [${entry.kind}]`);
+      lines.push(indented);
+    }
+  } else {
+    lines.push("  new Copilot comment bodies this round: (none)");
+  }
+  return lines.join("\n");
+}
 export async function runCli(
   argv = process.argv.slice(2),
   {
@@ -364,10 +483,18 @@ export async function runCli(
     watchCopilotReviewImpl,
     detectSessionActivity: true,
   });
-  stdout.write(`${JSON.stringify(result)}\n`);
+  if (options.concise && options.jq === undefined && !options.silent) {
+    stdout.write(`${formatWatchCycleConcise(result)}\n`);
+    return result.ok === false ? 1 : 0;
+  }
+  return emitResult(result, { jq: options.jq, silent: options.silent, stdout });
 }
 if (isDirectCliRun(import.meta.url)) {
-  runCli().catch((error) => {
+  runCli().then((code) => {
+    if (typeof code === "number") {
+      process.exitCode = code;
+    }
+  }).catch((error) => {
     process.stderr.write(`${formatCliError(error)}\n`);
     process.exitCode = 1;
   });

package/scripts/loop/slides-story-review-contract.mjs

@@ -0,0 +1,123 @@
+// Bounded slides content & storytelling reviewer mode behind `dev-loop`.
+// Sibling of scripts/loop/ui-designer-review-contract.mjs: this one judges a
+// deck's narrative, not its pixels. Pure module, no I/O.
+
+export const STORY_REVIEW_OUTCOMES = Object.freeze([
+  'story_review_satisfied',
+  'needs_iteration',
+]);
+
+export const STORY_REVIEW_SEVERITIES = Object.freeze(['high', 'medium', 'low']);
+
+export function validateSlidesStoryReviewInput(input = {}) {
+  // Coerce a null / non-object argument to {} so this validator always returns
+  // its structured status rather than throwing (the module's contract is a
+  // structured result, never an exception).
+  if (!input || typeof input !== 'object') input = {};
+  if (input.workType !== 'slides' || input.storyReviewRequested !== true) {
+    return {
+      ok: true,
+      status: 'skip_non_slides',
+      reason: 'non_slides_or_not_requested',
+      missing: [],
+    };
+  }
+  const missing = [];
+  const acceptanceCriteria = Array.isArray(input.acceptanceCriteria)
+    ? input.acceptanceCriteria.filter((entry) => typeof entry === 'string' && entry.trim().length > 0)
+    : [];
+  if (acceptanceCriteria.length === 0) {
+    missing.push('acceptanceCriteria');
+  }
+  if (typeof input.storytellingBrief !== 'string' || input.storytellingBrief.trim().length === 0) {
+    missing.push('storytellingBrief');
+  }
+  const deckBundle = input.deckBundle ?? {};
+  if (typeof deckBundle.deckSourcePath !== 'string' || deckBundle.deckSourcePath.trim().length === 0) {
+    missing.push('deckBundle.deckSourcePath');
+  }
+  if (missing.length > 0) {
+    return {
+      ok: false,
+      status: 'blocked_missing_required_inputs',
+      reason: 'required_inputs_missing',
+      missing,
+    };
+  }
+  // Captured slide screenshots are optional, but if present each entry must be complete.
+  const incompleteArtifacts = [];
+  const slideScreenshots = Array.isArray(deckBundle.slideScreenshots) ? deckBundle.slideScreenshots : [];
+  slideScreenshots.forEach((rawShot, index) => {
+    const shot = rawShot && typeof rawShot === 'object' ? rawShot : {};
+    if (typeof shot.slideId !== 'string' || shot.slideId.trim().length === 0) {
+      incompleteArtifacts.push(`deckBundle.slideScreenshots[${index}].slideId`);
+    }
+    if (typeof shot.screenshotPath !== 'string' || shot.screenshotPath.trim().length === 0) {
+      incompleteArtifacts.push(`deckBundle.slideScreenshots[${index}].screenshotPath`);
+    }
+  });
+  if (incompleteArtifacts.length > 0) {
+    return {
+      ok: false,
+      status: 'blocked_incomplete_deck_bundle',
+      reason: 'deck_bundle_incomplete',
+      missing: incompleteArtifacts,
+    };
+  }
+  return {
+    ok: true,
+    status: 'ready_for_story_review',
+    reason: 'deck_bundle_complete',
+    missing: [],
+  };
+}
+
+export function validateSlidesStoryReviewResult(result = {}) {
+  // Coerce a null / non-object argument to {} so this validator returns its
+  // structured `invalid` result rather than throwing.
+  if (!result || typeof result !== 'object') result = {};
+  const invalid = [];
+  if (!STORY_REVIEW_OUTCOMES.includes(result.outcome)) {
+    invalid.push('outcome');
+  }
+  if (typeof result.summary !== 'string' || result.summary.trim().length === 0) {
+    invalid.push('summary');
+  }
+  const findings = Array.isArray(result.findings) ? result.findings : null;
+  if (findings === null) {
+    invalid.push('findings');
+  } else {
+    findings.forEach((rawFinding, index) => {
+      const finding = rawFinding && typeof rawFinding === 'object' ? rawFinding : {};
+      if (!STORY_REVIEW_SEVERITIES.includes(finding.severity)) {
+        invalid.push(`findings[${index}].severity`);
+      }
+      if (typeof finding.slideId !== 'string' || finding.slideId.trim().length === 0) {
+        invalid.push(`findings[${index}].slideId`);
+      }
+      if (typeof finding.problem !== 'string' || finding.problem.trim().length === 0) {
+        invalid.push(`findings[${index}].problem`);
+      }
+      if (typeof finding.correctiveAction !== 'string' || finding.correctiveAction.trim().length === 0) {
+        invalid.push(`findings[${index}].correctiveAction`);
+      }
+    });
+  }
+  if (result.outcome === 'needs_iteration' && findings !== null && findings.length === 0) {
+    invalid.push('findings');
+  }
+  if (invalid.length > 0) {
+    return {
+      ok: false,
+      status: 'invalid_result_shape',
+      reason: 'result_shape_invalid',
+      invalid,
+    };
+  }
+  return {
+    ok: true,
+    status: 'valid_result_shape',
+    reason: 'result_shape_valid',
+    invalid: [],
+  };
+}

package/scripts/pages/build-site.mjs

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+// Assembles the GitHub Pages publishable dir deterministically. The landing
+// page (index.html) is the "Introducing dev-loops" article; the deep-dive
+// article and the deep-dive deck are published alongside it and reached through
+// a shared navigation bar injected into the article pages. The source HTML files
+// under docs/ are the source of truth; site/ is assembled, never hand-maintained.
+// Usage: node scripts/pages/build-site.mjs [--out <dir>] [--repo-root <dir>]
+import { cp, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve, parse as parsePath } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const REPO_ROOT_DEFAULT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
+
+// The landing page: the intro article, published as index.html. file is
+// relative to docs/articles/.
+export const LANDING = { file: 'introducing-dev-loops.html' };
+
+// The deep-dive article published alongside the landing page. file is relative
+// to docs/articles/; navLabel is how the nav refers to it.
+export const ARTICLES = [
+  { file: 'dev-loops-deep-dive.html', navLabel: 'Deep dive' },
+];
+
+// The decks to publish. file is relative to docs/presentations/; outFile is the
+// published name (defaults to file). The deep-dive article and deck share the
+// source basename dev-loops-deep-dive.html under different docs/ dirs, so the
+// deck publishes under a distinct name to avoid clobbering the article in site/.
+export const DECKS = [
+  {
+    file: 'introducing-dev-loops.html',
+    title: 'Introducing dev-loops',
+    subtitle: 'A coordination runtime for AI-assisted development',
+    description: 'The concept, the data behind it, and how to run the loop on your own project.',
+    navLabel: 'Intro (deck)',
+  },
+  {
+    file: 'dev-loops-deep-dive.html',
+    outFile: 'dev-loops-deep-dive-deck.html',
+    title: 'dev-loops: A Deep Dive',
+    subtitle: 'Coordination delay and the waiting between actions',
+    description: 'How explicit handoffs on a state graph and measuring the wait between actions cut delivery delay.',
+    navLabel: 'Deep dive (deck)',
+  },
+];
+
+// Resolve a deck's published filename: distinct outFile when set, else file.
+const deckOut = (deck) => deck.outFile ?? deck.file;
+
+// The other resources linked from the navigation, in order.
+export const NAV_LINKS = [
+  ...ARTICLES.map((a) => ({ file: a.file, label: a.navLabel })),
+  ...DECKS.map((d) => ({ file: deckOut(d), label: d.navLabel })),
+];
+
+// Nav styling, appended to each article page's own <style> block so it reuses
+// the article design-system variables (--heading/--kicker/--accent-soft).
+const NAV_CSS = `
+  .site-nav { display: flex; flex-wrap: wrap; align-items: baseline; gap: 0.5rem 1.1rem; max-width: 64rem; margin: 0 auto; padding: 0.9rem clamp(1.1rem, 5vw, 2rem); border-bottom: 1px solid rgba(148, 163, 184, 0.16); }
+  .site-nav-brand { font-weight: 700; letter-spacing: -0.01em; color: var(--heading); text-decoration: none; border: 0; margin-right: auto; }
+  .site-nav-links { display: flex; flex-wrap: wrap; gap: 0.5rem 1.1rem; }
+  .site-nav a { color: var(--kicker); text-decoration: none; font-size: 0.9rem; border: 0; }
+  .site-nav a:hover { color: var(--accent-soft); }`;
+
+function navMarkup() {
+  const links = NAV_LINKS.map((l) => `        <a href="${l.file}">${l.label}</a>`).join('\n');
+  return `<nav class="site-nav" aria-label="dev-loops resources">
+      <a class="site-nav-brand" href="index.html">dev-loops</a>
+      <div class="site-nav-links">
+${links}
+      </div>
+    </nav>`;
+}
+
+// Inject the shared nav into an article page: nav CSS before </style>, nav
+// markup right after <body>. Idempotent enough for assembly (each source file
+// is read once). Throws if the page lacks the expected anchors so a structural
+// drift fails the build rather than publishing an un-navigable page.
+export function injectNav(html) {
+  if (!html.includes('</style>') || !/<body[^>]*>/.test(html)) {
+    throw new Error('cannot inject nav: page is missing a <style> block or <body> tag');
+  }
+  return html
+    .replace('</style>', `${NAV_CSS}\n</style>`)
+    .replace(/<body([^>]*)>/, `<body$1>\n    ${navMarkup()}`);
+}
+
+export async function buildSite({ repoRoot = REPO_ROOT_DEFAULT, outDir } = {}) {
+  const out = outDir ? resolve(outDir) : join(repoRoot, 'site');
+  const articlesDir = join(repoRoot, 'docs', 'articles');
+  const decksDir = join(repoRoot, 'docs', 'presentations');
+
+  // Guard: out is wiped before assembly. Refuse paths that would nuke the
+  // filesystem root, the repo itself, or an ancestor of the repo.
+  const root = resolve(repoRoot);
+  const isAncestorOf = (a, b) => b === a || b.startsWith(a + '/');
+  if (out === parsePath(out).root || out === root || isAncestorOf(out, root)) {
+    throw new Error(`refusing to wipe unsafe output dir ${out}`);
+  }
+
+  await rm(out, { recursive: true, force: true });
+  await mkdir(out, { recursive: true });
+
+  // Landing page: the intro article, navigable, published as index.html.
+  const landingHtml = await readFile(join(articlesDir, LANDING.file), 'utf8');
+  await writeFile(join(out, 'index.html'), injectNav(landingHtml), 'utf8');
+
+  // Deep-dive article: published with the same nav so the set is navigable.
+  for (const article of ARTICLES) {
+    const html = await readFile(join(articlesDir, article.file), 'utf8');
+    await writeFile(join(out, article.file), injectNav(html), 'utf8');
+  }
+
+  // Decks: self-contained slide renders, copied as-is (no nav injection).
+  for (const deck of DECKS) {
+    await cp(join(decksDir, deck.file), join(out, deckOut(deck)));
+  }
+
+  return {
+    out,
+    files: ['index.html', ...ARTICLES.map((a) => a.file), ...DECKS.map((d) => deckOut(d))],
+  };
+}
+
+const invokedDirectly = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (invokedDirectly) {
+  const args = process.argv.slice(2);
+  const getArg = (name) => {
+    const i = args.indexOf(name);
+    return i >= 0 ? args[i + 1] : undefined;
+  };
+  const result = await buildSite({
+    repoRoot: getArg('--repo-root') ? resolve(getArg('--repo-root')) : undefined,
+    outDir: getArg('--out'),
+  });
+  console.log(`Built site at ${result.out}: ${result.files.join(', ')}`);
+}

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

@@ -2,8 +2,10 @@
 import { formatCliError, isDirectCliRun, parseJsonText } from "../_core-helpers.mjs";
 import { runChild as _runChild } from "../_cli-primitives.mjs";
 import { parseArgs } from "node:util";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult } from "../lib/jq-output.mjs";
 
-const USAGE = `Usage: dev-loops project add --repo <owner/name> --project <number|id> --item <number>
+const USAGE = `Usage: dev-loops queue add --repo <owner/name> --project <number|id> --item <number>
+       dev-loops project add … (back-compat alias for "queue add")
 
 Add an existing issue or PR to a GitHub Projects V2 board.
 
@@ -11,16 +13,19 @@ Options:
   --repo <owner/name>         Required. Repository containing the issue/PR.
   --project <number|id>       Required. Project number (integer) or node ID.
   --item <number>             Required. Issue or PR number to add.
-  --status <name>             Initial Status column (default: "Backlog").
+  --column <name>             Initial Status column (default: "Backlog").
+  --status <name>             Back-compat alias for --column.
   --help, -h                  Show this help.
 
 Output (stdout):
   JSON: { ok: true, item: { itemId, issueNumber, prNumber, status, alreadyPresent } }
 
+${JQ_OUTPUT_USAGE}
+
 Exit codes:
   0 — success (or no-op when already present)
   1 — usage or argument error
-  2 — GitHub API error
+  2 — GitHub API error / invalid --jq filter
   3 — project, field, column, or issue/PR not found
 `.trim();
 
@@ -41,8 +46,10 @@ function parseCliArgs(argv) {
       repo: { type: "string" },
       project: { type: "string" },
       item: { type: "string" },
+      column: { type: "string" },
       status: { type: "string" },
       help: { type: "boolean", short: "h" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
     strict: false,
@@ -81,9 +88,21 @@ function parseCliArgs(argv) {
         args.item = val;
         break;
       }
+      case "column":
+        args.column = requireValue(token, "--column requires a value");
+        break;
       case "status":
+        // Back-compat alias for --column (issue #912). Kept separate so a
+        // conflicting `--column X --status Y` is rejected rather than silently
+        // resolved by argv order.
         args.status = requireValue(token, "--status requires a value");
         break;
+      case "jq":
+        args.jq = requireValue(token, "--jq requires a filter");
+        break;
+      case "silent":
+        args.silent = true;
+        break;
       default:
         throw Object.assign(new Error(`Unknown flag: ${token.rawName}`), { code: "INVALID_ARGS", usage: USAGE });
     }
@@ -375,9 +394,15 @@ async function main(args, { env = process.env, runChild } = {}) {
   if (!Number.isInteger(itemNumber) || itemNumber < 1) {
     throw Object.assign(new Error("--item is required and must be a positive integer"), { code: "INVALID_ITEM" });
   }
-  const targetStatus = (args.status ?? "Backlog").trim();
+  if (args.column != null && args.status != null && args.column.trim() !== args.status.trim()) {
+    throw Object.assign(
+      new Error(`Conflicting --column ("${args.column}") and --status ("${args.status}") — pass only one (prefer --column).`),
+      { code: "INVALID_ARGS", usage: USAGE },
+    );
+  }
+  const targetStatus = (args.column ?? args.status ?? "Backlog").trim();
   if (!targetStatus) {
-    throw Object.assign(new Error("--status must not be empty"), { code: "INVALID_STATUS" });
+    throw Object.assign(new Error("--column must not be empty"), { code: "INVALID_STATUS" });
   }
 
   // 1. Resolve owner
@@ -528,7 +553,7 @@ async function runCli(argv, { stdout = process.stdout, stderr = process.stderr,
   }
   try {
     const result = await main(args, { env });
-    stdout.write(JSON.stringify(result) + "\n");
+    process.exitCode = emitResult(result, { jq: args.jq, silent: args.silent, stdout, stderr });
   } catch (err) {
     stderr.write(JSON.stringify({ ok: false, error: err.message, code: err.code ?? "UNKNOWN" }) + "\n");
     process.exitCode = classifyExitCode(err);
@@ -542,4 +567,4 @@ if (isDirectCliRun(import.meta.url)) {
   });
 }
 
-export { main };
+export { main, parseCliArgs };

package/scripts/projects/archive-done-items.mjs

@@ -6,7 +6,8 @@ import { formatCliError, isDirectCliRun, parseJsonText } from "../_core-helpers.
 import { runChild as _runChild } from "../_cli-primitives.mjs";
 import { parseArgs } from "node:util";
 
-const USAGE = `Usage: dev-loops project archive-done --repo <owner/name> [--project <number|id>] [--older-than <duration>] [--dry-run]
+const USAGE = `Usage: dev-loops queue archive-done --repo <owner/name> [--project <number|id>] [--older-than <duration>] [--dry-run]
+       (dev-loops project archive-done … is a back-compat alias)
 
 Archive GitHub Projects V2 items whose issue/PR has been closed for at least the
 given duration. Operator-triggered (no webhooks). Uses archiveProjectV2Item.

package/scripts/projects/ensure-queue-board.mjs

@@ -6,7 +6,8 @@ import { parse as parseYaml } from "yaml";
 import { formatCliError, isDirectCliRun, parseJsonText } from "../_core-helpers.mjs";
 import { runChild as _runChild } from "../_cli-primitives.mjs";
 
-const USAGE = `Usage: dev-loops project ensure --repo <owner/name> [--project <number>] [--title <title>] [--link-repo <owner/name>] [--repair-rename]
+const USAGE = `Usage: dev-loops queue ensure --repo <owner/name> [--project <number>] [--title <title>] [--link-repo <owner/name>] [--repair-rename]
+       (dev-loops project ensure … is a back-compat alias)
 
 --repair-rename    Rename semantically equivalent Status columns to the standard names
                    (e.g. "Ready" -> "Next Up"). Without this flag the helper only