@fitlab-ai/agent-infra 0.9.2 → 0.9.3

package/lib/internal/agent-client.ts

@@ -7,12 +7,15 @@ import {
 } from '../agent-clients/config.ts';
 import { normalizeCustomTUIs } from '../agent-clients/custom-tuis.ts';
 import { renderNextStepCommands } from '../agent-clients/next-steps.ts';
+import { getAgentClientModelSelection } from '../agent-clients/registry.ts';
+import { isAgentClientId } from '../agent-clients/types.ts';
 
-const USAGE = 'Usage: agent-infra-internal agent-client next-steps --skill <skill-name> [--task-ref <NN|TASK-id>] [--format text|json]\n';
+const USAGE = 'Usage: agent-infra-internal agent-client <next-steps|model-selection> [options]\n';
 
 type ParsedArgs = Readonly<{
   skillName: string;
   taskRef?: string;
+  version?: string;
   format: 'text' | 'json';
 }>;
 
@@ -38,11 +41,12 @@ function parseArgs(args: string[]): ParsedArgs | null {
   }
   let skillName: string | undefined;
   let taskRef: string | undefined;
+  let version: string | undefined;
   let format: 'text' | 'json' = 'text';
   const seen = new Set<string>();
   for (let index = 1; index < args.length; index += 1) {
     const flag = args[index]!;
-    if (!['--skill', '--task-ref', '--format'].includes(flag)) {
+    if (!['--skill', '--task-ref', '--version', '--format'].includes(flag)) {
       failure('AGENT_CLIENT_PAYLOAD_INVALID', `unknown option '${flag}'`);
       return null;
     }
@@ -58,6 +62,7 @@ function parseArgs(args: string[]): ParsedArgs | null {
     seen.add(flag);
     if (flag === '--skill') skillName = value;
     if (flag === '--task-ref') taskRef = value;
+    if (flag === '--version') version = value;
     if (flag === '--format') {
       if (value !== 'text' && value !== 'json') {
         failure('AGENT_CLIENT_PAYLOAD_INVALID', "format must be 'text' or 'json'");
@@ -70,10 +75,59 @@ function parseArgs(args: string[]): ParsedArgs | null {
     failure('AGENT_CLIENT_PAYLOAD_INVALID', "option '--skill' is required");
     return null;
   }
-  return { skillName, ...(taskRef ? { taskRef } : {}), format };
+  return {
+    skillName,
+    ...(taskRef ? { taskRef } : {}),
+    ...(version ? { version } : {}),
+    format
+  };
 }
 
 function agentClient(args: string[] = []): void {
+  if (args[0] === 'model-selection') {
+    const values: Record<string, string> = {};
+    const seen = new Set<string>();
+    for (let index = 1; index < args.length; index += 1) {
+      const flag = args[index]!;
+      if (!['--client', '--format'].includes(flag) || seen.has(flag)) {
+        failure('AGENT_CLIENT_PAYLOAD_INVALID', `invalid or duplicate option '${flag}'`);
+        return;
+      }
+      const value = args[++index];
+      if (!value || value.startsWith('--')) {
+        failure('AGENT_CLIENT_PAYLOAD_INVALID', `option '${flag}' requires a value`);
+        return;
+      }
+      seen.add(flag);
+      values[flag] = value;
+    }
+    const client = values['--client'];
+    const format = values['--format'] ?? 'text';
+    if (!isAgentClientId(client) || !['text', 'json'].includes(format)) {
+      failure('AGENT_CLIENT_PAYLOAD_INVALID', 'model-selection requires a known --client and text|json format');
+      return;
+    }
+    const context = getAgentClientModelSelection(client);
+    if (format === 'json') {
+      process.stdout.write(`${JSON.stringify({
+        status: 'resolved', changed: false, client, context, error: null
+      })}\n`);
+      return;
+    }
+    if (context.kind === 'interactive-only') {
+      process.stdout.write(`Model selection: interactive-only\nCommand: ${context.command}\n${context.guidance}\n`);
+    } else {
+      process.stdout.write(`Model selection: ${context.completeness} catalog\nSource: ${context.source}\n`);
+      for (const model of context.models) {
+        const efforts = model.reasoningEfforts?.length
+          ? ` (${model.reasoningEfforts.join(', ')})`
+          : '';
+        process.stdout.write(`- ${model.id}${efforts}\n`);
+      }
+      if (context.guidance) process.stdout.write(`${context.guidance}\n`);
+    }
+    return;
+  }
   const parsed = parseArgs(args);
   if (!parsed || process.exitCode) return;
 
@@ -98,7 +152,8 @@ function agentClient(args: string[] = []): void {
       state: clients.state,
       customTUIs: custom.items,
       skillName: parsed.skillName,
-      ...(parsed.taskRef ? { taskRef: parsed.taskRef } : {})
+      ...(parsed.taskRef ? { taskRef: parsed.taskRef } : {}),
+      ...(parsed.version ? { version: parsed.version } : {})
     });
     if (parsed.format === 'json') {
       process.stdout.write(`${JSON.stringify({

package/lib/internal/git-workflow.ts

@@ -1,5 +1,5 @@
 import fs from 'node:fs';
-import { commitExplicitPaths, inspectGitWorkflow, pushGitRefs } from '../git/workflow.ts';
+import { commitExplicitPaths, inspectGitWorkflow, pushGitRefs, pushRebasedBranch } from '../git/workflow.ts';
 import { compareReviewTrees, snapshotReview } from '../git/review-snapshot.ts';
 import { resolvePostReviewGlobs } from '../task/review-fingerprint.ts';
 
@@ -23,6 +23,10 @@ function gitWorkflow(args: string[] = []): void {
     const inputIndex = rest.indexOf('--input');
     const input = inputIndex >= 0 && rest[inputIndex + 1] ? JSON.parse(fs.readFileSync(rest[inputIndex + 1]!, 'utf8')) : null;
     result = input ? pushGitRefs({ cwd: cwd ?? process.cwd(), ...input }) : { status: 'failed', changed: false, error: { code: 'GIT_INPUT_REQUIRED', message: '--input JSON file is required' } };
+  } else if (action === 'push-rebased') {
+    const inputIndex = rest.indexOf('--input');
+    const input = inputIndex >= 0 && rest[inputIndex + 1] ? JSON.parse(fs.readFileSync(rest[inputIndex + 1]!, 'utf8')) : null;
+    result = input ? pushRebasedBranch({ cwd: cwd ?? process.cwd(), ...input }) : { status: 'failed', changed: false, error: { code: 'GIT_INPUT_REQUIRED', message: '--input JSON file is required' } };
   } else if (action === 'snapshot' || action === 'compare-trees') {
     const inputIndex = rest.indexOf('--input');
     const input = inputIndex >= 0 && rest[inputIndex + 1] ? JSON.parse(fs.readFileSync(rest[inputIndex + 1]!, 'utf8')) : null;

package/lib/internal/platform-checks.ts

@@ -2,9 +2,9 @@ import path from 'node:path';
 
 import {
   fetchPlatformCheckLogs,
-  inspectRequiredChecks,
+  inspectPullRequestReadiness,
   resolvePlatformCheckRun,
-  watchPlatformChecks
+  watchPullRequestReadiness
 } from '../platform/pr-checks.ts';
 import type { ChecksResult } from '../platform/pr-checks.ts';
 
@@ -70,7 +70,7 @@ async function platformChecks(args: string[] = []): Promise<void> {
   };
   const unexpected = Object.keys(values).find((name) => !allowed[operation]!.includes(name));
   if (unexpected) { fail(`${operation} does not accept --${unexpected}`); return; }
-  if (operation === 'inspect') { finish(inspectRequiredChecks(taskRef, { cwd })); return; }
+  if (operation === 'inspect') { finish(inspectPullRequestReadiness(taskRef, { cwd })); return; }
   if (operation === 'resolve-run') {
     if (!values.checkName) { fail('resolve-run requires --check-name'); return; }
     finish(resolvePlatformCheckRun(taskRef, { cwd, checkName: values.checkName, detailsUrl: values.detailsUrl }));
@@ -91,7 +91,7 @@ async function platformChecks(args: string[] = []): Promise<void> {
   process.once('SIGINT', abort);
   process.once('SIGTERM', abort);
   try {
-    finish(await watchPlatformChecks(taskRef, { cwd, intervalSeconds, deadlineSeconds, signal: controller.signal }));
+    finish(await watchPullRequestReadiness(taskRef, { cwd, intervalSeconds, deadlineSeconds, signal: controller.signal }));
   } finally {
     process.removeListener('SIGINT', abort);
     process.removeListener('SIGTERM', abort);

package/lib/internal/platform-comment.ts

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
+import { normalizeAgentToken, AGENT_USAGE_HINT } from '../agent-clients/tokens.ts';
 import {
   checkPlatformCommentOwner,
   listPlatformComments,
@@ -8,9 +9,11 @@ import {
 } from '../platform/issue-comments.ts';
 import type { CommentKind } from '../platform/issue-comments.ts';
 import type { PlatformResult } from '../platform/types.ts';
+import { backfillCompletionComments } from '../platform/completion-backfill.ts';
 
 const USAGE = `Usage: agent-infra-internal platform-comment list --issue <N> [--cwd <path>]
        agent-infra-internal platform-comment owner <task-ref> [--cwd <path>]
+       agent-infra-internal platform-comment backfill <task-ref> --agent <agent> [--cwd <path>]
        agent-infra-internal platform-comment sync <task-ref> --kind <kind> --agent <agent> [--artifact <file>] [--body-file <path|->] [--status-label <label>] [--backfill] [--cwd <path>]
 `;
 
@@ -52,7 +55,7 @@ function readBodyFile(value: string, cwd: string): string {
 function platformComment(args: string[] = []): void {
   if (args[0] === '--help' || args[0] === '-h') { process.stdout.write(USAGE); return; }
   const operation = args[0];
-  if (!operation || !['list', 'owner', 'sync'].includes(operation)) { fail('a valid operation is required'); return; }
+  if (!operation || !['list', 'owner', 'backfill', 'sync'].includes(operation)) { fail('a valid operation is required'); return; }
   const hasTaskRef = operation !== 'list';
   const taskRef = hasTaskRef ? args[1] : undefined;
   if (hasTaskRef && (!taskRef || taskRef.startsWith('--'))) { fail(`${operation} requires a task ref`); return; }
@@ -73,10 +76,22 @@ function platformComment(args: string[] = []): void {
     finish(checkPlatformCommentOwner(taskRef!, { cwd }));
     return;
   }
+  if (operation === 'backfill') {
+    const unexpected = Object.keys(parsed.values).find((key) => !['cwd', 'agent'].includes(key));
+    if (unexpected) { fail(`backfill does not accept '--${unexpected}'`); return; }
+    const agent = parsed.values.agent;
+    if (typeof agent !== 'string' || !agent) { fail('backfill requires --agent'); return; }
+    const normalizedAgent = normalizeAgentToken(agent);
+    if (!normalizedAgent) { fail(`invalid --agent '${agent}': ${AGENT_USAGE_HINT}`); return; }
+    finish(backfillCompletionComments(taskRef!, { cwd, agent: normalizedAgent }));
+    return;
+  }
   const kind = parsed.values.kind;
   const agent = parsed.values.agent;
   if (!['task', 'artifact', 'summary', 'cancel'].includes(String(kind))) { fail('sync requires a valid --kind'); return; }
   if (typeof agent !== 'string' || !agent) { fail('sync requires --agent'); return; }
+  const normalizedAgent = normalizeAgentToken(agent);
+  if (!normalizedAgent) { fail(`invalid --agent '${agent}': ${AGENT_USAGE_HINT}`); return; }
   if (kind === 'artifact' && typeof parsed.values.artifact !== 'string') { fail('artifact sync requires --artifact'); return; }
   if ((kind === 'summary' || kind === 'cancel') && typeof parsed.values.bodyFile !== 'string') { fail(`${kind} sync requires --body-file`); return; }
   let body: string | undefined;
@@ -88,7 +103,7 @@ function platformComment(args: string[] = []): void {
   }
   finish(syncPlatformComment(taskRef!, {
     kind: kind as CommentKind,
-    agent,
+    agent: normalizedAgent,
     artifact: typeof parsed.values.artifact === 'string' ? parsed.values.artifact : undefined,
     body,
     backfill: parsed.values.backfill === true,

package/lib/internal/platform-issue.ts

@@ -1,5 +1,6 @@
 import path from 'node:path';
 
+import { normalizeAgentToken, AGENT_USAGE_HINT } from '../agent-clients/tokens.ts';
 import {
   bindPlatformIssue,
   createPlatformIssue,
@@ -76,6 +77,9 @@ function platformIssue(args: string[] = []): void {
   if (unexpected) { fail(`${operation} does not accept --${unexpected}`); return; }
   if (operation === 'inspect') { finish(inspectPlatformIssue(taskRef, { cwd })); return; }
   if (typeof values.agent !== 'string' || !values.agent) { fail(`${operation} requires --agent`); return; }
+  const agent = normalizeAgentToken(values.agent);
+  if (!agent) { fail(`invalid --agent '${values.agent}': ${AGENT_USAGE_HINT}`); return; }
+  values.agent = agent;
   if (operation === 'create') {
     finish(createPlatformIssue(taskRef, { cwd, agent: values.agent, dryRun: values.dryRun === true })); return;
   }

package/lib/internal/platform-pr-review.ts

@@ -0,0 +1,104 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { inspectPlatformPullRequestByNumber } from '../platform/pull-requests.ts';
+import { listPrReviews, publishPrReview } from '../platform/pr-review.ts';
+import type { PrReviewEvent } from '../platform/pr-review.ts';
+import type { PlatformResult } from '../platform/types.ts';
+
+const USAGE = `Usage: agent-infra-internal platform-pr-review inspect --pr <N> [--cwd <path>]
+       agent-infra-internal platform-pr-review list --pr <N> [--cwd <path>]
+       agent-infra-internal platform-pr-review publish --pr <N> --scope <taskId|pr{N}> --round <N> --commit <sha> --event <COMMENT|APPROVE|REQUEST_CHANGES> --body-file <path|-> [--dry-run] [--cwd <path>]
+`;
+
+const BOOLEAN_FLAGS = new Set(['--dry-run']);
+const VALUE_FLAGS = new Set(['--cwd', '--pr', '--scope', '--round', '--commit', '--event', '--body-file']);
+
+function key(flag: string): string {
+  return flag.slice(2).replace(/-([a-z])/g, (_, letter: string) => letter.toUpperCase());
+}
+
+function fail(message: string): void {
+  process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'PR_REVIEW_PAYLOAD_INVALID', message } })}\n`);
+  process.stderr.write(USAGE);
+  process.exitCode = 1;
+}
+
+function finish(output: PlatformResult): void {
+  process.stdout.write(`${JSON.stringify(output)}\n`);
+  if (output.status === 'failed') process.exitCode = 1;
+  if (output.status === 'blocked') process.exitCode = 2;
+}
+
+function parse(args: string[], start: number) {
+  const values: Record<string, string | boolean> = {};
+  const seen = new Set<string>();
+  for (let index = start; index < args.length; index += 1) {
+    const flag = args[index]!;
+    if (!BOOLEAN_FLAGS.has(flag) && !VALUE_FLAGS.has(flag)) return { values, error: `unknown option '${flag}'` };
+    if (seen.has(flag)) return { values, error: `duplicate option '${flag}'` };
+    seen.add(flag);
+    if (BOOLEAN_FLAGS.has(flag)) { values[key(flag)] = true; continue; }
+    const value = args[++index];
+    if (value === undefined || value.startsWith('--')) return { values, error: `option '${flag}' requires a value` };
+    values[key(flag)] = value;
+  }
+  return { values };
+}
+
+function readBodyFile(value: string, cwd: string): string {
+  return value === '-' ? fs.readFileSync(0, 'utf8') : fs.readFileSync(path.resolve(cwd, value), 'utf8');
+}
+
+function platformPrReview(args: string[] = []): void {
+  if (args[0] === '--help' || args[0] === '-h') { process.stdout.write(USAGE); return; }
+  const operation = args[0];
+  if (!operation || !['inspect', 'list', 'publish'].includes(operation)) { fail('a valid operation is required'); return; }
+  const parsed = parse(args, 1);
+  if (parsed.error) { fail(parsed.error); return; }
+  const values = parsed.values;
+  const cwd = path.resolve(typeof values.cwd === 'string' ? values.cwd : process.cwd());
+  const allowed: Record<string, string[]> = {
+    inspect: ['cwd', 'pr'],
+    list: ['cwd', 'pr'],
+    publish: ['cwd', 'pr', 'scope', 'round', 'commit', 'event', 'bodyFile', 'dryRun']
+  };
+  const unexpected = Object.keys(values).find((name) => !allowed[operation]!.includes(name));
+  if (unexpected) { fail(`${operation} does not accept --${unexpected}`); return; }
+  const pr = Number(values.pr);
+  if (!Number.isInteger(pr) || pr <= 0) { fail(`${operation} requires a positive --pr`); return; }
+  if (operation === 'inspect') {
+    finish(inspectPlatformPullRequestByNumber(pr, { cwd }));
+    return;
+  }
+  if (operation === 'list') {
+    finish(listPrReviews(pr, { cwd }));
+    return;
+  }
+  const scope = typeof values.scope === 'string' ? values.scope : '';
+  const round = Number(values.round);
+  const commit = typeof values.commit === 'string' ? values.commit : '';
+  const event = values.event as string;
+  if (!scope || !/^(?:pr\d+|TASK-\d{8}-\d{6})$/.test(scope)) { fail('publish requires --scope <taskId|pr{N}>'); return; }
+  if (!Number.isInteger(round) || round <= 0) { fail('publish requires a positive --round'); return; }
+  if (!/^[0-9a-f]{7,40}$/i.test(commit)) { fail('publish requires --commit <sha>'); return; }
+  if (!['COMMENT', 'APPROVE', 'REQUEST_CHANGES'].includes(event)) { fail('publish requires --event <COMMENT|APPROVE|REQUEST_CHANGES>'); return; }
+  if (typeof values.bodyFile !== 'string') { fail('publish requires --body-file'); return; }
+  let body: string;
+  try {
+    body = readBodyFile(values.bodyFile, cwd);
+  } catch (error) {
+    fail(`unable to read body file: ${error instanceof Error ? error.message : String(error)}`);
+    return;
+  }
+  finish(publishPrReview({
+    cwd,
+    prNumber: pr,
+    identity: { scope, round, commitSha: commit },
+    event: event as PrReviewEvent,
+    body,
+    dryRun: values.dryRun === true
+  }));
+}
+
+export { platformPrReview };

package/lib/internal/platform-pr.ts

@@ -1,10 +1,12 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
+import { normalizeAgentToken, AGENT_USAGE_HINT } from '../agent-clients/tokens.ts';
 import {
   bindPlatformPullRequest,
   createPlatformPullRequest,
   inspectPlatformPullRequest,
+  resolveExternalPullRequest,
   syncPlatformPullRequest
 } from '../platform/pull-requests.ts';
 import type { PullRequestResult } from '../platform/pull-requests.ts';
@@ -12,6 +14,7 @@ import { summaryContext, syncPullRequestSummary } from '../platform/pr-summary.t
 import type { PlatformResult } from '../platform/types.ts';
 
 const USAGE = `Usage: agent-infra-internal platform-pr inspect <task-ref> [--cwd <path>]
+       agent-infra-internal platform-pr resolve-external <task-ref> --agent <agent> [--pr <N>] [--dry-run] [--cwd <path>]
        agent-infra-internal platform-pr create <task-ref> --agent <agent> --base <branch> --head <branch> --title-file <path|-> --body-file <path|-> [--draft] [--dry-run] [--cwd <path>]
        agent-infra-internal platform-pr bind <task-ref> --pr <N> --agent <agent> [--dry-run] [--cwd <path>]
        agent-infra-internal platform-pr sync <task-ref> --agent <agent> [--metadata] [--closing-issue] [--dry-run] [--cwd <path>]
@@ -61,7 +64,7 @@ function readFile(value: string, cwd: string): string {
 function platformPr(args: string[] = []): void {
   if (args[0] === '--help' || args[0] === '-h') { process.stdout.write(USAGE); return; }
   const operation = args[0];
-  if (!operation || !['inspect', 'create', 'bind', 'sync', 'summary-context', 'summary-sync'].includes(operation)) { fail('a valid operation is required'); return; }
+  if (!operation || !['inspect', 'resolve-external', 'create', 'bind', 'sync', 'summary-context', 'summary-sync'].includes(operation)) { fail('a valid operation is required'); return; }
   const taskRef = args[1];
   if (!taskRef || taskRef.startsWith('--')) { fail(`${operation} requires a task ref`); return; }
   const parsed = parse(args, 2);
@@ -70,6 +73,7 @@ function platformPr(args: string[] = []): void {
   const cwd = path.resolve(typeof values.cwd === 'string' ? values.cwd : process.cwd());
   const allowed: Record<string, string[]> = {
     inspect: ['cwd'],
+    'resolve-external': ['cwd', 'agent', 'pr', 'dryRun'],
     create: ['cwd', 'agent', 'base', 'head', 'titleFile', 'bodyFile', 'draft', 'dryRun'],
     bind: ['cwd', 'agent', 'pr', 'dryRun'],
     sync: ['cwd', 'agent', 'metadata', 'closingIssue', 'dryRun'],
@@ -81,6 +85,15 @@ function platformPr(args: string[] = []): void {
   if (operation === 'inspect') { finish(inspectPlatformPullRequest(taskRef, { cwd })); return; }
   if (operation === 'summary-context') { finish(summaryContext(taskRef, { cwd })); return; }
   if (typeof values.agent !== 'string' || !values.agent) { fail(`${operation} requires --agent`); return; }
+  const agent = normalizeAgentToken(values.agent);
+  if (!agent) { fail(`invalid --agent '${values.agent}': ${AGENT_USAGE_HINT}`); return; }
+  values.agent = agent;
+  if (operation === 'resolve-external') {
+    const pr = values.pr === undefined ? undefined : Number(values.pr);
+    if (pr !== undefined && (!Number.isInteger(pr) || pr <= 0)) { fail('resolve-external requires a positive --pr'); return; }
+    finish(resolveExternalPullRequest(taskRef, { cwd, agent: values.agent, pr, dryRun: values.dryRun === true }));
+    return;
+  }
   if (operation === 'bind') {
     const pr = Number(values.pr);
     if (!Number.isInteger(pr) || pr <= 0) { fail('bind requires a positive --pr'); return; }

package/lib/internal/platform-release-notes.ts

@@ -1,11 +1,34 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
-import { publishReleaseNotes, releaseNoteContext } from '../platform/release-notes.ts';
+import { publishReleaseNotes, releaseNoteContext, stageReleaseNotes } from '../platform/release-notes.ts';
 
-function option(args: string[], name: string): string | null {
-  const index = args.indexOf(name);
-  return index >= 0 && args[index + 1] ? args[index + 1]! : null;
+type ParsedOptions = Readonly<{ values: ReadonlyMap<string, string>; switches: ReadonlySet<string> }>;
+
+function parseOptions(
+  args: string[],
+  valueFlags: readonly string[],
+  switchFlags: readonly string[] = []
+): ParsedOptions | null {
+  const values = new Map<string, string>();
+  const switches = new Set<string>();
+  for (let index = 0; index < args.length; index += 1) {
+    const flag = args[index]!;
+    if (values.has(flag) || switches.has(flag)) return null;
+    if (switchFlags.includes(flag)) {
+      switches.add(flag);
+      continue;
+    }
+    if (!valueFlags.includes(flag)) return null;
+    const value = args[++index];
+    if (!value || value.startsWith('--')) return null;
+    values.set(flag, value);
+  }
+  return { values, switches };
+}
+
+function invalidInput(message: string) {
+  return { status: 'failed', changed: false, error: { code: 'RELEASE_NOTES_INPUT_INVALID', message, retryable: false } };
 }
 
 function finish(result: { status: string; [key: string]: unknown }): void {
@@ -15,21 +38,40 @@ function finish(result: { status: string; [key: string]: unknown }): void {
 
 function platformReleaseNotes(args: string[] = []): void {
   const [action, ...rest] = args;
-  const cwd = path.resolve(option(rest, '--cwd') || process.cwd());
   if (action === 'context') {
-    const historyRaw = option(rest, '--history-limit');
+    const parsed = parseOptions(rest, ['--cwd', '--history-limit', '--from-tag', '--to-tag', '--branch']);
+    if (!parsed) return finish(invalidInput('invalid context options'));
+    const cwd = path.resolve(parsed.values.get('--cwd') || process.cwd());
+    const historyRaw = parsed.values.get('--history-limit') ?? null;
     finish(releaseNoteContext({
-      fromTag: option(rest, '--from-tag') || '',
-      toTag: option(rest, '--to-tag') || '',
-      branch: option(rest, '--branch') || '',
+      fromTag: parsed.values.get('--from-tag') || '',
+      toTag: parsed.values.get('--to-tag') || '',
+      branch: parsed.values.get('--branch') || '',
       historyLimit: historyRaw === null ? undefined : Number(historyRaw)
     }, { cwd }));
     return;
   }
+  if (action === 'stage') {
+    const parsed = parseOptions(rest, ['--cwd', '--notes-file']);
+    if (!parsed) return finish(invalidInput('invalid stage options'));
+    const notesFile = parsed.values.get('--notes-file');
+    if (!notesFile) return finish(invalidInput('notes-file is required'));
+    finish(stageReleaseNotes(
+      { notesFile },
+      { cwd: path.resolve(parsed.values.get('--cwd') || process.cwd()) }
+    ));
+    return;
+  }
   if (action === 'publish') {
-    const notesPath = option(rest, '--notes-file');
+    const parsed = parseOptions(
+      rest,
+      ['--cwd', '--notes-file', '--tag', '--title', '--expected-sha256'],
+      ['--dry-run']
+    );
+    if (!parsed) return finish(invalidInput('invalid publish options'));
+    const notesPath = parsed.values.get('--notes-file');
     if (!notesPath) {
-      finish({ status: 'failed', changed: false, error: { code: 'RELEASE_NOTES_INPUT_INVALID', message: 'notes-file is required', retryable: false } });
+      finish(invalidInput('notes-file is required'));
       return;
     }
     let resolvedNotesPath = notesPath;
@@ -39,17 +81,18 @@ function platformReleaseNotes(args: string[] = []): void {
     }
     try {
       finish(publishReleaseNotes({
-        tag: option(rest, '--tag') || '',
-        title: option(rest, '--title') || option(rest, '--tag') || '',
+        tag: parsed.values.get('--tag') || '',
+        title: parsed.values.get('--title') || parsed.values.get('--tag') || '',
         notesFile: resolvedNotesPath,
-        dryRun: rest.includes('--dry-run')
-      }, { cwd }));
+        expectedSha256: parsed.values.get('--expected-sha256') || '',
+        dryRun: parsed.switches.has('--dry-run')
+      }, { cwd: path.resolve(parsed.values.get('--cwd') || process.cwd()) }));
     } finally {
       if (notesPath === '-') fs.rmSync(resolvedNotesPath, { force: true });
     }
     return;
   }
-  finish({ status: 'failed', changed: false, error: { code: 'RELEASE_NOTES_INPUT_INVALID', message: 'Usage: platform-release-notes context|publish', retryable: false } });
+  finish(invalidInput('Usage: platform-release-notes context|stage|publish'));
 }
 
 export { platformReleaseNotes };

package/lib/internal/pr-review-grade.ts

@@ -0,0 +1,130 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import {
+  collectHostCandidates,
+  decide,
+  deriveTaskIssueMatches,
+  extractClosingIssueNumbers,
+  resolveHostFromCandidates
+} from '../pr-review/evidence-grading.ts';
+import type { DecisionRecord, HostResolution } from '../pr-review/evidence-grading.ts';
+import { inspectPlatformPullRequestByNumber } from '../platform/pull-requests.ts';
+import { verifyInProcess } from '../task/verification-engine.ts';
+
+const USAGE = `Usage: agent-infra-internal pr-review-grade decide --input-file <path|-> [--cwd <path>]
+       agent-infra-internal pr-review-grade resolve-host --pr <N> [--cwd <path>]
+       agent-infra-internal pr-review-grade verify-artifact --artifact-file <path> [--cwd <path>]
+`;
+
+function fail(message: string): void {
+  process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'PR_REVIEW_GRADE_INVALID', message } })}\n`);
+  process.stderr.write(USAGE);
+  process.exitCode = 1;
+}
+
+function finish(result: unknown, exitCode = 0): void {
+  process.stdout.write(`${JSON.stringify(result)}\n`);
+  if (exitCode !== 0) process.exitCode = exitCode;
+}
+
+function parseFlags(args: string[], start: number): { values: Record<string, string | boolean>; error?: string } {
+  const values: Record<string, string | boolean> = {};
+  const seen = new Set<string>();
+  for (let index = start; index < args.length; index += 1) {
+    const flag = args[index]!;
+    if (!['--input-file', '--artifact-file', '--cwd', '--pr'].includes(flag)) {
+      return { values, error: `unknown option '${flag}'` };
+    }
+    if (seen.has(flag)) return { values, error: `duplicate option '${flag}'` };
+    seen.add(flag);
+    const value = args[++index];
+    if (value === undefined || value.startsWith('--')) return { values, error: `option '${flag}' requires a value` };
+    values[flag.slice(2).replace(/-([a-z])/g, (_, letter: string) => letter.toUpperCase())] = value;
+  }
+  return { values };
+}
+
+function readInput(value: string, cwd: string): string {
+  return value === '-' ? fs.readFileSync(0, 'utf8') : fs.readFileSync(path.resolve(cwd, value), 'utf8');
+}
+
+function prReviewGrade(args: string[] = []): void {
+  if (args[0] === '--help' || args[0] === '-h') { process.stdout.write(USAGE); return; }
+  const operation = args[0];
+  if (!operation || !['decide', 'resolve-host', 'verify-artifact'].includes(operation)) { fail('a valid operation is required'); return; }
+  const parsed = parseFlags(args, 1);
+  if (parsed.error) { fail(parsed.error); return; }
+  const values = parsed.values;
+  const cwd = path.resolve(typeof values.cwd === 'string' ? values.cwd : process.cwd());
+  const allowed: Record<string, string[]> = {
+    decide: ['cwd', 'inputFile'],
+    'resolve-host': ['cwd', 'pr'],
+    'verify-artifact': ['cwd', 'artifactFile']
+  };
+  const unexpected = Object.keys(values).find((key) => !allowed[operation]!.includes(key));
+  if (unexpected) { fail(`${operation} does not accept '--${unexpected}'`); return; }
+
+  if (operation === 'decide') {
+    if (typeof values.inputFile !== 'string') { fail('decide requires --input-file'); return; }
+    let input: unknown;
+    try {
+      input = JSON.parse(readInput(values.inputFile, cwd));
+    } catch (error) {
+      fail(`unable to read decide input: ${error instanceof Error ? error.message : String(error)}`);
+      return;
+    }
+    try {
+      const record: DecisionRecord = decide(input as Parameters<typeof decide>[0]);
+      finish(record);
+    } catch (error) {
+      const code = error && typeof error === 'object' && 'code' in error ? String(error.code) : 'DECIDE_FAILED';
+      finish({ status: 'failed', changed: false, error: { code, message: error instanceof Error ? error.message : String(error) } }, 1);
+    }
+    return;
+  }
+
+  if (operation === 'resolve-host') {
+    const pr = Number(values.pr);
+    if (!Number.isInteger(pr) || pr <= 0) { fail('resolve-host requires a positive --pr'); return; }
+    const inspected = inspectPlatformPullRequestByNumber(pr, { cwd });
+    if (!inspected.pullRequest) {
+      finish({
+        status: 'failed', changed: false, host: null, candidates: [], closingIssues: [],
+        error: inspected.error ?? { code: 'PR_INSPECTION_INVALID', message: 'unable to inspect the pull request', retryable: false }
+      }, inspected.status === 'blocked' ? 2 : 1);
+      return;
+    }
+    const closingIssues = extractClosingIssueNumbers(inspected.pullRequest.body);
+    const candidates = collectHostCandidates({ prNumber: pr, closingIssues, workspaceRoot: cwd });
+    const host: HostResolution = resolveHostFromCandidates(candidates);
+    finish({
+      status: 'ok', changed: false,
+      pr: { number: pr, baseSha: inspected.pullRequest.base.sha, headSha: inspected.pullRequest.head.sha, state: inspected.pullRequest.state },
+      closingIssues, candidates, host,
+      taskIssueMatches: deriveTaskIssueMatches(host, closingIssues), error: null
+    });
+    return;
+  }
+
+  if (typeof values.artifactFile !== 'string') { fail('verify-artifact requires --artifact-file'); return; }
+  const artifactPath = path.resolve(cwd, values.artifactFile);
+  let result: Record<string, unknown>;
+  try {
+    result = verifyInProcess({
+      mode: 'checks',
+      skillName: 'review-pr',
+      taskDir: path.dirname(artifactPath),
+      artifactFile: path.basename(artifactPath),
+      checks: ['artifact'],
+      repositoryRoot: cwd
+    }) as Record<string, unknown>;
+  } catch (error) {
+    finish({ status: 'failed', changed: false, error: { code: 'VERIFY_ARTIFACT_INVALID', message: error instanceof Error ? error.message : String(error) } }, 1);
+    return;
+  }
+  const status = result.status as 'pass' | 'fail' | 'blocked';
+  finish(result, ({ pass: 0, fail: 1, blocked: 2 } as const)[status]);
+}
+
+export { prReviewGrade };