opennori 0.1.5 → 0.1.7

package/.opennori/protocol.md

@@ -145,7 +145,7 @@ OpenNori exposes a Skill Pack for agent use. The user should not need to remembe
 the root `nori` Skill routes natural-language requests to focused Skills:
 
 - `nori`: root router for OpenNori turns
-- `nori-acceptance`: brainstorm, draft, approve, and revise human-facing ACs
+- `nori-acceptance`: discover AC gaps, brainstorm, draft, approve, and revise human-facing ACs
 - `nori-evidence`: record reviewable evidence without forcing fixed adapters
 - `nori-capability-profile`: record required Skills, preferred stacks, avoided tools, and install policy
 - `nori-project-health`: install, uninstall, doctor, manifest, and Skill Pack sync
@@ -154,6 +154,11 @@ the root `nori` Skill routes natural-language requests to focused Skills:
 `opennori install --skill` installs the pack under `.agents/skills/`. The manifest records `skill_pack`
 state, and `opennori doctor` checks whether the pack is installed and in sync.
 
+When upgrading an existing OpenNori project, upgrade entry assets first, then run `opennori check`.
+`check` validates active Nori Contracts and reports `acceptance_quality` warnings for vague ACs
+such as "modify profile fields" or "show an error". It does not rewrite existing contracts, evidence,
+reports, archives, or brainstorms. The user decides whether to revise affected criteria.
+
 ## Nori Profile
 
 Acceptance criteria remain human-facing outcomes. A Nori Profile is separate execution
@@ -239,23 +244,27 @@ all evidence through a narrow adapter taxonomy.
 
 On every turn:
 
-1. If the user wants to discuss, brainstorm, explore, or is not ready to define acceptance criteria, run `opennori brainstorm --idea "<idea>" --root <repo> --json`.
-2. Show only candidate acceptance directions and ask the user to choose or revise a direction. Brainstorm output is not a contract or completion evidence.
-3. If the user chooses a candidate, run `opennori draft --from-brainstorm <brainstorm-id> --candidate <A|B|C> --root <repo> --json`.
-4. If the user starts with "use OpenNori" / "用 OpenNori 跑这个任务", run `opennori draft --goal "<goal>" --root <repo> --json`.
-5. Show the draft acceptance criteria and ask the user to approve or revise them.
-6. After approval, run `opennori approve --root <repo> --summary "<approval>" --json`.
-7. If the user states required Skills, preferred stacks, avoided tools, install policy, or execution constraints, run `opennori profile add --root <repo> ... --json` and keep those items out of the user acceptance criteria.
-8. If the user revises a criterion later, run `opennori criterion update --root <repo> --criterion <id> ... --json`; old evidence for the changed criterion is cleared.
-9. Run `opennori resume --root <repo>` or `opennori next --root <repo>` to recover the active goal and current acceptance gap from repository files.
-10. Work only to produce evidence for that gap.
-11. Add acceptance evidence with `opennori evidence add`; choose any suitable verification method, but record basis, sources, reviewability, confidence, and limitations. Add profile compliance evidence with `opennori profile evidence` when profile items exist.
-12. Run `opennori evaluate`.
-13. Report acceptance state, profile compliance, and evidence, not implementation steps.
+1. If the user gives a fuzzy goal or candidate AC, run `opennori discover --goal "<goal>" --root <repo> --json` before drafting.
+2. Ask only the discovery questions that affect completion judgment. Do not turn discovery gaps into implementation tasks or completion evidence.
+3. If the user wants to discuss, brainstorm, explore, or is not ready to define acceptance criteria, run `opennori brainstorm --idea "<idea>" --root <repo> --json`.
+4. Show only candidate acceptance directions and ask the user to choose or revise a direction. Brainstorm output is not a contract or completion evidence.
+5. If the user chooses a candidate, run `opennori draft --from-brainstorm <brainstorm-id> --candidate <A|B|C> --root <repo> --json`.
+6. If the user starts with "use OpenNori" / "用 OpenNori 跑这个任务" and discovery gaps are answered or explicitly accepted as assumptions, run `opennori draft --goal "<goal>" --root <repo> --json`.
+7. Show the draft acceptance criteria and ask the user to approve or revise them.
+8. After approval, run `opennori approve --root <repo> --summary "<approval>" --json`.
+9. If the user states required Skills, preferred stacks, avoided tools, install policy, or execution constraints, run `opennori profile add --root <repo> ... --json` and keep those items out of the user acceptance criteria.
+10. If the user revises a criterion later, run `opennori criterion update --root <repo> --criterion <id> ... --json`; old evidence for the changed criterion is cleared.
+11. If the user asks to upgrade an existing OpenNori project, run `opennori doctor`, preview and confirm `opennori upgrade`, then run `opennori check`; ask the user before revising any existing AC flagged by `acceptance_quality`.
+12. Run `opennori resume --root <repo>` or `opennori next --root <repo>` to recover the active goal and current acceptance gap from repository files.
+13. Work only to produce evidence for that gap.
+14. Add acceptance evidence with `opennori evidence add`; choose any suitable verification method, but record basis, sources, reviewability, confidence, and limitations. Add profile compliance evidence with `opennori profile evidence` when profile items exist.
+15. Run `opennori evaluate`.
+16. Report acceptance state, profile compliance, and evidence, not implementation steps.
 
 Useful commands:
 
 - `opennori brainstorm --idea "<idea>" --root <repo>`: create selectable acceptance directions before a contract exists.
