forgeos 0.1.0-alpha.37 → 0.1.0-alpha.39

package/src/forge/cli/docs.ts

@@ -47,7 +47,7 @@ const CONTENT_CHECKS: Array<{ file: string; contains: string[] }> = [
   { file: "docs/agent-workflow.md", contains: ["forge do", "forge status --json", "forge handoff --json"] },
   { file: "docs/troubleshooting.md", contains: ["FORGE_DELTA_BUSY", "waiting-for-user-trust", "Studio target preview issues"] },
   { file: "docs/release.md", contains: ["release:verify-public-alpha", "Documentation checklist"] },
-  { file: "docs/self-host.md", contains: ["forge self-host check"] },
+  { file: "docs/self-host.md", contains: ["forge deploy check --production --json"] },
 ];
 
 function read(workspaceRoot: string, relative: string): string | null {

package/src/forge/cli/doctor.ts

@@ -30,6 +30,41 @@ export interface PgliteDoctorResult {
   ok: boolean;
   inspection: PgliteStoreInspection;
   checks: DoctorCheck[];
+  dbGuide: LocalDbModeGuide;
+  nextActions: string[];
+  exitCode: 0 | 1;
+}
+
+export interface LocalDbModeGuide {
+  recommendedForCurrentState: "pglite" | "memory" | "stop-active-process" | "repair-pglite";
+  memory: {
+    command: string;
+    useWhen: string[];
+    tradeoff: string;
+  };
+  pglite: {
+    command: string;
+    useWhen: string[];
+    tradeoff: string;
+  };
+  repair?: {
+    command: string;
+    safeWhen: string;
+    preservesDataByArchiving: boolean;
+  };
+}
+
+export interface RuntimeDoctorResult {
+  ok: boolean;
+  checks: DoctorCheck[];
+  dev: {
+    pidFile: string;
+    logFile: string;
+    running: boolean;
+    pid?: number;
+  };
+  pglite: PgliteStoreInspection;
+  dbGuide: LocalDbModeGuide;
   nextActions: string[];
   exitCode: 0 | 1;
 }
@@ -106,6 +141,50 @@ function frontendDevAuthChecks(
     }));
 }
 
