forgeos 0.1.0-alpha.4 → 0.1.0-alpha.41

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

@@ -0,0 +1,329 @@
+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 -- workos setup --file workos-seed.yml --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

@@ -0,0 +1,336 @@
+import { join } from "node:path";
+import { nodeFileSystem } from "../compiler/fs/index.ts";
+import type { Diagnostic } from "../compiler/types/diagnostic.ts";
+import { runDevConsoleCycle } from "../dev-console/cycle.ts";
+import type { DevConsoleCycle, DevConsolePhase } from "../dev-console/types.ts";
+import type { TestRunRecord } from "../impact/types.ts";
+import type { UiRunReport } from "../ui/types.ts";
+import { summarizeChangeTypes, type CategorizedFileSummary } from "../workspace/change-summary.ts";
+import { forgeCliCommandsForWorkspace } from "../workspace/forge-cli.ts";
+import { buildWorkspaceGitSummary } from "../workspace/git-summary.ts";
+import { runChangedCommand } from "./changed.ts";
+
+export interface HandoffCommandOptions {
+  workspaceRoot: string;
+  json: boolean;
+  commitReady?: boolean;
+}
+
+export interface HandoffCommandResult {
+  schemaVersion: "0.1.0";
+  ok: boolean;
+  summary: {
+    projectRoot: string;
+    safeToEdit: boolean;
+    generatedFresh: boolean;
+    generatedChanged: boolean;
+    generatedChangedFiles: number;
+    frontendReady: boolean;
+    changedFiles: number;
+    commitReadyFiles: number;
+    stagedFiles: number;
+    unstagedFiles: number;
+    untrackedFiles: number;
+    lastTestRun: "passed" | "failed" | "missing";
+    lastUiRun: "passed" | "failed" | "missing";
+    workspaceMode: "git" | "nonGit";
+    tracking: string;
+  };
+  dev: {
+    ok: boolean;
+    primaryAction?: DevConsoleCycle["summary"]["primaryAction"];
+    agentContext: DevConsoleCycle["summary"]["agentContext"];
+    phases: Array<Pick<DevConsolePhase, "name" | "status" | "message">>;
+  };
+  git: {
+    available: boolean;
+    branch?: string;
+    commit?: string;
+    changed: {
+      count: number;
+      sample: string[];
+      hidden: number;
+    };
+    staged: {
+      count: number;
+      sample: string[];
+      hidden: number;
+    };
+    unstaged: {
+      count: number;
+      sample: string[];
+      hidden: number;
+    };
+    untracked: {
+      count: number;
+      sample: string[];
+      hidden: number;
+    };
+    changeSummary: {
+      changed: CategorizedFileSummary;
+      staged: CategorizedFileSummary;
+      unstaged: CategorizedFileSummary;
+      untracked: CategorizedFileSummary;
+    };
+    workspaceMode?: string;
+    tracking?: string;
+    baseline?: unknown;
+    error?: string;
+  };
+  recentRuns: {
+    test?: {
+      id?: string;
+      ok: boolean;
+      failed: string[];
+      durationMs?: number;
+    };
+    ui?: {
+      id?: string;
+      ok: boolean;
+      failedScenarios: string[];
+    };
+  };
+  nextAgent: {
+    openingBrief: string;
+    recommendedReadFiles: string[];
+    recommendedCommands: string[];
+    risks: string[];
+  };
+  commitReady?: {
+    count: number;
+    files: string[];
+  };
+  diagnosticSummary: {
+    total: number;
+    sample: Diagnostic[];
+    hidden: number;
+    bySeverity: Record<string, number>;
+    byCode: Record<string, number>;
+    fullDiagnosticsCommands: string[];
+  };
+  diagnostics: Diagnostic[];
+  nextActions: string[];
+  exitCode: 0 | 1;
+}
+
+function readJson<T>(workspaceRoot: string, relativePath: string): T | null {
+  const absolute = join(workspaceRoot, relativePath);
+  if (!nodeFileSystem.exists(absolute)) {
+    return null;
+  }
+  try {
+    return JSON.parse(nodeFileSystem.readText(absolute) ?? "null") as T;
+  } catch {
+    return null;
+  }
+}
+
+function summarizeRecentRuns(workspaceRoot: string): HandoffCommandResult["recentRuns"] {
+  const test = readJson<TestRunRecord>(workspaceRoot, ".forge/test-runs/last.json");
+  const ui = readJson<UiRunReport>(workspaceRoot, ".forge/ui-runs/last.json");
+  const failedScenarios = (ui?.scenarios ?? [])
+    .filter((scenario) => !scenario.ok)
+    .map((scenario) => scenario.name);
+  return {
+    ...(test
+      ? {
+          test: {
+            id: test.id,
+            ok: test.failed.length === 0,
+            failed: test.failed,
+            durationMs: test.durationMs,
+          },
+        }
+      : {}),
+    ...(ui
+      ? {
+          ui: {
+            id: ui.id,
+            ok: failedScenarios.length === 0 && ui.diagnostics.every((diagnostic) => diagnostic.severity !== "error"),
+            failedScenarios,
+          },
+        }
+      : {}),
+  };
+}
+
+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"
+      : "last test run failed"
+    : "no last test run";
+  const blockers = agent.blockingIssues.length > 0
+    ? `${agent.blockingIssues.length} blocking issue(s)`
+    : "no blocking issues";
+  return [
+    `ForgeOS handoff: ${input.dev.ok ? "dev diagnostics are clean" : "dev diagnostics need attention"}.`,
+    `${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(" ");
+}
+
+function compactDiagnostics(
+  workspaceRoot: string,
+  diagnostics: Diagnostic[],
+  sampleSize = 8,
+): HandoffCommandResult["diagnosticSummary"] {
+  const bySeverity: Record<string, number> = {};
+  const byCode: Record<string, number> = {};
+  for (const diagnostic of diagnostics) {
+    bySeverity[diagnostic.severity] = (bySeverity[diagnostic.severity] ?? 0) + 1;
+    byCode[diagnostic.code] = (byCode[diagnostic.code] ?? 0) + 1;
+  }
+  return {
+    total: diagnostics.length,
+    sample: diagnostics.slice(0, sampleSize),
+    hidden: Math.max(0, diagnostics.length - sampleSize),
+    bySeverity,
+    byCode,
+    fullDiagnosticsCommands: forgeCliCommandsForWorkspace(workspaceRoot, [
+      "forge dev --once --json",
+      "forge inspect all --full --json",
+      "forge generate --check --json",
+    ]),
+  };
+}
+
+export async function runHandoffCommand(options: HandoffCommandOptions): Promise<HandoffCommandResult> {
+  const workspaceRoot = options.workspaceRoot.replace(/\\/g, "/");
+  const dev = await runDevConsoleCycle({
+    workspaceRoot,
+    mode: "once",
+    generatedMode: "check",
+    includeImpact: true,
+  });
+  const git = buildWorkspaceGitSummary(workspaceRoot);
+  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 = [
+    ...agent.blockingIssues,
+    ...(!git.available && git.source === "forge-baseline"
+      ? ["git status is unavailable; using Forge workspace baseline for non-git change tracking"]
+      : !git.available
+        ? ["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"] : []),
+  ];
+  const nextActions = [
+    ...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",
+    ]),
+  ];
+  const ok = dev.ok &&
+    agent.blockingIssues.length === 0 &&
+    (!recentRuns.test || recentRuns.test.ok) &&
+    (!recentRuns.ui || recentRuns.ui.ok);
+  const changedFiles = Math.max(agent.changedFiles, git.changed.count);
+  const diagnosticSummary = compactDiagnostics(workspaceRoot, dev.diagnostics);
+
+  return {
+    schemaVersion: "0.1.0",
+    ok,
+    summary: {
+      projectRoot: workspaceRoot,
+      safeToEdit: agent.safeToEdit,
+      generatedFresh: agent.generatedFresh,
+      generatedChanged: agent.generatedChanged,
+      generatedChangedFiles: agent.generatedChangedFiles,
+      frontendReady: agent.frontendReady,
+      changedFiles,
+      commitReadyFiles: commitReady?.count ?? changedFiles,
+      stagedFiles: git.staged.count,
+      unstagedFiles: git.unstaged.count,
+      untrackedFiles: git.untracked.count,
+      lastTestRun: recentRuns.test ? (recentRuns.test.ok ? "passed" : "failed") : "missing",
+      lastUiRun: recentRuns.ui ? (recentRuns.ui.ok ? "passed" : "failed") : "missing",
+      workspaceMode: git.workspaceMode ?? (git.available ? "git" : "nonGit"),
+      tracking: git.tracking ?? git.source ?? "git",
+    },
+    dev: {
+      ok: dev.ok,
+      ...(dev.summary.primaryAction ? { primaryAction: dev.summary.primaryAction } : {}),
+      agentContext: agent,
+      phases: dev.phases.map((phase) => ({
+        name: phase.name,
+        status: phase.status,
+        ...(phase.message ? { message: phase.message } : {}),
+      })),
+    },
+    git,
+    recentRuns,
+    nextAgent: {
+      openingBrief: buildOpeningBrief({ dev, git, recentRuns, commitReady }),
+      recommendedReadFiles: agent.recommendedReadFiles,
+      recommendedCommands: [...new Set(nextActions)].slice(0, 10),
+      risks,
+    },
+    ...(commitReady ? { commitReady } : {}),
+    diagnosticSummary,
+    diagnostics: diagnosticSummary.sample,
+    nextActions: [...new Set(nextActions)].slice(0, 10),
+    exitCode: ok ? 0 : 1,
+  };
+}
+
+export function formatHandoffJson(result: HandoffCommandResult): string {
+  return `${JSON.stringify(result, null, 2)}\n`;
+}
+
+export function formatHandoffHuman(result: HandoffCommandResult): string {
+  const lines = [
+    `Forge handoff: ${result.ok ? "ready" : "needs attention"}`,
+    result.nextAgent.openingBrief,
+    "",
+    "Read first:",
+    ...result.nextAgent.recommendedReadFiles.slice(0, 6).map((file) => `  ${file}`),
+    "",
+    "Next commands:",
+    ...result.nextActions.slice(0, 6).map((command) => `  ${command}`),
+  ];
+  if (result.nextAgent.risks.length > 0) {
+    lines.push("", "Risks:");
+    lines.push(...result.nextAgent.risks.slice(0, 6).map((risk) => `  ${risk}`));
+  }
+  if (result.diagnosticSummary.total > 0) {
+    lines.push(
+      "",
+      "Diagnostics:",
+      `  ${result.diagnosticSummary.total} total` +
+        (result.diagnosticSummary.hidden > 0 ? ` (${result.diagnosticSummary.hidden} hidden in compact handoff)` : ""),
+    );
+  }
+  if (result.commitReady) {
+    lines.push("", "Commit-ready files:", `  ${result.commitReady.count}`);
+    lines.push(...result.commitReady.files.slice(0, 8).map((file) => `  ${file}`));
+    if (result.commitReady.files.length > 8) {
+      lines.push(`  ... ${result.commitReady.files.length - 8} more`);
+    }
+  }
+  const changedTypes = summarizeChangeTypes(result.git.changeSummary.changed);
+  if (changedTypes) {
+    lines.push("", "Change types:", `  ${changedTypes}`);
+  }
+  return `${lines.join("\n")}\n`;
+}

package/src/forge/cli/index.ts

@@ -2,6 +2,7 @@ export { CLI_VERSION } from "./version.ts";
 export { parseCli, hasUnknownOption, type ParsedCli, type ForgeCommand } from "./parse.ts";
 export { runNewCommand, type NewCommandOptions, type NewCommandResult } from "./new.ts";
 export { runSelfHostCommand, type SelfHostCommandOptions } from "./self-host.ts";
+export { runDocsCheckCommand, type DocsCheckResult } from "./docs.ts";
 export { runBuildCommand, type BuildCommandOptions } from "./build.ts";
 export { runServeCommand, type ServeCommandOptions } from "./serve.ts";
 export { runWorkerCommand, type WorkerCommandOptions } from "./worker.ts";