NVIDIA
diff --git a/‎.agents/skills/nemoclaw-maintainer-cut-release-tag/SKILL.md‎
Lines changed: 161 additions & 268 deletions b/‎.agents/skills/nemoclaw-maintainer-cut-release-tag/SKILL.md‎
Lines changed: 161 additions & 268 deletions
diff --git a/‎.agents/skills/nemoclaw-maintainer-cut-release-tag/references/candidate-evidence.md‎
Lines changed: 444 additions & 0 deletions b/‎.agents/skills/nemoclaw-maintainer-cut-release-tag/references/candidate-evidence.md‎
Lines changed: 444 additions & 0 deletions
diff --git a/‎.agents/skills/nemoclaw-maintainer-day/PR-REVIEW-PRIORITIES.md‎
Lines changed: 7 additions & 5 deletions b/‎.agents/skills/nemoclaw-maintainer-day/PR-REVIEW-PRIORITIES.md‎
Lines changed: 7 additions & 5 deletions
diff --git a/‎.agents/skills/nemoclaw-maintainer-day/scripts/handoff-summary.ts‎
Lines changed: 231 additions & 80 deletions b/‎.agents/skills/nemoclaw-maintainer-day/scripts/handoff-summary.ts‎
Lines changed: 231 additions & 80 deletions
diff --git a/‎.agents/skills/nemoclaw-maintainer-day/scripts/shared.ts‎
Lines changed: 1 addition & 0 deletions b/‎.agents/skills/nemoclaw-maintainer-day/scripts/shared.ts‎
Lines changed: 1 addition & 0 deletions
@@ -55,11 +55,13 @@ The team follows a daily ship cycle. All maintainer skills operate within this r
 
 1. **Morning** (`/nemoclaw-maintainer-morning`) — triage the backlog, pick items for the day, label them with the target version (e.g., `v0.0.8`).
 2. **During the day** (`/nemoclaw-maintainer-day`) — land PRs using the maintainer loop. Version labels make progress visible on dashboards.
-3. **Evening** (`/nemoclaw-maintainer-evening`) — Check shipped work and the pre-tag changelog PR.
-   Confirm that the pre-tag changelog PR contains `docs/changelog/YYYY-MM-DD.mdx` for the release.
-   Identify open items and prepare the QA summary. Record the candidate SHA and qualifying full manual `Release qualification` check that the release script accepts.
-   Cut the tag after confirmation. Move open items to the next patch label and delete the released label.
-   Prepare the Announcement.
+3. **Evening** (`/nemoclaw-maintainer-evening`) — check shipped work and the cumulative
+   documentation PR. Confirm that it covers every merged change selected for the release and
+   contains `docs/changelog/YYYY-MM-DD.mdx` for the release.
+   Identify open items and prepare the Markdown release brief. Show the newest full E2E result and
+   let the maintainer choose focused tests, the full suite, or the displayed status.
+   Cut the tag after confirmation. Treat aliases, labels, publication, and the Announcement as work
+   outside tag cutting; some share a workflow or depend on another post-tag state.
 4. **Overnight** — A QA team in another time zone validates the tag.
    Put new issues into the next morning's triage.
 
 
@@ -2,39 +2,48 @@
 // SPDX-License-Identifier: Apache-2.0
 
 /**
- * Generate a QA handoff summary for the upcoming release tag.
+ * Generate exact-range QA context for a release brief.
  *
- * Lists commits since the last tag, identifies risky areas touched,
- * and suggests test focus areas. Output is JSON.
- *
- * Usage: node --experimental-strip-types --no-warnings .agents/skills/nemoclaw-maintainer-day/scripts/handoff-summary.ts [--repo OWNER/REPO]
+ * Usage:
+ *   node --experimental-strip-types --no-warnings handoff-summary.ts \
+ *     --plan PATH --output PATH
  */
 
-import { isRiskyFile, run } from "./shared.ts";
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
 
-interface CommitInfo {
-  sha: string;
-  subject: string;
-}
+import { isRiskyFile } from "./shared.ts";
 
