opennori 0.1.6 → 0.1.7

package/.opennori/protocol.md

@@ -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
@@ -249,11 +254,12 @@ On every turn:
 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. Run `opennori resume --root <repo>` or `opennori next --root <repo>` to recover the active goal and current acceptance gap from repository files.
-12. Work only to produce evidence for that gap.
-13. 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.
-14. Run `opennori evaluate`.
-15. Report acceptance state, profile compliance, and evidence, not implementation steps.
+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:
 
@@ -269,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

@@ -94,6 +94,8 @@ language requests to the deterministic CLI state layer.
   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.6",
+  "version": "0.1.7",
   "description": "OpenNori: human-centered Nori Contracts and evidence records for coding agents.",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -39,6 +39,7 @@ const NORI_CAPABILITIES = [
   "skill-pack",
   "brainstorm",
   "acceptance-discovery",
+  "acceptance-quality-audit",
   "capability-profile",
   "profile-check",
   "archive",
@@ -428,30 +429,40 @@ function sentenceHasSpecifics(text, terms) {
   return terms.some((term) => value.includes(term.toLowerCase()));
 }
 
-function discoverAcceptance(goal, explicitId = undefined) {
-  const text = String(goal || "").trim();
+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, ["昵称", "头像", "简介", "邮箱", "手机号", "name", "avatar", "bio", "email", "phone"]);
-      if (gap.id === "missing-validation-rule") return !sentenceHasSpecifics(text, ["长度", "必填", "格式", "大小", "类型", "字符", "required", "format", "length", "size", "type"]);
+      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-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;
     });
 
-  const selectedGaps = gaps.length > 0 ? gaps : [
+  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",
@@ -469,6 +480,84 @@ function discoverAcceptance(goal, explicitId = undefined) {
   };
 }
 
+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));
 }
@@ -763,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."
     ]
   },
   {
@@ -1867,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,
@@ -1874,7 +1971,7 @@ export async function main(args) {
       upgrade_plan: upgradePlan,
       actions: upgradePlan.actions,
       manifest: dryRun ? buildManifest(root) : safeReadManifest(root)
-    }));
+    }, [], [], nextActions));
     return;
   }
 
@@ -2029,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;
   }