silvermoon 0.0.3 → 0.1.0

package/src/whatsnext.js

@@ -1,454 +1,605 @@
 import { resolve } from "node:path";
 
-import { inspectAdoption } from "./adoption.js";
-import { loadConfig } from "./config.js";
 import {
+  createEnvelope,
+  dialogueReadyObservation,
+  localize,
+  outcome,
+} from "./dialogue.js";
+import {
+  compareCommits,
   fetchPrimary,
-  parseWorktreeChanges,
-  runGit,
-  withTemporaryWorktree,
+  inspectCurrentBranch,
+  inspectWorktreeChanges,
+  resolveHead,
+  sanitizeGitMessage,
 } from "./git.js";
-import { inspectIdeaLayout } from "./idea-layout.js";
-import { resolveLanguage } from "./language.js";
-import { loadUserConfig } from "./user-config.js";
+import {
+  observeSnapshot,
+  repositoryProblemObservation,
+  withObservationLanguage,
+} from "./observation.js";
+import { traceAsync } from "./trace.js";
 
-const ACTIVE_STATES = new Set(["preparing", "implementing", "deploying"]);
+export const CHANGE_SAMPLE_ITEM_LIMIT = 12;
+export const CHANGE_SAMPLE_BYTE_LIMIT = 768;
 