-interface HandoffOutput {
+export interface HandoffInput {
   previousTag: string;
+  previousTagCommit: string;
   targetVersion: string;
+  candidateCommit: string;
+}
+
+export interface HandoffOutput extends HandoffInput {
   commitCount: number;
-  commits: CommitInfo[];
-  riskyFilesTouched: string[];
+  riskyFileCount: number;
   riskyAreas: string[];
   suggestedTestFocus: string[];
 }
 
+type CommandRunner = (command: string, args: string[]) => string;
+
+const SEMVER = /^v\d+\.\d+\.\d+$/;
+const SHA = /^[0-9a-f]{40}$/;
+const INCOMPLETE = "TODO_RELEASE_BRIEF";
+
 const AREA_LABELS: Record<string, RegExp[]> = {
   "Installer / bootstrap": [
     /^install\.sh$/,
     /^setup\.sh$/,
     /^brev-setup\.sh$/,
     /^scripts\/.*\.sh$/,
   ],
-  "Onboarding / host glue": [/^bin\/lib\/onboard\.js$/, /^bin\/.*\.js$/],
+  "Onboarding / host glue": [/^bin\/lib\/onboard\.js$/, /^bin\/.*\.js$/, /^src\/lib\/onboard\//],
   "Sandbox / policy / SSRF": [
     /^nemoclaw\/src\/blueprint\//,
     /^nemoclaw-blueprint\//,
@@ -45,89 +54,231 @@ const AREA_LABELS: Record<string, RegExp[]> = {
   "Credentials / inference": [/credential/i, /inference/i],
 };
 
-function getLatestTag(): string {
-  const out = run("git", ["tag", "--sort=-v:refname"]);
-  if (!out) return "v0.0.0";
-  for (const line of out.split("\n")) {
-    if (/^v\d+\.\d+\.\d+$/.test(line.trim())) return line.trim();
+function run(command: string, args: string[]): string {
+  try {
+    return execFileSync(command, args, {
+      encoding: "utf8",
+      maxBuffer: 10 * 1024 * 1024,
+      stdio: ["ignore", "pipe", "pipe"],
+      timeout: 120_000,
+    }).trim();
+  } catch (error) {
+    const value = error as { stderr?: Buffer | string };
+    const detail = value.stderr ? String(value.stderr).trim() : "";
+    throw new Error(
+      [`Command failed: ${command} ${args.join(" ")}`, detail].filter(Boolean).join("\n"),
+    );
   }
-  return "v0.0.0";
 }
 
-function bumpPatch(tag: string): string {
-  const match = tag.match(/^v(\d+)\.(\d+)\.(\d+)$/);
-  if (!match) return "v0.0.1";
-  return `v${match[1]}.${match[2]}.${parseInt(match[3], 10) + 1}`;
+function validateInput(input: HandoffInput): void {
+  if (!SEMVER.test(input.previousTag)) throw new Error("previous tag must be vX.Y.Z");
+  if (!SEMVER.test(input.targetVersion)) throw new Error("target version must be vX.Y.Z");
+  if (!SHA.test(input.previousTagCommit)) {
+    throw new Error("previous tag commit must be a lowercase 40-character Git SHA");
+  }
+  if (!SHA.test(input.candidateCommit)) {
+    throw new Error("candidate commit must be a lowercase 40-character Git SHA");
+  }
 }
 
-function main(): void {
-  run("git", ["fetch", "origin", "--tags", "--prune"]);
-
-  const previousTag = getLatestTag();
-  const targetVersion = bumpPatch(previousTag);
-
-  // Commits since last tag
-  const logOut = run("git", ["log", "--oneline", "--format=%h %s", `${previousTag}..origin/main`]);
-  const commits: CommitInfo[] = [];
-  if (logOut) {
-    for (const line of logOut.split("\n")) {
-      const spaceIdx = line.indexOf(" ");
-      if (spaceIdx > 0) {
-        commits.push({
-          sha: line.slice(0, spaceIdx),
-          subject: line.slice(spaceIdx + 1),
-        });
-      }
-    }
+function suggestedFocus(areasHit: Set<string>, commitCount: number): string[] {
+  const focus: string[] = [];
+  if (areasHit.has("Installer / bootstrap")) focus.push("Fresh install and upgrade paths");
+  if (areasHit.has("Onboarding / host glue")) {
+    focus.push("Onboarding wizard and sandbox creation");
+  }
+  if (areasHit.has("Sandbox / policy / SSRF")) {
+    focus.push("Policy enforcement, network egress, and SSRF protections");
   }
+  if (areasHit.has("Workflow / enforcement")) {
+    focus.push("CI checks, pre-commit hooks, and DCO declarations");
+  }
+  if (areasHit.has("Credentials / inference")) {
+    focus.push("Credential storage and inference provider routing");
+  }
+  if (focus.length === 0 && commitCount > 0) {
+    focus.push("General smoke test; no risky areas were detected");
+  }
+  return focus;
+}
+
+export function buildHandoffSummary(
+  input: HandoffInput,
+  command: CommandRunner = run,
+): HandoffOutput {
+  validateInput(input);
 
-  // Files changed since last tag
-  const diffOut = run("git", ["diff", "--name-only", `${previousTag}..origin/main`]);
-  const changedFiles = diffOut
-    ? diffOut
+  const resolvedCandidate = command("git", ["rev-parse", `${input.candidateCommit}^{commit}`]);
+  if (resolvedCandidate !== input.candidateCommit) {
+    throw new Error(`candidate does not resolve to ${input.candidateCommit}`);
+  }
+  const mergeBase = command("git", ["merge-base", input.previousTagCommit, input.candidateCommit]);
+  if (mergeBase !== input.previousTagCommit) {
+    throw new Error("previous tag commit is not an ancestor of the candidate");
+  }
+
+  const range = `${input.previousTagCommit}..${input.candidateCommit}`;
+  const commitCountText = command("git", ["rev-list", "--count", range]);
+  if (!/^\d+$/u.test(commitCountText)) throw new Error("git returned an invalid commit count");
+  const commitCount = Number(commitCountText);
+  if (!Number.isSafeInteger(commitCount)) throw new Error("release range is too large");
+
+  const changed = command("git", ["diff", "--name-only", range]);
+  const changedFiles = changed
+    ? changed
         .split("\n")
-        .map((f) => f.trim())
+        .map((file) => file.trim())
         .filter(Boolean)
     : [];
   const riskyFilesTouched = changedFiles.filter(isRiskyFile);
-
-  // Map risky files to area labels
   const areasHit = new Set<string>();
   for (const file of riskyFilesTouched) {
     for (const [area, patterns] of Object.entries(AREA_LABELS)) {
-      if (patterns.some((re) => re.test(file))) {
-        areasHit.add(area);
-      }
+      if (patterns.some((pattern) => pattern.test(file))) areasHit.add(area);
     }
   }
-  const riskyAreas = [...areasHit];
-
-  // Suggest test focus based on areas
-  const suggestedTestFocus: string[] = [];
-  if (areasHit.has("Installer / bootstrap"))
-    suggestedTestFocus.push("Fresh install and upgrade paths");
-  if (areasHit.has("Onboarding / host glue"))
-    suggestedTestFocus.push("Onboarding wizard, sandbox creation");
-  if (areasHit.has("Sandbox / policy / SSRF"))
-    suggestedTestFocus.push("Policy enforcement, network egress, SSRF protections");
-  if (areasHit.has("Workflow / enforcement"))
-    suggestedTestFocus.push("CI checks, pre-commit hooks, DCO signing");
-  if (areasHit.has("Credentials / inference"))
-    suggestedTestFocus.push("Credential storage, inference provider routing");
-  if (suggestedTestFocus.length === 0 && commits.length > 0)
-    suggestedTestFocus.push("General smoke test — no risky areas touched");
-
-  const output: HandoffOutput = {
-    previousTag,
-    targetVersion,
-    commitCount: commits.length,
-    commits,
-    riskyFilesTouched,
-    riskyAreas,
-    suggestedTestFocus,
+
+  return {
+    ...input,
+    commitCount,
+    riskyFileCount: riskyFilesTouched.length,
+    riskyAreas: [...areasHit],
+    suggestedTestFocus: suggestedFocus(areasHit, commitCount),
   };
+}
+
+function text(value: string): string {
+  return value.replace(/([\\`*_[\]<>#])/g, "\\$1");
+}
 
-  console.log(JSON.stringify(output, null, 2));
+function code(value: string): string {
+  return `\`${value.replace(/`/g, "\\`")}\``;
+}
+
+function list(values: string[], empty: string): string[] {
+  return values.length ? values.map((value) => `- ${text(value)}`) : [`- ${empty}`];
+}
+
+export function renderHandoffMarkdown(summary: HandoffOutput): string {
+  const lines = [
+    `# NemoClaw ${summary.targetVersion} release brief`,
+    "",
+    "## Release range",
+    "",
+    `- Previous release: ${code(summary.previousTag)} at ${code(summary.previousTagCommit)}`,
+    `- Candidate: ${code(summary.candidateCommit)}`,
+    `- Commits: ${summary.commitCount}`,
+    `- Risky files detected: ${summary.riskyFileCount}`,
+    "",
+    "## QA context",
+    "",
+    "### Risky areas",
+    "",
+    ...list(summary.riskyAreas, "None detected."),
+    "",
+    "### Suggested test focus",
+    "",
+    ...list(summary.suggestedTestFocus, "No test focus was inferred."),
+    "",
+    "## Canonical release entry",
+    "",
+    `- Path: ${INCOMPLETE}`,
+    "- Entry:",
+    "",
+    INCOMPLETE,
+    "",
+    "## Pi documentation evidence",
+    "",
+    `- Pi candidate: ${code(summary.candidateCommit)}`,
+    `- Evidence: ${INCOMPLETE} (workflow and job URLs, artifact name, normalized approved-empty review, and managed-branch checks)`,
+    "",
+    "## Base and managed image evidence",
+    "",
+    `- Base-image candidate: ${code(summary.candidateCommit)}`,
+    `- Evidence: ${INCOMPLETE}`,
+    "",
+    "## Exact staging Brev Launchable evidence",
+    "",
+    `- Launchable candidate: ${code(summary.candidateCommit)}`,
+    `- Evidence: ${INCOMPLETE}`,
+    "",
+    "## General E2E decision",
+    "",
+    `- ${INCOMPLETE}: displayed run, requested runs, and maintainer choice.`,
+    "",
+    `Exceptions: ${INCOMPLETE}`,
+    "",
+  ];
+  return `${lines.join("\n")}\n`;
+}
+
+function parseArguments(argv: string[]): { output: string; plan: string } {
+  let output = "";
+  let plan = "";
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index];
+    if (argument === "--plan") {
+      plan = argv[++index] ?? "";
+      if (!plan || plan.startsWith("--")) throw new Error("--plan requires a path");
+    } else if (argument === "--output") {
+      output = argv[++index] ?? "";
+      if (!output || output.startsWith("--")) throw new Error("--output requires a path");
+    } else {
+      throw new Error(`unknown argument: ${argument ?? "missing"}`);
+    }
+  }
+  if (!plan || !output) throw new Error("usage: handoff-summary.ts --plan PATH --output PATH");
+  return { output, plan };
 }
 
-main();
+function readPlan(planPath: string): HandoffInput {
+  const value = JSON.parse(fs.readFileSync(path.resolve(planPath), "utf8")) as Record<
+    string,
+    unknown
+  >;
+  const expectedKeys = [
+    "nextTag",
+    "originMainCommit",
+    "originMainHeadline",
+    "previousTag",
+    "previousTagCommit",
+    "previousTagObject",
+  ];
+  if (JSON.stringify(Object.keys(value).sort()) !== JSON.stringify(expectedKeys)) {
+    throw new Error("release plan must contain exactly the six supported fields");
+  }
+  if (typeof value.originMainHeadline !== "string" || !value.originMainHeadline) {
+    throw new Error("release plan headline must be a nonempty string");
+  }
+  const input = {
+    previousTag: String(value.previousTag),
+    previousTagCommit: String(value.previousTagCommit),
+    targetVersion: String(value.nextTag),
+    candidateCommit: String(value.originMainCommit),
+  };
+  validateInput(input);
+  return input;
+}
+
+function main(): void {
+  const options = parseArguments(process.argv.slice(2));
+  const summary = buildHandoffSummary(readPlan(options.plan));
+  const output = path.resolve(options.output);
+  fs.mkdirSync(path.dirname(output), { recursive: true });
+  fs.writeFileSync(output, renderHandoffMarkdown(summary), { encoding: "utf8", flag: "wx" });
+  console.log(`Release brief written: ${output}`);
+}
+
+const invoked = process.argv[1]
+  ? pathToFileURL(path.resolve(process.argv[1])).href === import.meta.url
+  : false;
+if (invoked) {
+  try {
+    main();
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`handoff-summary: ${message}\n`);
+    process.exitCode = 1;
+  }
+}
@@ -21,6 +21,7 @@ export const RISKY_PATTERNS: RegExp[] = [
   /^scripts\/.*\.sh$/,
   /^bin\/lib\/onboard\.js$/,
   /^bin\/.*\.js$/,
+  /^src\/lib\/onboard\//,
   /^nemoclaw\/src\/blueprint\//,
   /^nemoclaw-blueprint\//,
   /^\.github\/workflows\//,