+- `opennori discover --goal "<goal>" --root <repo>`: find underspecified acceptance gaps before drafting a contract.
 - `opennori draft --goal "<goal>" --root <repo>`: create a draft Nori Contract that needs user approval.
 - `opennori draft --from-brainstorm <brainstorm-id> --candidate <A|B|C> --root <repo>`: convert a selected brainstorm direction into a draft contract.
 - `opennori approve --root <repo>`: mark the acceptance basis as approved so completion can be decided.
@@ -266,7 +275,9 @@ Useful commands:
 - `opennori profile show --root <repo>`: show profile compliance and blocking items.
 - `opennori list --root <repo>`: list active OpenNori goals.
 - `opennori install --root <repo>`: create or refresh project-local OpenNori assets and manifest.
+- `opennori upgrade --root <repo>`: preview and refresh project-local OpenNori assets without rewriting active contracts or evidence.
 - `opennori doctor --root <repo>`: inspect project OpenNori health and recovery actions.
+- `opennori check --root <repo>`: validate active contract structure and audit active ACs for underspecified acceptance quality.
 - `opennori resume --root <repo>`: recover the active goal, current gap, completion answer, and intervention state.
 - `opennori status --root <repo>`: answer whether the goal is complete and whether the user needs to act.
 - `opennori report --root <repo>`: generate the human acceptance report.

package/README.md

@@ -45,6 +45,10 @@ Use OpenNori for this project. Start from my goal, define a Nori Contract,
 and keep working only from acceptance gaps until the report says whether it is complete.
 ```
 
+For fuzzy goals, ask Nori to discover the real acceptance gaps first. It should ask about missing
+field scope, validation rules, success signals, persistence, failure cases, and out-of-scope
+boundaries before it turns the goal into a Nori Contract.
+
 ## What Gets Added
 
 OpenNori uses one project-local state directory:
@@ -69,6 +73,7 @@ It does not create a `process/` directory as the main workflow surface.
 ```bash
 opennori bootstrap
 opennori doctor --root .
+opennori discover --goal "Ship a settings page" --root .
 opennori brainstorm --idea "Explore this goal" --root .
 opennori draft --goal "Ship a user-visible result" --root .
 opennori approve --root . --summary "User approved the acceptance checks."