-function diagnostic(code, message, remediation, path) {
-  return { code, level: "error", ...(path ? { path } : {}), message, remediation };
+function ideaName(idea) {
+  return idea.alias ?? idea.id;
 }
 
-function failed(root, diagnostics, request, observedPrimaryCommit = null) {
-  return {
-    command: "whats-next",
-    ok: false,
-    root,
-    diagnostics,
-    result: request
-      ? { observedPrimaryCommit, request, selectedIdea: null, action: null }
-      : null,
-  };
+function command(root, value) {
+  return `\`${value.replace("<root>", root)}\``;
 }
 
-function ideaName(idea) {
-  return idea.alias ?? idea.id;
+function joinInstructions(lines) {
+  return lines.filter(Boolean).join("\n");
 }
 
-function summary(idea) {
-  const value = {
-    id: idea.id,
-    idealRevision: idea.idealRevision,
-    implementationRevision: idea.implementationRevision,
-    deploymentRevision: idea.deploymentRevision,
-    ledgerPath: idea.ledgerPath,
-    state: idea.state,
-  };
-  if (idea.alias !== undefined) value.alias = idea.alias;
-  return value;
+function formatInstructionSteps(steps) {
+  return steps.length === 1
+    ? steps
+    : steps.map((step, index) => `${index + 1}. ${step}`);
 }
 
-function action(code, message, details = {}) {
-  return { code, message, details };
+export function projectInstructions(
+  observed,
+  root,
+  language,
+  recheckCommand = "silvermoon whats-next",
+) {
+  return joinInstructions([
+    ...formatInstructionSteps(observed.findings.map(({ instruction }) => instruction)),
+    localize(
+      language,
+      `After completing the applicable steps, run ${command(root, recheckCommand)} again.`,
+      `完成适用步骤后，再运行 ${command(root, recheckCommand)}。`,
+    ),
+  ]);
 }
 
-function actionWithLanguage(nextAction, language) {
+function sampleChanges(changes) {
+  const entries = [
+    ...changes.conflicted.map(({ path }) => `conflicted:${path}`),
+    ...changes.staged.map(({ path }) => `staged:${path}`),
+    ...changes.unstaged.map(({ path }) => `unstaged:${path}`),
+    ...changes.untracked.map(({ path }) => `untracked:${path}`),
+  ];
+  const samples = [];
+  let bytes = 0;
+  for (const entry of entries) {
+    if (samples.length >= CHANGE_SAMPLE_ITEM_LIMIT) break;
+    const nextBytes = Buffer.byteLength(
+      samples.length === 0 ? entry : `, ${entry}`,
+      "utf8",
+    );
+    if (bytes + nextBytes > CHANGE_SAMPLE_BYTE_LIMIT) break;
+    samples.push(entry);
+    bytes += nextBytes;
+  }
   return {
-    ...nextAction,
-    message: `${nextAction.message} Use ${language.tag} for natural-language content and user-facing explanations.`,
+    counts: {
+      conflicted: changes.conflicted.length,
+      staged: changes.staged.length,
+      unstaged: changes.unstaged.length,
+      untracked: changes.untracked.length,
+    },
+    omitted: entries.length - samples.length,
+    samples,
   };
 }
 
-function onboardingGaps(onboarding) {
-  if (onboarding.findings.length === 0) return null;
-  return {
-    status: onboarding.status,
-    gaps: onboarding.findings,
-    recommendedAction: onboarding.recommendedAction,
-    recheck: onboarding.recheck,
+export function summarizeWorktreeChanges(changes, language = "en-US") {
+  const summary = sampleChanges(changes);
+  const labels = {
+    conflicted: localize(language, "conflicted", "冲突"),
+    staged: localize(language, "staged", "已暂存"),
+    unstaged: localize(language, "unstaged", "未暂存"),
+    untracked: localize(language, "untracked", "未跟踪"),
   };
+  const counts = Object.entries(summary.counts)
+    .map(([kind, count]) => `${labels[kind]}=${count}`)
+    .join(localize(language, ", ", "，"));
+  const samples = summary.samples.length === 0
+    ? localize(language, "none", "无")
+    : summary.samples.join(localize(language, ", ", "，"));
+  return localize(
+    language,
+    `${counts}; samples=[${samples}]; omitted=${summary.omitted}`,
+    `${counts}；样例=[${samples}]；省略=${summary.omitted}`,
+  );
 }
 
-function success(root, observedPrimaryCommit, request, selectedIdea, nextAction, language) {
-  return {
-    command: "whats-next",
-    ok: true,
-    root,
-    diagnostics: [],
-    result: {
-      observedPrimaryCommit,
-      request,
+function worktreeInstructionSteps(changes, language) {
+  const lines = [];
+  if (changes.conflicted.length > 0) {
+    lines.push(localize(
       language,
-      selectedIdea: selectedIdea ? summary(selectedIdea) : null,
-      action: actionWithLanguage(nextAction, language),
-    },
-  };
+      "Inspect every conflicted path and its contents, then resolve the conflicts without discarding either side.",
+      "检查全部冲突路径及其内容，再在不丢弃任一方内容的前提下解决冲突。",
+    ));
+  }
+  const hasOrdinaryChanges =
+    changes.staged.length > 0
+    || changes.unstaged.length > 0
+    || changes.untracked.length > 0;
+  if (hasOrdinaryChanges) {
+    lines.push(localize(
+      language,
+      "Inspect all staged, unstaged, and untracked paths and their changes, not just the samples above. Preserve unknown work, then commit, isolate, or explicitly discard each change.",
+      "检查全部 staged、unstaged 和 untracked 路径及其修改内容，不要只依据上述样例。保留未知工作，再逐项提交、隔离，或在获得明确授权后放弃。",
+    ));
+  }
+  return lines;
 }
 
-export function stateAction(idea) {
-  if (idea.state === "abandoned") {
-    return action(
-      "review-abandoned",
-      `Review abandoned idea ${ideaName(idea)} and decide whether to keep it abandoned or revise it.`,
-      { statusPath: idea.statusPath, ledgerPath: idea.ledgerPath },
-    );
-  }
+function localRepositoryInstructions(root, steps, language, recheckCommand) {
+  return joinInstructions([
+    ...formatInstructionSteps(steps),
+    localize(
+      language,
+      `After completing every applicable step, run ${command(root, recheckCommand)} again.`,
+      `完成全部适用步骤后，再运行 ${command(root, recheckCommand)}。`,
+    ),
+  ]);
+}
+
+function selectIdea(ideas, selector) {
+  if (selector === undefined) return null;
+  return ideas.find(({ id }) => id === selector)
+    ?? ideas.find(({ alias }) => alias === selector)
+    ?? null;
+}
+
+function lifecycleInstruction(idea, language) {
+  const name = ideaName(idea);
   if (idea.state === "preparing") {
-    const world = idea.worlds.idealRevision;
-    return action(
-      "prepare-idea",
-      `Clarify the Ideal World (道心) for idea ${ideaName(idea)} in Idea.md and its supporting files, then record approval for ${idea.idealRevision}.`,
-      {
-        ideaPath: idea.relativePath,
-        statusPath: idea.statusPath,
-        ledgerPath: idea.ledgerPath,
-        world: {
-          ...world,
-          auxiliaryRoot: world.path,
-          revision: idea.idealRevision,
-          decisionField: "approvedRevision",
-          cascade: "Changes invalidate approval, implementation acceptance, and deployment acceptance.",
-        },
-      },
+    return localize(
+      language,
+      `Continue idea ${name} in ${idea.worlds.idealRevision.documentPath} and ${idea.ledgerPath}. Preserve the other worlds. When the Ideal World is ready, ask the user to approve exact revision ${idea.idealRevision}; only after explicit approval write it to approvedRevision in ${idea.statusPath}.`,
+      `继续在 ${idea.worlds.idealRevision.documentPath} 和 ${idea.ledgerPath} 推进 idea ${name}，并保留其他世界。理想契约就绪后，请用户明确批准精确 revision ${idea.idealRevision}；只有获得明确批准后，才将其写入 ${idea.statusPath} 的 approvedRevision。`,
     );
   }
   if (idea.state === "implementing") {
-    const world = idea.worlds.implementationRevision;
-    return action(
-      "implement-idea",
-      `Shape the Inner World (内景) for idea ${ideaName(idea)} in Implementation.md and its supporting files, then accept implementation ${idea.implementationRevision}.`,
-      {
-        ideaPath: idea.relativePath,
-        statusPath: idea.statusPath,
-        ledgerPath: idea.ledgerPath,
-        world: {
-          ...world,
-          auxiliaryRoot: world.path,
-          nestedWorldPath: idea.worlds.idealRevision.path,
-          revision: idea.implementationRevision,
-          decisionField: "implementationAcceptedRevision",
-          cascade: "Inner World changes invalidate implementation and deployment acceptance; Ideal World changes return to preparing.",
-        },
-      },
+    return localize(
+      language,
+      `Continue idea ${name} in ${idea.worlds.implementationRevision.documentPath}, its supporting files under ${idea.worlds.implementationRevision.path}, and ${idea.ledgerPath}. Do not change ${idea.worlds.idealRevision.path} unless the Ideal World must change. After all implementation evidence is published, ask the user to accept exact revision ${idea.implementationRevision}; only then write it to implementationAcceptedRevision in ${idea.statusPath}.`,
+      `继续在 ${idea.worlds.implementationRevision.documentPath}、${idea.worlds.implementationRevision.path} 下的辅助文件和 ${idea.ledgerPath} 推进 idea ${name}。除非理想契约确实需要变化，否则不要修改 ${idea.worlds.idealRevision.path}。全部实现证据发布后，请用户明确验收精确 revision ${idea.implementationRevision}；只有获得明确验收后，才将其写入 ${idea.statusPath} 的 implementationAcceptedRevision。`,
     );
   }
   if (idea.state === "deploying") {
-    const world = idea.worlds.deploymentRevision;
-    return action(
-      "deploy-idea",
-      `Verify the Outer World (现世) for idea ${ideaName(idea)} from Deployment.md and its supporting files, then accept deployment ${idea.deploymentRevision}.`,
-      {
-        ideaPath: idea.relativePath,
-        statusPath: idea.statusPath,
-        ledgerPath: idea.ledgerPath,
-        world: {
-          ...world,
-          auxiliaryRoot: world.path,
-          nestedWorldPath: idea.worlds.implementationRevision.path,
-          revision: idea.deploymentRevision,
-          decisionField: "deploymentAcceptedRevision",
-          cascade: "Outer World changes invalidate deployment acceptance only; nested world changes cascade inward.",
-        },
-      },
+    return localize(
+      language,
+      `Continue idea ${name} from ${idea.worlds.deploymentRevision.documentPath}, its supporting files under ${idea.worlds.deploymentRevision.path}, and ${idea.ledgerPath}. Preserve nested worlds. After external evidence is complete and published, ask the user to accept exact revision ${idea.deploymentRevision}; only then write it to deploymentAcceptedRevision in ${idea.statusPath}.`,
+      `从 ${idea.worlds.deploymentRevision.documentPath}、${idea.worlds.deploymentRevision.path} 下的辅助文件和 ${idea.ledgerPath} 继续推进 idea ${name}，并保留内层世界。外部证据完成且发布后，请用户明确验收精确 revision ${idea.deploymentRevision}；只有获得明确验收后，才将其写入 ${idea.statusPath} 的 deploymentAcceptedRevision。`,
     );
   }
-  return action(
-    "review-completed",
-    `Review completed idea ${ideaName(idea)} and decide whether to revise it or create a new idea.`,
-    {
-      ideaPath: idea.relativePath,
-      statusPath: idea.statusPath,
-      ledgerPath: idea.ledgerPath,
-      revisions: idea.revisions,
-    },
+  if (idea.state === "abandoned") {
+    return localize(
+      language,
+      `Review abandoned idea ${name} at ${idea.relativePath}. Keep abandoned: true in ${idea.statusPath}, remove it only after an explicit decision to resume, or discuss a different goal and run silvermoon create-idea.`,
+      `复查位于 ${idea.relativePath} 的已放弃 idea ${name}。保持 ${idea.statusPath} 中的 abandoned: true；只有明确决定恢复时才移除它，或者讨论另一个目标并运行 silvermoon create-idea。`,
+    );
+  }
+  return localize(
+    language,
+    `Review completed idea ${name} at ${idea.relativePath}. If its definition must change, revise the existing idea; otherwise discuss a new goal and run silvermoon create-idea.`,
+    `复查位于 ${idea.relativePath} 的已完成 idea ${name}。若其定义需要变化则修订现有 idea；否则讨论新目标并运行 silvermoon create-idea。`,
   );
 }
 
-function selectIdea(ideas, selector) {
-  if (!selector) return null;
-  return ideas.find(({ id, alias }) => id === selector || alias === selector) ?? null;
+function navigationInstruction(ideas, language) {
+  const hasActiveIdea = ideas.some(({ state }) =>
+    state === "preparing" || state === "implementing" || state === "deploying"
+  );
+  return joinInstructions([
+    localize(
+      language,
+      "Choose explicitly whether to continue an active idea or create a new one.",
+      "请明确选择继续一个 active idea，或创建一个新 idea。",
+    ),
+    hasActiveIdea
+      ? null
+      : localize(language, "No active ideas are available.", "当前没有 active idea。"),
+    localize(
+      language,
+      "To continue, run `silvermoon whats-next <ULID-or-alias>`. To start something else, discuss the goal and run `silvermoon create-idea`.",
+      "如需继续，运行 `silvermoon whats-next <ULID-or-alias>`；如需开始其他工作，先讨论目标，再运行 `silvermoon create-idea`。",
+    ),
+  ]);
 }
 
-function worktreeAction(root, config, observedPrimaryCommit) {
-  const symbolic = runGit(root, ["symbolic-ref", "--quiet", "HEAD"]);
-  const expectedBranch = `refs/heads/${config.primaryBranch}`;
-  if (!symbolic.ok || symbolic.stdout !== expectedBranch) {
-    return action(
-      "switch-to-primary",
-      `Preserve current work, then switch to configured primary branch ${config.primaryBranch}.`,
-      { actual: symbolic.ok ? symbolic.stdout : null, expected: expectedBranch },
-    );
-  }
-
-  const status = runGit(root, ["status", "--porcelain=v2", "-z", "--untracked-files=all"]);
-  if (!status.ok) {
-    return action(
-      "inspect-worktree-changes",
-      "Worktree changes could not be inspected; repair Git state before continuing.",
-      { error: status.stderr },
-    );
-  }
+async function assessRepositoryReadinessInternal({
+  observed,
+  outcomes,
+  requirePrimaryBranch = false,
+  recheckCommand = "silvermoon whats-next",
+  root,
+  synchronizePrimary = true,
+}) {
+  const language = observed.language;
   let changes;
   try {
-    changes = parseWorktreeChanges(status.stdout);
+    changes = inspectWorktreeChanges(root);
   } catch (caught) {
-    return action(
-      "inspect-worktree-changes",
-      "Worktree changes could not be parsed; inspect Git state before continuing.",
-      { error: caught.message },
-    );
-  }
-  if (changes.conflicted.length > 0) {
-    return action(
-      "resolve-conflicts",
-      "Resolve worktree conflicts without discarding either side, then run whats-next again.",
-      changes,
-    );
+    const problem = {
+      type: "worktree-inspection-failed",
+      summary: sanitizeGitMessage(caught.message),
+    };
+    return {
+      observation: repositoryProblemObservation(observed.observation, [problem]),
+      instructions: localize(
+        language,
+        `Repair the local Git state, verify that all changes can be inspected, then run ${command(root, recheckCommand)} again.`,
+        `修复本地 Git 状态，确认可检查全部修改后，再运行 ${command(root, recheckCommand)}。`,
+      ),
+      ready: false,
+    };
   }
-  if (changes.staged.length > 0 || changes.unstaged.length > 0 || changes.untracked.length > 0) {
-    return action(
-      "inspect-worktree-changes",
-      "Inspect the exact worktree diff; preserve unknown work and commit, isolate, or explicitly handle each path.",
-      changes,
-    );
+
+  const dirty =
+    changes.conflicted.length > 0
+    || changes.staged.length > 0
+    || changes.unstaged.length > 0
+    || changes.untracked.length > 0;
+  const localProblems = [];
+  const localSteps = [];
+  if (dirty) {
+    if (changes.conflicted.length > 0) {
+      localProblems.push({
+        type: "worktree-conflicts",
+        summary: localize(
+          language,
+          `${changes.conflicted.length} conflicted path(s); ${summarizeWorktreeChanges({
+            conflicted: changes.conflicted,
+            staged: [],
+            unstaged: [],
+            untracked: [],
+          }, language)}`,
+          `${changes.conflicted.length} 个冲突路径；${summarizeWorktreeChanges({
+            conflicted: changes.conflicted,
+            staged: [],
+            unstaged: [],
+            untracked: [],
+          }, language)}`,
+        ),
+      });
+    }
+    if (
+      changes.staged.length > 0
+      || changes.unstaged.length > 0
+      || changes.untracked.length > 0
+    ) {
+      localProblems.push({
+        type: "worktree-changes",
+        summary: summarizeWorktreeChanges({
+          conflicted: [],
+          staged: changes.staged,
+          unstaged: changes.unstaged,
+          untracked: changes.untracked,
+        }, language),
+      });
+    }
+    localSteps.push(...worktreeInstructionSteps(changes, language));
   }
 
-  const local = runGit(root, ["rev-parse", "HEAD"]);
-  if (!local.ok) {
-    return action(
-      "integrate-primary",
-      "Local HEAD is unavailable; repair the primary checkout before continuing.",
-      { error: local.stderr },
-    );
+  const head = resolveHead(root);
+  if (head === null) {
+    localProblems.push({
+      type: "head-missing",
+      summary: localize(
+        language,
+        "The repository has no commit at HEAD.",
+        "repository 的 HEAD 尚无 commit。",
+      ),
+    });
+    localSteps.push(localize(
+      language,
+      "After resolving conflicts and deciding which local changes belong, create the initial commit on the intended branch.",
+      "解决冲突并确认应保留的本地修改后，在预期分支创建初始 commit。",
+    ));
   }
-  if (local.stdout === observedPrimaryCommit) return null;
-  if (runGit(root, ["merge-base", "--is-ancestor", local.stdout, observedPrimaryCommit]).ok) {
-    return action(
-      "fast-forward-primary",
-      `Fast-forward local ${config.primaryBranch} to observed primary ${observedPrimaryCommit}.`,
-      { from: local.stdout, to: observedPrimaryCommit },
-    );
+
+  const branch = inspectCurrentBranch(root);
+  if (branch.branch === null) {
+    localProblems.push({
+      type: "detached-head",
+      summary: localize(
+        language,
+        head === null
+          ? "The repository has no current local branch."
+          : `HEAD ${head} is detached and has no current branch.`,
+        head === null
+          ? "repository 当前没有本地分支。"
+          : `HEAD ${head} 处于 detached 状态，没有当前分支。`,
+      ),
+    });
+    localSteps.push(localize(
+      language,
+      `Preserve current work, then switch to or create the intended local branch whose upstream is ${observed.config.primaryRepository}#${observed.config.primaryBranch}.`,
+      `保留当前工作，然后切换或创建 upstream 为 ${observed.config.primaryRepository}#${observed.config.primaryBranch} 的预期本地分支。`,
+    ));
+  } else {
+    if (requirePrimaryBranch && branch.branch !== observed.config.primaryBranch) {
+      localProblems.push({
+        type: "primary-branch-mismatch",
+        summary: localize(
+          language,
+          `Current branch is ${branch.branch}; expected configured primary branch ${observed.config.primaryBranch}.`,
+          `当前分支为 ${branch.branch}；预期为 configured primary branch ${observed.config.primaryBranch}。`,
+        ),
+      });
+      localSteps.push(localize(
+        language,
+        `Preserve current work, then switch to configured primary branch ${observed.config.primaryBranch}.`,
+        `保留当前工作，然后切换到 configured primary branch ${observed.config.primaryBranch}。`,
+      ));
+    }
+    if (
+      branch.repository !== observed.config.primaryRepository
+      || branch.upstreamBranch !== observed.config.primaryBranch
+    ) {
+    const actual = branch.remote === null
+      ? localize(language, "none", "无")
+      : `${branch.repository ?? branch.remote}#${branch.upstreamBranch ?? localize(language, "unknown", "未知")}`;
+    localProblems.push({
+      type: "primary-upstream-mismatch",
+      summary: localize(
+        language,
+        `Branch ${branch.branch} has upstream ${actual}; expected ${observed.config.primaryRepository}#${observed.config.primaryBranch}.`,
+        `分支 ${branch.branch} 的 upstream 是 ${actual}；预期为 ${observed.config.primaryRepository}#${observed.config.primaryBranch}。`,
+      ),
+    });
+    localSteps.push(localize(
+      language,
+      `Configure a named remote for ${observed.config.primaryRepository}, then set branch ${branch.branch} to track that remote's ${observed.config.primaryBranch} branch. Verify with ${command(root, 'git -C "<root>" rev-parse --abbrev-ref --symbolic-full-name \'@{upstream}\'')}.`,
+      `为 ${observed.config.primaryRepository} 配置 named remote，再将分支 ${branch.branch} 的 upstream 设为该 remote 的 ${observed.config.primaryBranch}。使用 ${command(root, 'git -C "<root>" rev-parse --abbrev-ref --symbolic-full-name \'@{upstream}\'')} 验证。`,
+    ));
+    }
   }
-  if (runGit(root, ["merge-base", "--is-ancestor", observedPrimaryCommit, local.stdout]).ok) {
-    return action(
-      "publish-primary",
-      `Validate and publish local primary ${local.stdout} with expected remote tip ${observedPrimaryCommit}.`,
-      {
-        repository: config.primaryRepository,
-        branch: config.primaryBranch,
-        commit: local.stdout,
-        expectedRemoteTip: observedPrimaryCommit,
-        validation: { target: "commit", revision: local.stdout },
-      },
-    );
+
+  if (localProblems.length > 0) {
+    return {
+      branch,
+      changes,
+      head,
+      observation: repositoryProblemObservation(
+        observed.observation,
+        localProblems,
+      ),
+      instructions: localRepositoryInstructions(
+        root,
+        localSteps,
+        language,
+        recheckCommand,
+      ),
+      ready: false,
+    };
   }
-  return action(
-    "integrate-primary",
-    "Preserve both local and remote primary histories and integrate them without force-pushing.",
-    { local: local.stdout, remote: observedPrimaryCommit },
-  );
-}
 
-async function lifecycleWhatsNext({
-  create = false,
-  idea: selector,
-  root = process.cwd(),
-  userHome,
-} = {}) {
-  const repositoryRoot = resolve(root);
-  const request = create
-    ? { kind: "create-idea" }
-    : selector === undefined
-      ? { kind: "navigate" }
-      : { kind: "select-idea", selector };
-  let local;
-  try {
-    local = await withTemporaryWorktree(repositoryRoot, "HEAD", (worktree) =>
-      loadConfig({ root: worktree }),
-    );
-  } catch (caught) {
-    return failed(repositoryRoot, [diagnostic(
-      "head.observation-failed",
-      caught.message,
-      "Restore a valid committed HEAD snapshot and retry.",
-    )], request);
+  if (!synchronizePrimary) {
+    return {
+      branch,
+      changes,
+      head,
+      observation: observed.observation,
+      ready: true,
+    };
   }
-  if (!local.config) return failed(repositoryRoot, local.diagnostics, request);
 
-  let observedPrimaryCommit;
+  let primary;
   try {
-    observedPrimaryCommit = fetchPrimary(repositoryRoot, local.config);
+    primary = fetchPrimary(root, observed.config);
+    outcomes.push(outcome(
+      "fetch-primary",
+      "success",
+      localize(
+        language,
+        `Fetched ${observed.config.primaryRepository}#${observed.config.primaryBranch} at ${primary} without moving the worktree, index, branch, or named refs.`,
+        `已 fetch ${observed.config.primaryRepository}#${observed.config.primaryBranch} 的 ${primary}，未移动 worktree、index、branch 或 named refs。`,
+      ),
+    ));
   } catch (caught) {
-    return failed(repositoryRoot, [diagnostic(
-      "primary.refresh-failed",
-      caught.message,
-      "Check network, authorization, repository URL, and primary branch, then retry.",
-    )], request);
+    const message = sanitizeGitMessage(caught.message);
+    outcomes.push(outcome(
+      "fetch-primary",
+      "failure",
+      localize(
+        language,
+        `Could not fetch configured primary: ${message}`,
+        `无法 fetch configured primary：${message}`,
+      ),
+    ));
+    return {
+      observation: repositoryProblemObservation(observed.observation, [{
+        type: "primary-fetch-failed",
+        summary: message,
+      }]),
+      instructions: localize(
+        language,
+        `Check network access, authorization, ${observed.config.primaryRepository}, and branch ${observed.config.primaryBranch}; after an observable fix, run ${command(root, recheckCommand)} again.`,
+        `检查网络、授权、${observed.config.primaryRepository} 和分支 ${observed.config.primaryBranch}；产生可观察修复后，再运行 ${command(root, recheckCommand)}。`,
+      ),
+      ready: false,
+    };
   }
 
-  let observed;
+  let relation;
   try {
-    observed = await withTemporaryWorktree(
-      repositoryRoot,
-      observedPrimaryCommit,
-      async (worktree, tree) => {
-        const loaded = await loadConfig({ root: worktree });
-        if (!loaded.config) return { config: null, diagnostics: loaded.diagnostics, ideas: [] };
-        const layout = await inspectIdeaLayout({
-          config: loaded.config,
-          gitRoot: repositoryRoot,
-          historyCommit: observedPrimaryCommit,
-          root: worktree,
-          snapshotTree: tree,
-        });
-        return { config: loaded.config, ...layout };
-      },
-    );
+    relation = compareCommits(root, head, primary);
   } catch (caught) {
-    return failed(repositoryRoot, [diagnostic(
-      "primary.observation-failed",
-      caught.message,
-      "Repair the fetched primary snapshot and retry.",
-    )], request, observedPrimaryCommit);
-  }
-  const observationDiagnostics = create
-    ? observed.diagnostics.filter(({ code }) => code !== "layout.ideas.missing")
-    : observed.diagnostics;
-  if (observationDiagnostics.length > 0) {
-    return failed(repositoryRoot, observationDiagnostics, request, observedPrimaryCommit);
+    return {
+      branch,
+      head,
+      observation: repositoryProblemObservation(observed.observation, [{
+        type: "primary-ancestry-inspection-failed",
+        summary: sanitizeGitMessage(caught.message),
+      }]),
+      primary,
+      instructions: localize(
+        language,
+        `Repair or deepen local Git history until ${head} and ${primary} can be compared, then run ${command(root, recheckCommand)} again.`,
+        `修复或补全本地 Git 历史，直到可以比较 ${head} 和 ${primary}，然后再运行 ${command(root, recheckCommand)}。`,
+      ),
+      ready: false,
+    };
   }
-
-  const loadedUserConfig = await loadUserConfig({ home: userHome });
-  if (loadedUserConfig.diagnostics.length > 0) {
-    return failed(
-      repositoryRoot,
-      loadedUserConfig.diagnostics,
-      request,
-      observedPrimaryCommit,
-    );
+  if (relation === "aligned") {
+    return { branch, head, observation: observed.observation, primary, ready: true };
   }
-  const requestedIdea = selectIdea(observed.ideas, selector);
-  const repositoryLanguage = {
-    project: observed.config.preferredLanguage,
-    global: loadedUserConfig.config?.preferredLanguage,
+  const problem = {
+    type: relation === "unknown"
+      ? "primary-history-incomplete"
+      : `primary-${relation}`,
+    summary: localize(
+      language,
+      `Local HEAD is ${head}; observed primary is ${primary}; relationship is ${relation}.`,
+      `本地 HEAD 为 ${head}；观测到的 primary 为 ${primary}；两者关系为 ${relation}。`,
+    ),
   };
-  const languageFor = (idea) => resolveLanguage({
-    idea: idea?.status.language,
-    ...repositoryLanguage,
-  });
-
-  const hygiene = worktreeAction(repositoryRoot, local.config, observedPrimaryCommit);
-  if (hygiene) {
-    return success(
-      repositoryRoot,
-      observedPrimaryCommit,
-      request,
-      null,
-      hygiene,
-      languageFor(requestedIdea),
+  let instructions;
+  if (relation === "unknown") {
+    instructions = localize(
+      language,
+      `Deepen the shallow history from remote ${branch.remote} until ${head} and ${primary} can be compared, then run ${command(root, recheckCommand)} again.`,
+      `从 remote ${branch.remote} 补全 shallow history，直到可以比较 ${head} 和 ${primary}，然后再运行 ${command(root, recheckCommand)}。`,
+    );
+  } else if (relation === "behind") {
+    instructions = localize(
+      language,
+      `Fast-forward branch ${branch.branch} to observed primary ${primary} with ${command(root, `git -C "<root>" merge --ff-only ${primary}`)} without rewriting history, then run ${command(root, recheckCommand)} again.`,
+      `使用 ${command(root, `git -C "<root>" merge --ff-only ${primary}`)} 将分支 ${branch.branch} fast-forward 到已观察 primary ${primary}，不要改写历史，然后再运行 ${command(root, recheckCommand)}。`,
+    );
+  } else if (relation === "ahead") {
+    instructions = localize(
+      language,
+      `Validate local commit ${head}, confirm the remote tip is still ${primary}, then push normally to ${branch.remote}/${observed.config.primaryBranch} without force. Re-run ${command(root, recheckCommand)} after the push.`,
+      `验证本地 commit ${head}，确认 remote tip 仍为 ${primary}，再普通 push 到 ${branch.remote}/${observed.config.primaryBranch}，不要 force。push 后重新运行 ${command(root, recheckCommand)}。`,
+    );
+  } else {
+    instructions = localize(
+      language,
+      `Preserve local ${head} and remote ${primary}, integrate both histories without force-pushing, resolve and validate the result, then run ${command(root, recheckCommand)} again.`,
+      `保留本地 ${head} 与 remote ${primary}，在不 force-push 的前提下整合两边历史，解决并验证结果，然后再运行 ${command(root, recheckCommand)}。`,
     );
   }
+  return {
+    branch,
+    head,
+    observation: repositoryProblemObservation(observed.observation, [problem]),
+    primary,
+    instructions,
+    ready: false,
+  };
+}
 
-  if (create) {
-    return success(repositoryRoot, observedPrimaryCommit, request, null, action(
-      "create-idea",
-      "Create one new three-world idea scaffold in .silvermoon/ideas/.",
-    ), languageFor());
-  }
-
-  if (!selector) {
-    const active = observed.ideas.filter(({ state }) => ACTIVE_STATES.has(state));
-    if (active.length > 1) {
-      return success(repositoryRoot, observedPrimaryCommit, request, null, action(
-        "select-active-idea",
-        "Select one active idea by ULID or unique alias.",
-        { ideas: active.map(summary) },
-      ), languageFor());
-    }
-    if (active.length === 1) {
-      return success(repositoryRoot, observedPrimaryCommit, request, active[0], action(
-        "continue-active-idea",
-        `Continue active idea ${ideaName(active[0])}.`,
-        { idea: summary(active[0]) },
-      ), languageFor(active[0]));
-    }
-    return success(repositoryRoot, observedPrimaryCommit, request, null, action(
-      "create-idea",
-      "Discuss the next goal and create one self-contained three-world idea.",
-    ), languageFor());
-  }
-
-  const selected = requestedIdea;
-  if (!selected) {
-    return failed(repositoryRoot, [diagnostic(
-      "idea.not-found",
-      `Idea ${selector} does not exist in observed primary ${observedPrimaryCommit}.`,
-      "Choose a ULID or exact alias reported by silvermoon whats-next.",
-      selector,
-    )], request, observedPrimaryCommit);
-  }
+export async function assessRepositoryReadiness(options) {
+  return traceAsync(
+    "repository.assess-readiness",
+    {},
+    () => assessRepositoryReadinessInternal(options),
+  );
+}
 
-  return success(
-    repositoryRoot,
-    observedPrimaryCommit,
-    request,
-    selected,
-    stateAction(selected),
-    languageFor(selected),
+export async function assessIdeaCreationReadiness(options) {
+  return traceAsync(
+    "repository.assess-creation-readiness",
+    {},
+    () => assessRepositoryReadinessInternal({
+      ...options,
+      requirePrimaryBranch: true,
+      synchronizePrimary: false,
+    }),
   );
 }
 
 export async function whatsNext({
-  create = false,
-  enforceOnboarding = false,
   idea: selector,
   root = process.cwd(),
   userHome,
 } = {}) {
-  const repositoryRoot = resolve(root);
-  const onboarding = await inspectAdoption({ root: repositoryRoot, selector });
-  const gapReport = onboardingGaps(onboarding);
-  const request = create
-    ? { kind: "create-idea" }
-    : selector === undefined
-      ? { kind: "navigate" }
-      : { kind: "select-idea", selector };
-  if (enforceOnboarding && onboarding.status !== "ready") {
-    const loadedUserConfig = await loadUserConfig({ home: userHome });
-    if (loadedUserConfig.diagnostics.length > 0) {
-      return failed(repositoryRoot, loadedUserConfig.diagnostics, request);
-    }
-    const language = resolveLanguage({
-      global: loadedUserConfig.config?.preferredLanguage,
-    });
-    return {
-      command: "whats-next",
-      ok: true,
-      root: repositoryRoot,
-      diagnostics: [],
-      result: {
-        observedPrimaryCommit: null,
-        request,
-        language,
-        selectedIdea: null,
-        onboarding: gapReport,
-        action: actionWithLanguage(action(
-          "adopt-silvermoon",
-          "Complete the blocking Silvermoon onboarding gaps before idea lifecycle work.",
-          {
-            gaps: gapReport.gaps,
-            recommendedAction: gapReport.recommendedAction,
-            recheck: gapReport.recheck,
-          },
-        ), language),
-      },
-    };
-  }
-  const report = await lifecycleWhatsNext({
-    create,
-    idea: selector,
-    root: repositoryRoot,
+  const requestedRoot = resolve(root);
+  const intention = {
+    command: "whats-next",
+    args: { idea: selector ?? null },
+  };
+  const recheckCommand = selector === undefined
+    ? "silvermoon whats-next"
+    : `silvermoon whats-next ${JSON.stringify(selector)}`;
+  const outcomes = [];
+  let observed = await observeSnapshot({
+    root: requestedRoot,
     userHome,
+    version: { type: "worktree" },
+  });
+  if (!observed.projectReady) {
+    return createEnvelope(
+      intention,
+      observed.observation,
+      outcomes,
+      projectInstructions(
+        observed,
+        observed.observation.root,
+        observed.language,
+        recheckCommand,
+      ),
+    );
+  }
+
+  const selected = selectIdea(observed.layout.ideas, selector);
+  if (selected?.status.language) {
+    observed = withObservationLanguage(observed, selected.status.language);
+  }
+  const readiness = await assessRepositoryReadiness({
+    observed,
+    outcomes,
+    recheckCommand,
+    root: observed.observation.root,
   });
-  if (report.result && gapReport) report.result.onboarding = gapReport;
-  return report;
-}
+  if (!readiness.ready) {
+    return createEnvelope(
+      intention,
+      readiness.observation,
+      outcomes,
+      readiness.instructions,
+    );
+  }
+
+  if (selector === undefined) {
+    return createEnvelope(
+      intention,
+      { ...readiness.observation, state: "navigation-ready" },
+      outcomes,
+      navigationInstruction(observed.layout.ideas, observed.language),
+    );
+  }
+  if (!selected) {
+    return createEnvelope(
+      intention,
+      dialogueReadyObservation(readiness.observation, "idea-not-found", {
+        candidates: readiness.observation.ideas.activeIdeas,
+      }),
+      outcomes,
+      joinInstructions([
+        localize(
+          observed.language,
+          `Idea ${selector} does not match an observed ULID or unique alias.`,
+          `Idea ${selector} 未匹配任何已观察到的 ULID 或唯一 alias。`,
+        ),
+        navigationInstruction(observed.layout.ideas, observed.language),
+      ]),
+    );
+  }
+  return createEnvelope(
+    intention,
+    dialogueReadyObservation(readiness.observation, "idea-selected", {
+      selectedIdea: {
+        id: selected.id,
+        ...(selected.alias === undefined ? {} : { alias: selected.alias }),
+        state: selected.state,
+      },
+    }),
+    outcomes,
+    lifecycleInstruction(selected, observed.language),
+  );
+}