+function buildLocalDbModeGuide(workspaceRoot: string, pglite: PgliteStoreInspection): LocalDbModeGuide {
+  const memoryCommand = "forge dev --db memory --json";
+  const pgliteCommand = "forge dev --db pglite --json";
+  const repairCommand = "forge db repair --local --adapter pglite --json";
+  const recommendedForCurrentState: LocalDbModeGuide["recommendedForCurrentState"] =
+    pglite.state === "active"
+      ? "stop-active-process"
+      : pglite.state === "aborted" || pglite.state === "unhealthy"
+        ? "repair-pglite"
+        : pglite.openable
+          ? "pglite"
+          : "memory";
+  return normalizeForgeCliCommandsInValue(workspaceRoot, {
+    recommendedForCurrentState,
+    memory: {
+      command: memoryCommand,
+      useWhen: [
+        "you need a clean isolated smoke test",
+        "PGlite is active, aborted, or suspected corrupt",
+        "you do not need local data to persist after the process exits",
+      ],
+      tradeoff: "Fast and isolated, but data disappears when the dev process exits.",
+    },
+    pglite: {
+      command: pgliteCommand,
+      useWhen: [
+        "you want local data to persist between dev runs",
+        "you are reproducing real database behavior more closely than memory",
+        "doctor pglite reports the store is missing or healthy",
+      ],
+      tradeoff: "Persists local state, but a stale/corrupt .forge/pglite store can require repair.",
+    },
+    ...(pglite.state === "aborted" || pglite.state === "unhealthy"
+      ? {
+          repair: {
+            command: repairCommand,
+            safeWhen: "PGlite is not owned by a live forge dev process and doctor reports aborted/unhealthy.",
+            preservesDataByArchiving: true,
+          },
+        }
+      : {}),
+  }) as LocalDbModeGuide;
+}
+
 export async function runDoctorCommand(options: {
   workspaceRoot: string;
 }): Promise<DoctorResult> {
@@ -242,15 +321,116 @@ export async function runPgliteDoctorCommand(options: {
   }
 
   const exitOk = checks.every((check) => check.ok || check.severity === "warning");
+  const dbGuide = buildLocalDbModeGuide(options.workspaceRoot, inspection);
   return normalizeForgeCliCommandsInValue(options.workspaceRoot, {
     ok: exitOk,
     inspection,
     checks,
+    dbGuide,
     nextActions: inspection.nextActions,
     exitCode: exitOk ? 0 : 1,
   });
 }
 
+function isProcessRunning(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error instanceof Error && "code" in error && error.code === "EPERM";
+  }
+}
+
+function readPid(path: string): number | undefined {
+  const text = nodeFileSystem.readText(path);
+  if (text === null) return undefined;
+  const pid = Number(text.trim());
+  return Number.isInteger(pid) && pid > 0 ? pid : undefined;
+}
+
+export async function runRuntimeDoctorCommand(options: {
+  workspaceRoot: string;
+}): Promise<RuntimeDoctorResult> {
+  const checks: DoctorCheck[] = [];
+  const generated = await runGenerate({
+    workspaceRoot: options.workspaceRoot,
+    check: true,
+    dryRun: false,
+    json: false,
+    concurrency: 4,
+  });
+  checks.push({
+    name: "generated",
+    ok: generated.exitCode === 0,
+    severity: "error",
+    message: generated.exitCode === 0 ? "generated artifacts are fresh" : "generated artifacts are stale; run forge generate",
+  });
+
+  const devDir = join(options.workspaceRoot, ".forge", "dev");
+  const pidFile = join(devDir, "dev.pid");
+  const logFile = join(devDir, "dev.log");
+  const pid = readPid(pidFile);
+  const running = pid !== undefined && isProcessRunning(pid);
+  checks.push({
+    name: "dev-lifecycle",
+    ok: true,
+    severity: "warning",
+    message: running
+      ? `detached forge dev is running with pid ${pid}`
+      : "no detached forge dev server is running",
+  });
+
+  const pglite = await inspectPgliteStore(join(options.workspaceRoot, DEFAULT_PGLITE_DIR));
+  const pgliteOk = pglite.state === "missing" || pglite.state === "healthy" || pglite.state === "active";
+  checks.push({
+    name: "pglite-store",
+    ok: pgliteOk,
+    severity: pglite.state === "active" ? "warning" : "error",
+    message: pglite.error ?? `PGlite store is ${pglite.state}`,
+  });
+  checks.push({
+    name: "pglite-openable",
+    ok: pglite.openable || pglite.state === "active",
+    severity: pglite.state === "active" ? "warning" : "error",
+    message: pglite.openable
+      ? "PGlite store is openable"
+      : pglite.state === "active"
+        ? "PGlite store is owned by a live process"
+        : "PGlite store cannot be opened",
+  });
+
+  const ok = checks.every((check) => check.ok || check.severity === "warning");
+  const dbGuide = buildLocalDbModeGuide(options.workspaceRoot, pglite);
+  const nextActions = ok
+    ? ["forge dev --once --json", "forge dev status --json"]
+    : [
+        ...(generated.exitCode === 0 ? [] : ["forge generate"]),
+        ...(pglite.state === "active"
+          ? ["stop the running forge dev process that owns .forge/pglite", "forge doctor pglite --json"]
+          : []),
+        ...(pglite.state === "aborted" || pglite.state === "unhealthy"
+          ? ["forge doctor pglite --json", "forge db repair --local --adapter pglite --json", "forge dev --db memory --json"]
+          : []),
+        ...(!pglite.openable && pglite.state !== "active" && pglite.state !== "aborted" && pglite.state !== "unhealthy"
+          ? ["forge doctor pglite --json", "forge dev --db memory --json"]
+          : []),
+      ];
+  return normalizeForgeCliCommandsInValue(options.workspaceRoot, {
+    ok,
+    checks,
+    dev: {
+      pidFile,
+      logFile,
+      running,
+      ...(pid !== undefined ? { pid } : {}),
+    },
+    pglite,
+    dbGuide,
+    nextActions: [...new Set(nextActions)],
+    exitCode: ok ? 0 : 1,
+  });
+}
+
 export function formatDoctorJson(result: DoctorResult): string {
   return `${JSON.stringify(result, null, 2)}\n`;
 }