@@ -87,6 +92,10 @@ language requests to the deterministic CLI state layer.
   require explicit confirmation.
 - In a human terminal, `npx opennori` is interactive. With `--json` or non-interactive stdio it
   returns structured JSON for agents and automation.
+- `discover` finds underspecified acceptance gaps before draft, so vague ACs such as "modify fields"
+  or "show an error" become user questions instead of weak contracts.
+- Existing projects keep their Nori Contracts and evidence during upgrade. After upgrading, `check`
+  audits active contracts for vague ACs and asks the user before any revision.
 - `doctor` reports whether project state is `ready`, `needs-action`, or `broken`, with recovery
   actions.
 - Nori Profile records required Skills, preferred stacks, avoided tools, and install policy without

package/examples/opennori-self.json

@@ -97,9 +97,9 @@
     {
       "id": "AC-P-12",
       "layer": "protocol",
-      "user_story": "作为用户，我运行 opennori check 后，能发现 AC 是否缺少真实用户操作或可观察结果，而不是只检查是否以“作为用户”开头。",
-      "measurement": "对包含“测试通过”“字段存在”等内部完成条件的验收草案运行 opennori check，再对包含真实用户操作和报告结果的草案运行 opennori check。",
-      "threshold": "内部完成条件会被拒绝；包含用户运行、打开、查看、确认等操作，并说明用户能看到或判断什么结果的 AC 可以通过。",
+      "user_story": "作为用户，我运行 opennori check 或让 agent 升级已使用 OpenNori 的项目后，能发现现有 active contract 里过于含糊的 AC，而不是让旧的弱验收标准静默通过。",
+      "measurement": "对已有 active goal 中包含“修改字段”“失败时有提示”等空泛完成条件的 Nori Contract 运行 opennori check；再对结构正确且包含具体用户操作、字段范围、反馈和判断方式的 contract 运行 check。",
+      "threshold": "check 在不改写历史 contract/evidence 的前提下输出 acceptance_quality 审计结果、warnings 和下一步建议；弱 AC 会标出缺少的字段范围、校验规则、成功反馈、失败场景或范围边界；具体 AC 不产生质量告警。",
       "risk": "high"
     },
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opennori",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "OpenNori: human-centered Nori Contracts and evidence records for coding agents.",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -38,6 +38,8 @@ const NORI_CAPABILITIES = [
   "reviewable-evidence",
   "skill-pack",
   "brainstorm",
+  "acceptance-discovery",
+  "acceptance-quality-audit",
   "capability-profile",
   "profile-check",
   "archive",
@@ -371,6 +373,191 @@ const DEFAULT_CRITERIA = [
   }
 ];
 
+const DISCOVERY_GAPS = [
+  {
+    id: "missing-field-scope",
+    patterns: ["设置", "资料", "个人资料", "profile", "settings", "字段", "field"],
+    question: "本轮用户可以修改或查看哪些具体字段？哪些字段明确不在范围内？",
+    why: "没有字段范围，用户无法判断修改能力是否完整。"
+  },
+  {
+    id: "missing-validation-rule",
+    patterns: ["修改", "输入", "保存", "上传", "表单", "edit", "input", "save", "upload", "form"],
+    question: "每个可输入内容的有效规则是什么，例如长度、必填、格式、文件类型或大小？",
+    why: "没有校验规则，失败和边界输入无法验收。"
+  },
+  {
+    id: "missing-success-signal",
+    patterns: ["保存", "提交", "创建", "更新", "完成", "save", "submit", "create", "update"],
+    question: "操作成功后，用户会看到什么明确反馈或结果变化？",
+    why: "没有成功反馈，用户无法判断操作是否真的完成。"
+  },
+  {
+    id: "missing-persistence-scope",
+    patterns: ["保存", "刷新", "重新打开", "重新登录", "持久", "save", "refresh", "reload", "reopen", "login", "persist"],
+    question: "结果需要在刷新、重新打开、重新登录或跨设备后仍然存在吗？",
+    why: "没有持久化范围，完成判断会在当前页面和真实保存之间摇摆。"
+  },
+  {
+    id: "missing-failure-case",
+    patterns: ["失败", "错误", "提示", "网络", "权限", "error", "fail", "failure", "invalid", "permission", "network"],
+    question: "哪些失败情况必须覆盖，用户分别应该看到什么提示或保留什么原状态？",
+    why: "没有失败场景，错误体验可能被一句“有提示”掩盖。"
+  },
+  {
+    id: "missing-out-of-scope-boundary",
+    patterns: ["页面", "页", "设置", "功能", "支持", "完成", "page", "feature", "support", "complete"],
+    question: "哪些相关能力明确不属于本轮完成范围？",
+    why: "没有范围边界，agent 可能扩大实现，也可能漏掉用户真正期待的部分。"
+  },
+  {
+    id: "missing-user-entry",
+    patterns: ["使用", "打开", "查看", "进入", "run", "open", "view", "use", "entry"],
+    question: "用户从哪个入口开始操作，最终在哪里查看结果？",
+    why: "没有用户入口，AC 容易变成内部状态而不是可执行验收。"
+  },
+  {
+    id: "missing-review-method",
+    patterns: ["判断", "验收", "完成", "review", "accept", "done", "complete"],
+    question: "用户或评审者应该用什么可复查方式判断这条 AC 通过？",
+    why: "没有复查方式，完成判断会退化成 agent 自我总结。"
+  }
+];
+
+function sentenceHasSpecifics(text, terms) {
+  const value = String(text || "").toLowerCase();
+  return terms.some((term) => value.includes(term.toLowerCase()));
+}
+
+function discoverAcceptanceGaps(text, { fallback = false, allowedIds = null } = {}) {
+  const lowered = text.toLowerCase();
+  const gaps = DISCOVERY_GAPS
+    .filter((gap) => !allowedIds || allowedIds.has(gap.id))
+    .filter((gap) => gap.patterns.some((pattern) => lowered.includes(pattern.toLowerCase())))
+    .filter((gap) => {
+      if (gap.id === "missing-field-scope") return !sentenceHasSpecifics(text, ["昵称", "头像", "简介", "邮箱", "手机号", "字段范围", "field scope", "name", "avatar", "bio", "email", "phone"]);
+      if (gap.id === "missing-validation-rule") return !sentenceHasSpecifics(text, ["长度", "必填", "格式", "大小", "类型", "字符", "校验规则", "validation", "required", "format", "length", "size", "type"]);
+      if (gap.id === "missing-success-signal") return !sentenceHasSpecifics(text, ["成功", "保存成功", "成功反馈", "result", "success"]);
+      if (gap.id === "missing-persistence-scope") return !sentenceHasSpecifics(text, ["刷新", "重新打开", "重新登录", "跨设备", "refresh", "reload", "reopen", "login"]);
+      if (gap.id === "missing-failure-case") return !sentenceHasSpecifics(text, ["网络", "权限", "无效", "错误码", "保留原", "失败场景", "network", "permission", "invalid"]);
+      if (gap.id === "missing-out-of-scope-boundary") return !sentenceHasSpecifics(text, ["不在范围", "不包含", "本轮不", "范围边界", "out of scope", "exclude"]);
+      if (gap.id === "missing-user-entry") return !sentenceHasSpecifics(text, ["设置页", "登录页", "report", "dashboard", "页面", "page"]);
+      if (gap.id === "missing-review-method") return !sentenceHasSpecifics(text, ["截图", "浏览器", "报告", "测试", "review", "screenshot", "browser", "report"]);
+      return true;
+    });
+
+  if (gaps.length > 0 || !fallback) return gaps;
+  return [
+    {
+      id: "missing-review-method",
+      question: "用户或评审者应该用什么可复查方式判断这个目标完成？",
+      why: "OpenNori 需要先知道完成判断方式，才能形成真正可验收的 AC。"
+    }
+  ];
+}
+
+function discoveryGap(gapId) {
+  return DISCOVERY_GAPS.find((gap) => gap.id === gapId);
+}
+
+function discoverAcceptance(goal, explicitId = undefined) {
+  const text = String(goal || "").trim();
+  const selectedGaps = discoverAcceptanceGaps(text, { fallback: true });
+
+  return {
+    protocol_version: "opennori/discovery-v1",
+    id: explicitId || slugify(text.slice(0, 40) || "acceptance-discovery"),
+    goal: text,
+    status: selectedGaps.length > 0 ? "needs-user-answers" : "ready-for-draft",
+    is_acceptance_contract: false,
+    gaps: selectedGaps.map((gap, index) => ({
+      id: gap.id,
+      question: gap.question,
+      why: gap.why,
+      priority: index < 3 ? "must-answer" : "can-default"
+    })),
+    next: "Ask the must-answer questions before drafting a Nori Contract. Use assumptions only when the user accepts them."
+  };
+}
+
+function auditAcceptanceQuality(contract) {
+  const findings = [];
+  for (const [index, criterion] of (contract.criteria || []).entries()) {
+    const triggerText = [
+      criterion.user_story,
+      criterion.threshold
+    ].filter(Boolean).join("\n");
+    const fullText = [
+      criterion.user_story,
+      criterion.measurement,
+      criterion.threshold
+    ].filter(Boolean).join("\n");
+    const addFinding = (gapId) => {
+      const gap = discoveryGap(gapId);
+      if (!gap) return;
+      findings.push({
+        criterion_id: criterion.id,
+        path: `criteria[${index}]`,
+        gap_id: gap.id,
+        question: gap.question,
+        why: gap.why,
+        severity: "needs-user-review"
+      });
+    };
+
+    const vagueEditableProfile = sentenceHasSpecifics(triggerText, [
+      "修改个人资料",
+      "修改资料",
+      "修改字段",
+      "编辑个人资料",
+      "编辑资料",
+      "edit profile",
+      "update profile",
+      "modify fields",
+      "edit fields"
+    ]);
+    if (vagueEditableProfile && !sentenceHasSpecifics(fullText, ["昵称", "头像", "简介", "邮箱", "手机号", "字段范围", "field scope", "name", "avatar", "bio", "email", "phone"])) {
+      addFinding("missing-field-scope");
+    }
+    if (vagueEditableProfile && !sentenceHasSpecifics(fullText, ["长度", "必填", "格式", "大小", "类型", "字符", "校验规则", "validation", "required", "format", "length", "size", "type"])) {
+      addFinding("missing-validation-rule");
+    }
+
+    const mentionsSave = sentenceHasSpecifics(triggerText, ["保存", "提交", "save", "submit"]);
+    if (mentionsSave && !sentenceHasSpecifics(fullText, ["保存成功", "成功反馈", "成功提示", "显示成功", "报告显示", "result", "success"])) {
+      addFinding("missing-success-signal");
+    }
+    if (mentionsSave && !sentenceHasSpecifics(fullText, ["刷新", "重新打开", "重新登录", "跨设备", "refresh", "reload", "reopen", "login"])) {
+      addFinding("missing-persistence-scope");
+    }
+
+    const vagueFailure = sentenceHasSpecifics(triggerText, [
+      "失败时有提示",
+      "失败提示",
+      "有提示",
+      "错误提示",
+      "show an error",
+      "error message"
+    ]);
+    if (vagueFailure && !sentenceHasSpecifics(fullText, ["网络", "权限", "无效", "错误码", "保留原", "失败场景", "network", "permission", "invalid"])) {
+      addFinding("missing-failure-case");
+    }
+
+    const broadSettingsScope = sentenceHasSpecifics(triggerText, ["设置页", "个人资料", "settings page"]);
+    if (broadSettingsScope && !sentenceHasSpecifics(fullText, ["不在范围", "不包含", "本轮不", "范围边界", "out of scope", "exclude"])) {
+      addFinding("missing-out-of-scope-boundary");
+    }
+  }
+
+  return {
+    status: findings.length > 0 ? "needs-user-review" : "clear",
+    summary: findings.length > 0
+      ? `${findings.length} acceptance quality gap(s) may need user review.`
+      : "No underspecified acceptance gaps found.",
+    findings
+  };
+}
+
 function printJson(payload) {
   console.log(JSON.stringify(payload, null, 2));
 }