@@ -279,6 +459,42 @@ export function formatPgliteDoctorHuman(result: PgliteDoctorResult): string {
   lines.push("");
   lines.push(`Store: ${result.inspection.dataDir}`);
   lines.push(`State: ${result.inspection.state}`);
+  lines.push(`Recommended DB mode: ${result.dbGuide.recommendedForCurrentState}`);
+  lines.push(`Memory: ${result.dbGuide.memory.command} - ${result.dbGuide.memory.tradeoff}`);
+  lines.push(`PGlite: ${result.dbGuide.pglite.command} - ${result.dbGuide.pglite.tradeoff}`);
+  if (result.dbGuide.repair) {
+    lines.push(`Repair: ${result.dbGuide.repair.command}`);
+  }
+  if (result.nextActions.length > 0) {
+    lines.push("");
+    lines.push("Next actions:");
+    for (const action of result.nextActions) {
+      lines.push(`  ${action}`);
+    }
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+export function formatRuntimeDoctorJson(result: RuntimeDoctorResult): string {
+  return `${JSON.stringify(result, null, 2)}\n`;
+}
+
+export function formatRuntimeDoctorHuman(result: RuntimeDoctorResult): string {
+  const lines = ["Forge Runtime Doctor", ""];
+  for (const check of result.checks) {
+    const marker = check.ok ? "OK" : check.severity === "warning" ? "WARN" : "FAIL";
+    lines.push(`${marker} ${check.name}${check.message ? ` - ${check.message}` : ""}`);
+  }
+  lines.push("");
+  lines.push(`Dev pid file: ${result.dev.pidFile}`);
+  lines.push(`Dev log file: ${result.dev.logFile}`);
+  lines.push(`PGlite state: ${result.pglite.state}`);
+  lines.push(`Recommended DB mode: ${result.dbGuide.recommendedForCurrentState}`);
+  lines.push(`Memory: ${result.dbGuide.memory.command} - ${result.dbGuide.memory.tradeoff}`);
+  lines.push(`PGlite: ${result.dbGuide.pglite.command} - ${result.dbGuide.pglite.tradeoff}`);
+  if (result.dbGuide.repair) {
+    lines.push(`Repair: ${result.dbGuide.repair.command}`);
+  }
   if (result.nextActions.length > 0) {
     lines.push("");
     lines.push("Next actions:");

package/src/forge/cli/field-test.ts

@@ -0,0 +1,328 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { runNewCommand, type NewPackageManager, type NewTemplateName } from "./new.ts";
+import { normalizeForgeCliCommandsInValue } from "../workspace/forge-cli.ts";
+
+export type FieldTestSubcommand = "create" | "run" | "report";
+
+export interface FieldTestCommandOptions {
+  subcommand: FieldTestSubcommand;
+  workspaceRoot: string;
+  json: boolean;
+  name?: string;
+  template: NewTemplateName;
+  templates?: NewTemplateName[];
+  packageManager: NewPackageManager;
+  packageManagers?: NewPackageManager[];
+  forgeSpec?: string;
+  auth?: "none" | "workos";
+  dryRun: boolean;
+  keep: boolean;
+  runtimeProbes: boolean;
+  authProbes: boolean;
+  timeoutMs: number;
+  writeReport?: string;
+}
+
+export interface FieldTestCommandResult {
+  schemaVersion: "0.1.0";
+  ok: boolean;
+  kind: "field-test";
+  action: FieldTestSubcommand;
+  data?: unknown;
+  summary?: unknown;
+  command?: string[];
+  reportPath?: string;
+  stdout?: string;
+  stderr?: string;
+  nextActions: string[];
+  exitCode: 0 | 1;
+}
+
+function scriptPath(workspaceRoot: string): string {
+  return join(workspaceRoot, "scripts", "field-test-forgeos.mjs");
+}
+
+function compact(text: string, limit = 12000): string {
+  if (text.length <= limit) return text;
+  const half = Math.floor(limit / 2);
+  return `${text.slice(0, half)}\n...[truncated ${text.length - limit} chars]...\n${text.slice(-half)}`;
+}
+
+function defaultReportPath(): string {
+  return ".forge/field-test-report.json";
+}
+
+function parseJsonOutput(text: string): unknown | null {
+  const trimmed = text.trim();
+  if (!trimmed) return null;
+  try {
+    return JSON.parse(trimmed) as unknown;
+  } catch {
+    const start = trimmed.indexOf("{");
+    const end = trimmed.lastIndexOf("}");
+    if (start === -1 || end <= start) return null;
+    try {
+      return JSON.parse(trimmed.slice(start, end + 1)) as unknown;
+    } catch {
+      return null;
+    }
+  }
+}
+
+function summarizeReport(data: unknown) {
+  const root = data && typeof data === "object" ? data as Record<string, unknown> : {};
+  const results = Array.isArray(root.results) ? root.results as Array<Record<string, unknown>> : [];
+  const plannedCases = Array.isArray(root.cases) ? root.cases as Array<Record<string, unknown>> : [];
+  const failed = results.filter((result) => result.ok === false && result.skipped !== true);
+  const skipped = results.filter((result) => result.skipped === true);
+  const runtimeProbeSteps = results.flatMap((result) => {
+    const runtime = result.runtime && typeof result.runtime === "object"
+      ? result.runtime as Record<string, unknown>
+      : {};
+    return Array.isArray(runtime.steps) ? runtime.steps as unknown[] : [];
+  });
+  const ok = root.ok === true;
+  const runtimeProbes = root.runtimeProbes === true;
+  const authProbes = root.authProbes === true;
+  const productionEvidenceMissing = [
+    ...(!ok ? ["passing field-test report"] : []),
+    ...(!runtimeProbes ? ["runtime probes"] : []),
+    ...(!authProbes ? ["auth probes"] : []),
+    ...(failed.length > 0 ? ["zero failed cases"] : []),
+  ];
+  return {
+    ok,
+    cases: results.length || plannedCases.length,
+    executedCases: results.length,
+    plannedCases: plannedCases.length,
+    passed: results.filter((result) => result.ok === true && result.skipped !== true).length,
+    failed: failed.length,
+    skipped: skipped.length,
+    runtimeProbes,
+    authProbes,
+    runtimeProbeSteps: runtimeProbeSteps.length,
+    productionEvidence: {
+      readyForDeployCheck: productionEvidenceMissing.length === 0,
+      missing: productionEvidenceMissing,
+      deployCheckCommand: "forge deploy check --production --json",
+      note: "This proves field-test evidence only; deploy check still validates production auth, database, metadata, lockfile, and tenant posture.",
+    },
+    failedCases: failed.map((result) => ({
+      template: result.template,
+      packageManager: result.packageManager,
+      reason: result.reason,
+    })),
+  };
+}
+
+function runCommandForOptions(templates: NewTemplateName[], packageManagers: NewPackageManager[]): string {
+  return [
+    "forge field-test run",
+    `--templates ${templates.join(",")}`,
+    `--package-managers ${packageManagers.join(",")}`,
+    "--runtime-probes",
+    "--auth-probes",
+    "--json",
+  ].join(" ");
+}
+
+async function createFieldTestApp(options: FieldTestCommandOptions): Promise<FieldTestCommandResult> {
+  if (!options.name) {
+    return {
+      schemaVersion: "0.1.0",
+      ok: false,
+      kind: "field-test",
+      action: "create",
+      data: { error: "forge field-test create requires an app name" },
+      nextActions: ["forge field-test create vendor-access --auth workos --template minimal-web --json"],
+      exitCode: 1,
+    };
+  }
+  if (options.dryRun) {
+    return normalizeForgeCliCommandsInValue(options.workspaceRoot, {
+      schemaVersion: "0.1.0",
+      ok: true,
+      kind: "field-test",
+      action: "create",
+      data: {
+        dryRun: true,
+        name: options.name,
+        template: options.template,
+        packageManager: options.packageManager,
+        auth: options.auth,
+        command: `forge new ${options.name} --template ${options.template} --package-manager ${options.packageManager} --field-test --install`,
+      },
+      nextActions: [`forge new ${options.name} --template ${options.template} --package-manager ${options.packageManager} --field-test --install`],
+      exitCode: 0,
+    });
+  }
+  const created = await runNewCommand({
+    name: options.name,
+    template: options.template,
+    packageManager: options.packageManager,
+    install: true,
+    git: true,
+    fieldTest: options.auth === "workos",
+    forgePackageSpec: options.forgeSpec,
+    workspaceRoot: options.workspaceRoot,
+  });
+  const createdFieldTest = created.fieldTest?.steps ?? [];
+  return normalizeForgeCliCommandsInValue(options.workspaceRoot, {
+    schemaVersion: "0.1.0",
+    ok: created.exitCode === 0,
+    kind: "field-test",
+    action: "create",
+    data: {
+      ...created,
+      auth: options.auth,
+      setup: options.auth === "workos"
+        ? {
+            applied: createdFieldTest.length > 0 && createdFieldTest.every((step) => step.ok),
+            steps: createdFieldTest,
+          }
+        : {
+            applied: false,
+            steps: [],
+            note: "auth=none creates a plain app; pass --auth workos for WorkOS/AuthKit/auth.md field-test setup.",
+          },
+    },
+    nextActions: [
+      `cd ${created.targetDir}`,
+      `${options.packageManager} run forge -- agent onboard --target codex --json`,
+      `${options.packageManager} run forge -- generate`,
+      `${options.packageManager} run forge -- check --json`,
+      ...(options.auth === "workos"
+        ? [
+            `${options.packageManager} run forge -- authmd check --json`,
+            `${options.packageManager} run forge -- workos doctor --json`,
+            `${options.packageManager} run forge -- workos seed --file workos-seed.yml --dry-run --json`,
+          ]
+        : []),
+      `${options.packageManager} run forge -- dev --once --json`,
+      `${options.packageManager} run forge -- verify --smoke --json`,
+      `${options.packageManager} run forge -- handoff --json`,
+    ],
+    exitCode: created.exitCode,
+  });
+}
+
+function runHarness(options: FieldTestCommandOptions): FieldTestCommandResult {
+  const script = scriptPath(options.workspaceRoot);
+  if (!existsSync(script)) {
+    return {
+      schemaVersion: "0.1.0",
+      ok: false,
+      kind: "field-test",
+      action: "run",
+      data: { error: "field-test harness script not found", script },
+      nextActions: ["run from the ForgeOS framework checkout or use npm run field:test"],
+      exitCode: 1,
+    };
+  }
+  const reportPath = options.writeReport ?? (options.dryRun ? undefined : defaultReportPath());
+  const templates = options.templates?.length ? options.templates : [options.template];
+  const packageManagers = options.packageManagers?.length ? options.packageManagers : [options.packageManager];
+  const args = [
+    script,
+    "--templates",
+    templates.join(","),
+    "--package-managers",
+    packageManagers.join(","),
+    "--timeout-ms",
+    String(options.timeoutMs),
+  ];
+  if (options.dryRun) args.push("--dry-run");
+  if (options.keep) args.push("--keep");
+  if (options.runtimeProbes) args.push("--runtime-probes");
+  if (options.authProbes) args.push("--auth-probes");
+  if (options.forgeSpec) args.push("--forge-spec", options.forgeSpec);
+  if (reportPath) args.push("--write-report", reportPath);
+  if (options.json) args.push("--json");
+  const result = spawnSync(process.execPath, args, {
+    cwd: options.workspaceRoot,
+    encoding: "utf8",
+    windowsHide: true,
+  });
+  const reportAbsolute = reportPath ? join(options.workspaceRoot, reportPath) : null;
+  const reportData = reportAbsolute && existsSync(reportAbsolute)
+    ? JSON.parse(readFileSync(reportAbsolute, "utf8")) as unknown
+    : parseJsonOutput(result.stdout ?? "");
+  return normalizeForgeCliCommandsInValue(options.workspaceRoot, {
+    schemaVersion: "0.1.0",
+    ok: result.status === 0,
+    kind: "field-test",
+    action: "run",
+    command: [process.execPath, ...args],
+    reportPath,
+    data: reportData ?? undefined,
+    summary: reportData ? summarizeReport(reportData) : undefined,
+    stdout: compact(result.stdout ?? ""),
+    stderr: compact(result.stderr ?? ""),
+    nextActions: result.status === 0
+      ? options.dryRun
+        ? [runCommandForOptions(templates, packageManagers)]
+        : [`forge field-test report --file ${reportPath ?? defaultReportPath()} --json`, "forge deploy check --production --json"]
+      : ["inspect field-test stdout/stderr", "forge doctor pglite --json"],
+    exitCode: result.status === 0 ? 0 : 1,
+  });
+}
+
+function readReport(options: FieldTestCommandOptions): FieldTestCommandResult {
+  const candidates = [
+    options.writeReport,
+    ".forge/field-test-report.json",
+    "field-reports/full-alpha.json",
+  ].filter(Boolean) as string[];
+  const report = candidates.find((candidate) => existsSync(join(options.workspaceRoot, candidate)));
+  if (!report) {
+    return {
+      schemaVersion: "0.1.0",
+      ok: false,
+      kind: "field-test",
+      action: "report",
+      data: { searched: candidates },
+      nextActions: ["forge field-test run --runtime-probes --auth-probes --write-report .forge/field-test-report.json --json"],
+      exitCode: 1,
+    };
+  }
+  const data = JSON.parse(readFileSync(join(options.workspaceRoot, report), "utf8")) as unknown;
+  const summary = summarizeReport(data);
+  const productionEvidence = (summary as { productionEvidence?: { readyForDeployCheck?: boolean } }).productionEvidence;
+  return {
+    schemaVersion: "0.1.0",
+    ok: (data && typeof data === "object" && "ok" in data) ? (data as { ok?: unknown }).ok === true : true,
+    kind: "field-test",
+    action: "report",
+    reportPath: report,
+    summary,
+    data,
+    nextActions: productionEvidence?.readyForDeployCheck
+      ? ["forge deploy check --production --json"]
+      : ["forge field-test run --runtime-probes --auth-probes --write-report .forge/field-test-report.json --json"],
+    exitCode: (data && typeof data === "object" && "ok" in data && (data as { ok?: unknown }).ok !== true) ? 1 : 0,
+  };
+}
+
+export async function runFieldTestCommand(options: FieldTestCommandOptions): Promise<FieldTestCommandResult> {
+  if (options.subcommand === "create") return createFieldTestApp(options);
+  if (options.subcommand === "run") return runHarness(options);
+  return readReport(options);
+}
+
+export function formatFieldTestJson(result: FieldTestCommandResult): string {
+  return `${JSON.stringify(result, null, 2)}\n`;
+}
+
+export function formatFieldTestHuman(result: FieldTestCommandResult): string {
+  const lines = [
+    `field-test ${result.action} ${result.ok ? "ok" : "failed"}`,
+    ...(result.reportPath ? [`report: ${result.reportPath}`] : []),
+    ...(result.command ? [`command: ${result.command.join(" ")}`] : []),
+    ...(result.stdout ? ["", result.stdout] : []),
+    ...(result.stderr ? ["", result.stderr] : []),
+    ...(result.nextActions.length ? ["", "Next:", ...result.nextActions.map((action) => `  ${action}`)] : []),
+  ];
+  return `${lines.join("\n")}\n`;
+}

package/src/forge/cli/handoff.ts

@@ -27,6 +27,7 @@ export interface HandoffCommandResult {
     generatedChangedFiles: number;
     frontendReady: boolean;
     changedFiles: number;
+    commitReadyFiles: number;
     stagedFiles: number;
     unstagedFiles: number;
     untrackedFiles: number;
@@ -157,10 +158,14 @@ function buildOpeningBrief(input: {
   dev: DevConsoleCycle;
   git: HandoffCommandResult["git"];
   recentRuns: HandoffCommandResult["recentRuns"];
+  commitReady?: HandoffCommandResult["commitReady"];
 }): string {
   const agent = input.dev.summary.agentContext;
   const changedByType = summarizeChangeTypes(input.git.changeSummary.changed);
   const changedFiles = Math.max(agent.changedFiles, input.git.changed.count);
+  const commitReadyNote = input.commitReady && input.commitReady.count !== changedFiles
+    ? `; ${input.commitReady.count} commit-ready file(s) after excluding generated/operational artifacts`
+    : "";
   const tests = input.recentRuns.test
     ? input.recentRuns.test.ok
       ? "last test run passed"
@@ -171,7 +176,7 @@ function buildOpeningBrief(input: {
     : "no blocking issues";
   return [
     `ForgeOS handoff: ${input.dev.ok ? "dev diagnostics are clean" : "dev diagnostics need attention"}.`,
-    `${changedFiles} changed file(s)${changedByType ? `: ${changedByType}` : ""}; ${input.git.staged.count} staged, ${input.git.untracked.count} untracked.`,
+    `${changedFiles} changed file(s)${changedByType ? `: ${changedByType}` : ""}${commitReadyNote}; ${input.git.staged.count} staged, ${input.git.untracked.count} untracked.`,
     `${tests}; ${blockers}.`,
     `Next command: ${input.dev.summary.primaryAction?.command ?? input.dev.nextActions[0]?.command ?? "forge dev"}.`,
   ].join(" ");
@@ -211,9 +216,7 @@ export async function runHandoffCommand(options: HandoffCommandOptions): Promise
     includeImpact: true,
   });
   const git = buildWorkspaceGitSummary(workspaceRoot);
-  const commitReady = options.commitReady
-    ? runChangedCommand(workspaceRoot, { commitReady: true }).data.commitReady as { count: number; files: string[] } | undefined
-    : undefined;
+  const commitReady = runChangedCommand(workspaceRoot, { commitReady: true }).data.commitReady as { count: number; files: string[] } | undefined;
   const recentRuns = summarizeRecentRuns(workspaceRoot);
   const agent = dev.summary.agentContext;
   const risks = [
@@ -224,6 +227,9 @@ export async function runHandoffCommand(options: HandoffCommandOptions): Promise
         ? ["git status is unavailable; using filesystem inventory as untracked-file analysis"]
         : []),
     ...(git.untracked.count > 0 && git.source !== "forge-baseline" ? [`${git.untracked.count} untracked file(s) are not in git history`] : []),
+    ...(commitReady && git.changed.count > commitReady.count
+      ? [`${git.changed.count - commitReady.count} generated or operational file(s) are excluded from the commit-ready view`]
+      : []),
     ...(recentRuns.test && !recentRuns.test.ok ? ["last test run failed"] : []),
     ...(recentRuns.ui && !recentRuns.ui.ok ? ["last UI run failed"] : []),
   ];
@@ -231,6 +237,7 @@ export async function runHandoffCommand(options: HandoffCommandOptions): Promise
     ...agent.recommendedCommands,
     ...forgeCliCommandsForWorkspace(workspaceRoot, [
       ...(git.changed.count > 0 ? ["forge review run --changed --json"] : []),
+      ...(git.changed.count > 0 ? ["forge changed --commit-ready --json"] : []),
       "forge handoff --json",
     ]),
   ];
@@ -252,6 +259,7 @@ export async function runHandoffCommand(options: HandoffCommandOptions): Promise
       generatedChangedFiles: agent.generatedChangedFiles,
       frontendReady: agent.frontendReady,
       changedFiles,
+      commitReadyFiles: commitReady?.count ?? changedFiles,
       stagedFiles: git.staged.count,
       unstagedFiles: git.unstaged.count,
       untrackedFiles: git.untracked.count,
@@ -273,7 +281,7 @@ export async function runHandoffCommand(options: HandoffCommandOptions): Promise
     git,
     recentRuns,
     nextAgent: {
-      openingBrief: buildOpeningBrief({ dev, git, recentRuns }),
+      openingBrief: buildOpeningBrief({ dev, git, recentRuns, commitReady }),
       recommendedReadFiles: agent.recommendedReadFiles,
       recommendedCommands: [...new Set(nextActions)].slice(0, 10),
       risks,