@@ -398,7 +585,7 @@ function isInteractive(args) {
 }
 
 const CLI_NAME = "opennori";
-const TOP_LEVEL_USAGE = `${CLI_NAME} <bootstrap|doctor|install|upgrade|uninstall|brainstorm|draft|init|list|check|approve|criterion|profile|resume|next|evidence|evaluate|status|report|context|changes|archive|skill>`;
+const TOP_LEVEL_USAGE = `${CLI_NAME} <bootstrap|doctor|install|upgrade|uninstall|brainstorm|discover|draft|init|list|check|approve|criterion|profile|resume|next|evidence|evaluate|status|report|context|changes|archive|skill>`;
 
 function wantsHelp(args) {
   return args.includes("--help") || args.includes("-h");
@@ -413,6 +600,7 @@ function usageFor(args) {
   if (command === "uninstall") return `${CLI_NAME} uninstall --root <project> [--include-state] [--dry-run] [--confirm] [--json]`;
   if (command === "doctor") return `${CLI_NAME} doctor --root <project> [--json]`;
   if (command === "brainstorm") return `${CLI_NAME} brainstorm --idea "<idea>" --root <project> [--id <id>] [--json]`;
+  if (command === "discover") return `${CLI_NAME} discover --goal "<goal>" --root <project> [--id <id>] [--json]`;
   if (command === "draft") return `${CLI_NAME} draft --goal "<goal>" --root <project> [--goal-id <id>] [--json]`;
   if (command === "init") return `${CLI_NAME} init <brief.json> --root <project> [--json]`;
   if (command === "criterion" && subcommand === "update") return `${CLI_NAME} criterion update --root <project> --criterion <id> --user-story ... --measurement ... --threshold ... [--json]`;
@@ -573,7 +761,7 @@ const SKILL_PACK = [
       "Use when the user mentions OpenNori, asks to use OpenNori for a task, continue OpenNori, check completion, inspect project health, define acceptance criteria, record evidence, manage capability preferences, or produce an OpenNori report.",
       "",
       "## Route",
-      "- Goal, brainstorm, approval, or AC revision -> use `nori-acceptance`.",
+      "- Goal, acceptance discovery, brainstorm, approval, or AC revision -> use `nori-acceptance`.",
       "- Verification, evidence sufficiency, human confirmation, waiver, or why an AC is passing -> use `nori-evidence`.",
       "- Required Skills, preferred stacks, avoided tools, or install policy -> use `nori-capability-profile`.",
       "- Install, uninstall, doctor, manifest, Skill sync, or project recoverability -> use `nori-project-health`.",
@@ -596,9 +784,10 @@ const SKILL_PACK = [
     description: "Create, review, approve, and revise OpenNori human-centered acceptance criteria from natural language goals.",
     body: [
       "## When to use",
-      "Use when the user gives a goal, wants to brainstorm acceptance directions, approves criteria, revises completion criteria, or says the AC is wrong.",
+      "Use when the user gives a goal, wants to discover real acceptance criteria, wants to brainstorm acceptance directions, approves criteria, revises completion criteria, or says the AC is wrong.",
       "",
       "## Commands",
+      "- Before drafting from a fuzzy goal: `opennori discover --goal \"<goal>\" --root <repo> --json`.",
       "- Fuzzy idea or discussion: `opennori brainstorm --idea \"<idea>\" --root <repo> --json`.",
       "- Start from a goal: `opennori draft --goal \"<goal>\" --root <repo> --json`.",
       "- Start from a chosen brainstorm candidate: `opennori draft --from-brainstorm <brainstorm-id> --candidate <A|B|C> --root <repo> --json`.",
@@ -606,6 +795,9 @@ const SKILL_PACK = [
       "- User revises a criterion: `opennori criterion update --root <repo> --criterion <id> --user-story ... --measurement ... --threshold ... --json`.",
       "",
       "## Rules",
+      "Run discovery before draft when the goal or candidate AC contains vague verbs such as modify, save, support, show an error, or improve.",
+      "Discovery gaps are questions for the user, not implementation tasks and not completion evidence.",
+      "Do not draft generic ACs like 'modify fields' or 'show failure prompt' until field scope, validation rules, success signal, persistence scope, failure cases, and out-of-scope boundaries are clear enough for the user to judge.",
       "ACs must describe user actions or judgments, not implementation files, commands, modules, fields, tests, Skills, or technology choices.",
       "Capability preferences belong in the Nori Profile, not user ACs.",
       "Do not treat brainstorm output as a Nori Contract or completion evidence."
@@ -660,16 +852,20 @@ const SKILL_PACK = [
       "- Confirm first-time setup after user approval: `opennori bootstrap --root <repo> --confirm --json`.",
       "- Preview install: `opennori install --root <repo> --dry-run --json`.",
       "- Install Skill Pack: `opennori install --root <repo> --skill --json`.",
+      "- Preview upgrade: `opennori upgrade --root <repo> --skill --dry-run --json`.",
+      "- Confirm upgrade after user approval: `opennori upgrade --root <repo> --skill --confirm --json`.",
       "- Preview destructive install: `opennori install --root <repo> --skill --force --dry-run --json`.",
       "- Confirm destructive install: `opennori install --root <repo> --skill --force --confirm --json`.",
       "- Doctor: `opennori doctor --root <repo> --json`.",
+      "- Existing contract check after upgrade: `opennori check --root <repo> --json`.",
       "- Preview uninstall: `opennori uninstall --root <repo> --dry-run --json`.",
       "- Remove entry assets while preserving state: `opennori uninstall --root <repo> --confirm --json`.",
       "- Remove all OpenNori state only after explicit user acceptance: `opennori uninstall --root <repo> --include-state --confirm --json`.",
       "",
       "## Rules",
       "Always show dry-run plans before destructive writes.",
-      "Default uninstall preserves active goals, evidence, reports, archives, and brainstorms."
+      "Default uninstall preserves active goals, evidence, reports, archives, and brainstorms.",
+      "Upgrade must preserve existing active contracts and evidence. After upgrade, run `opennori check` and route any `acceptance_quality` warnings to `nori-acceptance` for user-approved revision."
     ]
   },
   {
@@ -1354,6 +1550,47 @@ function brainstormPaths(root, brainstormId) {
   };
 }
 
+function discoveryPaths(root, discoveryId) {
+  const dir = path.join(root, ".opennori", "brainstorms");
+  return {
+    jsonPath: path.join(dir, `${discoveryId}.discovery.json`),
+    markdownPath: path.join(dir, `${discoveryId}.discovery.md`)
+  };
+}
+
+function renderDiscoveryMarkdown(discovery) {
+  const lines = [
+    `# ${discovery.id} Acceptance Discovery`,
+    "",
+    "## Goal",
+    "",
+    discovery.goal,
+    "",
+    "## Rule",
+    "",
+    "This is an acceptance discovery source, not a Nori Contract, process plan, or completion evidence.",
+    "",
+    "## Acceptance Gaps",
+    ""
+  ];
+
+  for (const gap of discovery.gaps) {
+    lines.push(
+      `### ${gap.id}`,
+      "",
+      `Priority: ${gap.priority}`,
+      "",
+      `Question: ${gap.question}`,
+      "",
+      `Why it matters: ${gap.why}`,
+      ""
+    );
+  }
+
+  lines.push("## Next", "", discovery.next);
+  return `${lines.join("\n")}\n`;
+}
+
 function renderBrainstormMarkdown(brainstorm) {
   const lines = [
     `# ${brainstorm.id} Brainstorm`,
@@ -1723,6 +1960,10 @@ export async function main(args) {
       writeManifest(root);
     }
 
+    const nextActions = dryRun
+      ? ["Review the upgrade plan, then rerun with --confirm if the planned updates are acceptable."]
+      : ["Run opennori check --root <project> --json to audit existing active Nori Contracts for underspecified ACs before continuing work."];
+
     printJson(ok({
       root,
       dry_run: dryRun,
@@ -1730,7 +1971,7 @@ export async function main(args) {
       upgrade_plan: upgradePlan,
       actions: upgradePlan.actions,
       manifest: dryRun ? buildManifest(root) : safeReadManifest(root)
-    }));
+    }, [], [], nextActions));
     return;
   }
 
@@ -1764,6 +2005,37 @@ export async function main(args) {
     return;
   }
 
+  if (command === "discover") {
+    const root = resolveRoot(args);
+    const goal = String(argValue(args, "--goal", argValue(args, "--idea", ""))).trim();
+    if (!goal) throw new Error("--goal is required");
+    const discovery = discoverAcceptance(goal, argValue(args, "--id"));
+    const paths = discoveryPaths(root, discovery.id);
+    writeJson(paths.jsonPath, discovery);
+    fs.mkdirSync(path.dirname(paths.markdownPath), { recursive: true });
+    fs.writeFileSync(paths.markdownPath, renderDiscoveryMarkdown(discovery));
+    refreshManifest(root);
+    printJson(ok(
+      {
+        discovery_id: discovery.id,
+        status: discovery.status,
+        goal: discovery.goal,
+        gaps: discovery.gaps,
+        questions: discovery.gaps.map((gap) => gap.question),
+        discovery_path: paths.jsonPath,
+        markdown_path: paths.markdownPath,
+        is_acceptance_contract: false
+      },
+      [
+        { kind: "acceptance_discovery", path: paths.jsonPath },
+        { kind: "acceptance_discovery_markdown", path: paths.markdownPath }
+      ],
+      [],
+      [discovery.next]
+    ));
+    return;
+  }
+
   if (command === "draft") {
     const root = resolveRoot(args);
     const brainstormId = argValue(args, "--from-brainstorm");
@@ -1854,12 +2126,23 @@ export async function main(args) {
       process.exitCode = 1;
       return;
     }
+    const acceptanceQuality = auditAcceptanceQuality(contract);
+    const warnings = acceptanceQuality.findings.map((finding) => ({
+      type: "acceptance_quality",
+      criterion_id: finding.criterion_id,
+      gap_id: finding.gap_id,
+      message: finding.question
+    }));
+    const nextActions = acceptanceQuality.status === "needs-user-review"
+      ? ["Ask the user the acceptance_quality questions, then revise the affected criteria before relying on this contract as complete."]
+      : [];
     printJson(ok({
       goal_id: contract.goal_id,
       workflow_status: ledger.status,
       current_gap: currentGap(contract, ledger),
-      statuses: Object.fromEntries(Object.entries(ledger.criteria).map(([id, state]) => [id, state.status]))
-    }));
+      statuses: Object.fromEntries(Object.entries(ledger.criteria).map(([id, state]) => [id, state.status])),
+      acceptance_quality: acceptanceQuality
+    }, [], warnings, nextActions));
     return;
   }