artifact-graph 0.8.3 → 0.8.4

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 0.8.4
+
+### Changed
+
+- Version-lock audit and refresh Markdown now explains findings in Chinese, labels each item as a
+  blocking error or non-blocking warning, and includes concrete review, refresh, cleanup, and staging
+  commands.
+- `missing_lock` remains non-blocking by default and is promoted only by
+  `--strict-missing-lock`; runner liveness findings are warnings and no longer fail commits on their
+  own. Markdown summaries and CLI exit codes now share the same policy decision.
+- `version-lock refresh --all --remove-orphans` is documented in CLI help and remediation output as
+  the safe cleanup path after deleting, renaming, or splitting artifacts. Structural orphan locks
+  remain blocking until the user explicitly reviews and removes them.
+
+### Fixed
+
+- Pre-commit guidance now distinguishes a successful refresh that changed the lock file from a
+  validation failure, and gives the exact review, stage, and retry steps.
+
 ## 0.8.3
 
 ### Fixed

package/INSTALL.md

@@ -90,6 +90,27 @@ npx artifact-graph version-lock audit --root . --strict-missing-lock
 > Use `version-lock refresh --all` for the initial lock. The `--changed-only --staged` variant is for
 > pre-commit hooks on existing projects — not for first-time initialization.
 
+## Cleaning Up Orphan Locks
+
+After deleting or splitting an artifact (or removing a traceability edge), the affected version
+locks become orphans. Refresh retains them by default; clean them up explicitly and review the
+result before staging:
+
+```bash
+# pnpm
+pnpm exec artifact-graph version-lock refresh --all --remove-orphans --format markdown
+git diff artifacts/traceability-version-lock.json   # review the removed lock entries
+git add artifacts/traceability-version-lock.json    # stage, then commit again
+
+# npm
+npx artifact-graph version-lock refresh --all --remove-orphans --format markdown
+git diff artifacts/traceability-version-lock.json
+git add artifacts/traceability-version-lock.json
+```
+
+`version-lock audit` reports structural orphan locks and stale hashes as blocking issues with
+remediation steps; runner liveness findings are non-blocking warnings.
+
 ## Smoke Test
 
 Run these commands to confirm the installation is working:

package/README.md

@@ -73,6 +73,28 @@ npx artifact-graph version-lock audit --root . --strict-missing-lock
   having an empty relation list; run `refresh --all` once to establish the complete relation baseline.
 - Install opt-in Git hooks with `artifact-graph hooks install-git --hook all`.
 
+### Cleaning Up Orphan Locks After Deleting or Splitting Artifacts
+
+When an artifact, source file, or traceability edge no longer exists — typically after deleting
+or splitting an artifact — its version locks become orphans. `version-lock refresh` retains
+orphan locks by default so cleanup stays an explicit, reviewable decision:
+
+```bash
+# pnpm
+pnpm exec artifact-graph version-lock refresh --all --remove-orphans --format markdown
+git diff artifacts/traceability-version-lock.json   # review the removed lock entries
+git add artifacts/traceability-version-lock.json    # stage, then commit again
+
+# npm
+npx artifact-graph version-lock refresh --all --remove-orphans --format markdown
+git diff artifacts/traceability-version-lock.json
+git add artifacts/traceability-version-lock.json
+```
+
+`version-lock audit` marks structural orphan locks and stale hashes as blocking issues and prints
+these same remediation steps. Runner liveness findings (a test file no longer active in any
+configured runner) are warnings only and do not block.
+
 ## Review Result Protocol
 
 The package publishes `schemas/review-result.schema.json`, plus matching TypeScript types and a

package/README.zh-CN.md

@@ -69,6 +69,26 @@ npx artifact-graph version-lock audit --root . --strict-missing-lock
   `artifactRelations` 时视为空数组；首次启用时执行一次 `refresh --all` 建立完整关系基线。
 - 用 `artifact-graph hooks install-git --hook all` 安装可选 Git hooks。
 
+### 制品删除或拆分后的孤立锁清理
+
+当制品、源码文件或追溯边不再存在时（常见于制品删除或拆分之后），对应的版本锁会成为
+孤立锁。`version-lock refresh` 默认保留孤立锁，让清理始终是一次显式、可审查的操作：
+
+```bash
+# pnpm
+pnpm exec artifact-graph version-lock refresh --all --remove-orphans --format markdown
+git diff artifacts/traceability-version-lock.json   # 审查被移除的锁条目
+git add artifacts/traceability-version-lock.json    # 暂存后重新提交
+
+# npm
+npx artifact-graph version-lock refresh --all --remove-orphans --format markdown
+git diff artifacts/traceability-version-lock.json
+git add artifacts/traceability-version-lock.json
+```
+
+`version-lock audit` 会把结构性孤立锁和陈旧哈希标记为阻断问题，并输出上述解决步骤；
+runner liveness 发现（测试文件不再处于任何已配置 runner 的激活范围）只是警告，不会阻断。
+
 ## Review Result Protocol
 
 包内发布了 `schemas/review-result.schema.json`，以及配套的 TypeScript 类型和 `validateReviewResult`

package/dist/cli.js

@@ -1521,6 +1521,7 @@ async function auditVersionLock(root, lockPath = VERSION_LOCK_PATH, graph, confi
         status: "orphan_lock",
         edgeId: entry.edgeId,
         message: `Liveness: ${sourcePath} is not active in any configured runner \u2014 locked verifies edges may reference dead tests`,
+        severity: "warning",
         artifact: entry.artifact,
         source: entry.source
       });
@@ -1650,7 +1651,84 @@ async function auditVersionLock(root, lockPath = VERSION_LOCK_PATH, graph, confi
     fresh,
     totalArtifactRelationLocks: artifactRelationLocks.length,
     artifactRelationFresh,
-    issues: sortBy(issues, (issue2) => `${issue2.status}	${issue2.edgeId}	${issue2.verifiedByPath ?? ""}`)
+    issues: sortBy(issues.map(enrichVersionLockIssue), (issue2) => `${issue2.status}	${issue2.edgeId}	${issue2.verifiedByPath ?? ""}`)
+  };
+}
+function isLivenessIssue(issue2) {
+  return issue2.status === "orphan_lock" && issue2.message.startsWith(LIVENESS_MESSAGE_PREFIX);
+}
+function versionLockIssueSeverity(issue2) {
+  if (issue2.severity) {
+    return issue2.severity;
+  }
+  if (issue2.status === "missing_lock") {
+    return "warning";
+  }
+  if (issue2.status === "orphan_lock" && issue2.message.startsWith(LIVENESS_MESSAGE_PREFIX)) {
+    return "warning";
+  }
+  return "error";
+}
+function isVersionLockIssueBlocking(issue2, strictMissingLock) {
+  if (issue2.status === "missing_lock") {
+    return strictMissingLock;
+  }
+  return versionLockIssueSeverity(issue2) === "error";
+}
+function versionLockIssueRemediation(issue2) {
+  switch (issue2.status) {
+    case "artifact_changed":
+      return [
+        "\u786E\u8BA4\u8FD9\u6B21\u5236\u54C1\u53D8\u66F4\uFF08\u5185\u5BB9\u6216\u8DEF\u5F84\uFF09\u662F\u6709\u610F\u7684\u3002",
+        "\u8FD0\u884C `artifact-graph version-lock refresh --changed-only --worktree --format markdown`\uFF08\u65E5\u5E38\u5F00\u53D1\uFF09\u6216 `artifact-graph version-lock refresh --changed-only --staged --format markdown`\uFF08\u63D0\u4EA4\u524D\uFF09\u5237\u65B0\u53D7\u5F71\u54CD\u7684\u9501\u3002",
+        "\u8FD0\u884C `git diff artifacts/traceability-version-lock.json` \u5BA1\u67E5\u9501\u53D8\u66F4\uFF0C\u786E\u8BA4\u540E `git add artifacts/traceability-version-lock.json` \u5E76\u91CD\u65B0\u63D0\u4EA4\u3002"
+      ];
+    case "source_changed":
+      return [
+        "\u786E\u8BA4\u8FD9\u6B21\u6E90\u7801/\u6D4B\u8BD5\u53D8\u66F4\uFF08\u5185\u5BB9\u6216\u8DEF\u5F84\uFF09\u662F\u6709\u610F\u7684\u3002",
+        "\u8FD0\u884C `artifact-graph version-lock refresh --changed-only --worktree --format markdown`\uFF08\u65E5\u5E38\u5F00\u53D1\uFF09\u6216 `artifact-graph version-lock refresh --changed-only --staged --format markdown`\uFF08\u63D0\u4EA4\u524D\uFF09\u5237\u65B0\u53D7\u5F71\u54CD\u7684\u9501\u3002",
+        "\u8FD0\u884C `git diff artifacts/traceability-version-lock.json` \u5BA1\u67E5\u9501\u53D8\u66F4\uFF0C\u786E\u8BA4\u540E `git add artifacts/traceability-version-lock.json` \u5E76\u91CD\u65B0\u63D0\u4EA4\u3002"
+      ];
+    case "verified_by_changed":
+      return [
+        "\u786E\u8BA4\u8FD9\u6B21\u9A8C\u8BC1\u6587\u4EF6\u53D8\u66F4\u662F\u6709\u610F\u7684\u3002",
+        "\u8FD0\u884C `artifact-graph version-lock refresh --changed-only --worktree --format markdown`\uFF08\u65E5\u5E38\u5F00\u53D1\uFF09\u6216 `artifact-graph version-lock refresh --changed-only --staged --format markdown`\uFF08\u63D0\u4EA4\u524D\uFF09\u5237\u65B0\u53D7\u5F71\u54CD\u7684\u9501\u3002",
+        "\u8FD0\u884C `git diff artifacts/traceability-version-lock.json` \u5BA1\u67E5\u9501\u53D8\u66F4\uFF0C\u786E\u8BA4\u540E `git add artifacts/traceability-version-lock.json` \u5E76\u91CD\u65B0\u63D0\u4EA4\u3002"
+      ];
+    case "missing_lock":
+      return [
+        "\u65B0\u589E\u8FFD\u6EAF\u8FB9\u8FD8\u6CA1\u6709\u5BF9\u5E94\u7248\u672C\u9501\uFF1B\u9ED8\u8BA4\u4E0D\u963B\u65AD\uFF0C`--strict-missing-lock` \u4E0B\u4F1A\u963B\u65AD\u3002",
+        "\u8FD0\u884C `artifact-graph version-lock refresh --changed-only --worktree --format markdown` \u4E3A\u53D7\u5F71\u54CD\u8FB9\u8865\u9501\uFF1B\u9996\u6B21\u5EFA\u7ACB\u57FA\u7EBF\u6216\u914D\u7F6E\u53D8\u66F4\u65F6\u7528 `artifact-graph version-lock refresh --all --format markdown`\u3002",
+        "\u8FD0\u884C `git diff artifacts/traceability-version-lock.json` \u5BA1\u67E5\u540E `git add artifacts/traceability-version-lock.json` \u6682\u5B58\u3002"
+      ];
+    case "orphan_lock":
+      if (isLivenessIssue(issue2)) {
+        return [
+          "\u8FD9\u662F liveness \u8B66\u544A\uFF0C\u4E0D\u662F\u6821\u9A8C\u5931\u8D25\uFF1A\u9501\u4ECD\u7136\u4FDD\u7559\uFF0C\u9ED8\u8BA4\u4E0D\u963B\u65AD\u3002",
+          "\u5982\u679C\u6D4B\u8BD5\u5DF2\u5E9F\u5F03\uFF1A\u5220\u9664\u8BE5\u6587\u4EF6\u6216\u79FB\u9664\u5176\u4E2D\u7684\u8FFD\u6EAF\u6CE8\u91CA\uFF0C\u7136\u540E\u8FD0\u884C `artifact-graph version-lock refresh --all --remove-orphans --format markdown` \u6E05\u7406\u5BF9\u5E94\u7684\u9501\u3002",
+          "\u5982\u679C\u6D4B\u8BD5\u4ECD\u7136\u6709\u6548\uFF1A\u628A\u5B83\u52A0\u5165 artifact-graph.config.yaml \u4E2D\u67D0\u4E2A e2e runner \u7684 include\uFF0C\u6216\u68C0\u67E5 exclude/testIgnore \u662F\u5426\u8BEF\u4F24\u3002"
+        ];
+      }
+      return [
+        "\u9501\u5F15\u7528\u7684\u5236\u54C1\u3001\u6E90\u7801\u6216\u8FFD\u6EAF\u8FB9\u5728\u5F53\u524D\u56FE\u4E2D\u5DF2\u4E0D\u5B58\u5728\uFF0C\u5E38\u89C1\u4E8E\u5236\u54C1\u5220\u9664\u6216\u62C6\u5206\u4E4B\u540E\u3002",
+        "\u786E\u8BA4\u5220\u9664\u662F\u6709\u610F\u7684\u540E\uFF0C\u8FD0\u884C `artifact-graph version-lock refresh --all --remove-orphans --format markdown` \u6E05\u7406\u5B64\u7ACB\u9501\u3002",
+        "\u8FD0\u884C `git diff artifacts/traceability-version-lock.json` \u5BA1\u67E5\u88AB\u79FB\u9664\u7684\u9501\u6761\u76EE\uFF0C\u786E\u8BA4\u540E `git add artifacts/traceability-version-lock.json` \u6682\u5B58\u3002",
+        "\u5982\u679C\u5220\u9664\u662F\u8BEF\u64CD\u4F5C\uFF0C\u5148\u6062\u590D\u5BF9\u5E94\u5236\u54C1\u6216\u6E90\u7801\u6587\u4EF6\uFF0C\u518D\u8FD0\u884C\u4E0D\u5E26 `--remove-orphans` \u7684 refresh \u5237\u65B0\u54C8\u5E0C\u3002"
+      ];
+    case "target_not_found":
+      return [
+        "\u68C0\u67E5 `--target` \u7684 `type:id` \u662F\u5426\u62FC\u5199\u6B63\u786E\u3002",
+        "\u5982\u679C\u8BE5\u5236\u54C1\u5DF2\u88AB\u5220\u9664\u6216\u6539\u540D\uFF0C\u6539\u7528\u5F53\u524D\u5B58\u5728\u7684\u5236\u54C1\u6807\u8BC6\u91CD\u8BD5\u3002"
+      ];
+    default:
+      return [];
+  }
+}
+function enrichVersionLockIssue(issue2) {
+  return {
+    ...issue2,
+    severity: versionLockIssueSeverity(issue2),
+    remediation: issue2.remediation ?? versionLockIssueRemediation(issue2)
   };
 }
 async function updateVersionLock(root, options) {
@@ -1948,59 +2026,118 @@ async function traceVersion(root, target, lockPath = VERSION_LOCK_PATH) {
     currentEdges: index.edges.filter((edge2) => edge2.from === targetUid || edge2.to === targetUid),
     locks: lock.locks.filter((entry) => `${entry.artifact.type}:${entry.artifact.id}` === targetUid),
     artifactRelations: targetArtifactRelations,
-    issues: [...targetIssues, ...audit.issues.filter((issue2) => `${issue2.artifact?.type}:${issue2.artifact?.id}` === targetUid || issue2.edgeId.includes(`#${targetUid}`))]
+    issues: [...targetIssues.map(enrichVersionLockIssue), ...audit.issues.filter((issue2) => `${issue2.artifact?.type}:${issue2.artifact?.id}` === targetUid || issue2.edgeId.includes(`#${targetUid}`))]
   };
 }
-function renderVersionLockAuditMarkdown(result) {
+function renderIssueBlockingTag(issue2, strictMissingLock) {
+  return isVersionLockIssueBlocking(issue2, strictMissingLock) ? "\u963B\u65AD" : "\u8B66\u544A";
+}
+function renderIssueBlockingExplanation(issue2, strictMissingLock) {
+  if (!isVersionLockIssueBlocking(issue2, strictMissingLock)) {
+    return "\u5426\uFF08\u4EC5\u63D0\u9192\uFF0C\u4E0D\u963B\u65AD\uFF09";
+  }
+  if (issue2.status === "missing_lock" && versionLockIssueSeverity(issue2) !== "error") {
+    return "\u662F\uFF08\u5DF2\u7531 --strict-missing-lock \u5347\u7EA7\u4E3A\u963B\u65AD\uFF09";
+  }
+  return "\u662F\uFF08\u4F1A\u4F7F\u547D\u4EE4\u4EE5\u975E\u96F6\u9000\u51FA\u7801\u7ED3\u675F\uFF09";
+}
+function appendIssueDetails(lines, issues, strictMissingLock) {
+  issues.forEach((issue2, index) => {
+    const label = VERSION_LOCK_STATUS_LABELS[issue2.status] ?? issue2.status;
+    lines.push(`### ${index + 1}. [${renderIssueBlockingTag(issue2, strictMissingLock)}] ${label}\uFF08\`${issue2.status}\`\uFF09`);
+    lines.push("");
+    lines.push(`- \u8FB9: \`${issue2.edgeId}\``);
+    lines.push(`- \u8BE6\u60C5: ${issue2.message}`);
+    lines.push(`- \u662F\u5426\u963B\u65AD: ${renderIssueBlockingExplanation(issue2, strictMissingLock)}`);
+    const remediation = issue2.remediation ?? [];
+    if (remediation.length > 0) {
+      lines.push("- \u89E3\u51B3\u6B65\u9AA4:");
+      remediation.forEach((step, stepIndex) => {
+        lines.push(`  ${stepIndex + 1}. ${step}`);
+      });
+    }
+    lines.push("");
+  });
+}
+function renderVersionLockAuditMarkdown(result, options = {}) {
+  const strictMissingLock = options.strictMissingLock === true;
+  const blockingCount = result.issues.filter((issue2) => isVersionLockIssueBlocking(issue2, strictMissingLock)).length;
+  const nonBlockingCount = result.issues.length - blockingCount;
   const lines = [
-    "# Version Lock Audit",
+    "# \u7248\u672C\u9501\u5BA1\u8BA1\uFF08version-lock audit\uFF09",
     "",
-    `Root: \`${result.root}\``,
-    `Lock: \`${result.lockPath}\``,
-    `Locks: ${result.totalLocks} | Fresh: ${result.fresh} | Issues: ${result.issues.length}`,
-    `Artifact Relations: ${result.totalArtifactRelationLocks} | Fresh: ${result.artifactRelationFresh}`,
+    `- \u6839\u76EE\u5F55: \`${result.root}\``,
+    `- \u9501\u6587\u4EF6: \`${result.lockPath}\``,
+    `- \u5B9E\u73B0/\u9A8C\u8BC1\u9501: ${result.totalLocks}\uFF08\u65B0\u9C9C ${result.fresh}\uFF09`,
+    `- \u5236\u54C1\u5173\u7CFB\u9501: ${result.totalArtifactRelationLocks}\uFF08\u65B0\u9C9C ${result.artifactRelationFresh}\uFF09`,
+    `- \u963B\u65AD\u7B56\u7565: ${strictMissingLock ? "--strict-missing-lock\uFF08missing_lock \u5347\u7EA7\u4E3A\u963B\u65AD\uFF09" : "\u9ED8\u8BA4\uFF08missing_lock \u4E0D\u963B\u65AD\uFF09"}`,
+    `- \u95EE\u9898: ${result.issues.length}\uFF08\u963B\u65AD ${blockingCount}\uFF0C\u4E0D\u963B\u65AD ${nonBlockingCount}\uFF09`,
     ""
   ];
   if (result.issues.length === 0) {
-    lines.push("No version lock issues.");
+    lines.push("\u672A\u53D1\u73B0\u7248\u672C\u9501\u95EE\u9898\u3002");
     return `${lines.join("\n")}
 `;
   }
-  for (const issue2 of result.issues) {
-    lines.push(`- [${issue2.status}] \`${issue2.edgeId}\` \u2014 ${issue2.message}`);
+  if (blockingCount > 0) {
+    lines.push(`\u5F53\u524D\u7B56\u7565\u4E0B\u5B58\u5728 ${blockingCount} \u4E2A\u963B\u65AD\u95EE\u9898\uFF0C\u547D\u4EE4\u5C06\u4EE5\u975E\u96F6\u9000\u51FA\u7801\u7ED3\u675F\uFF1B\u8BF7\u6309\u4E0B\u65B9\u6B65\u9AA4\u9010\u9879\u5904\u7406\u3002`);
+  } else {
+    lines.push("\u5F53\u524D\u7B56\u7565\u4E0B\u6CA1\u6709\u963B\u65AD\u95EE\u9898\uFF0C\u4EE5\u4E0B\u4EC5\u4E3A\u63D0\u9192\uFF0C\u547D\u4EE4\u4EE5\u96F6\u9000\u51FA\u7801\u7ED3\u675F\u3002");
   }
+  lines.push("");
+  lines.push("## \u95EE\u9898\u6E05\u5355");
+  lines.push("");
+  appendIssueDetails(lines, result.issues, strictMissingLock);
   return `${lines.join("\n")}
 `;
 }
 function renderVersionLockRefreshMarkdown(result) {
+  const strictMissingLock = true;
+  const blockingCount = result.postAudit.issues.filter((issue2) => isVersionLockIssueBlocking(issue2, strictMissingLock)).length;
+  const nonBlockingCount = result.postAudit.issues.length - blockingCount;
   const lines = [
-    "# Version Lock Refresh",
+    "# \u7248\u672C\u9501\u5237\u65B0\uFF08version-lock refresh\uFF09",
+    "",
+    `- \u6839\u76EE\u5F55: \`${result.root}\``,
+    `- \u9501\u6587\u4EF6: \`${result.lockPath}\``,
+    `- \u6A21\u5F0F: \`${result.mode}\`\uFF08\u53D8\u66F4\u8DEF\u5F84 ${result.changedPaths.length} \u4E2A\uFF0C\u53D7\u5F71\u54CD\u8FB9 ${result.affectedEdges.length} \u6761\uFF09`,
+    `- \u5B9E\u73B0/\u9A8C\u8BC1\u9501: \u65B0\u589E ${result.addedLocks.length} | \u66F4\u65B0 ${result.updatedLocks.length} | \u4FDD\u7559\u5B64\u7ACB ${result.retainedOrphans.length} | \u5220\u9664\u5B64\u7ACB ${result.removedOrphans.length}`,
+    `- \u5236\u54C1\u5173\u7CFB\u9501: \u65B0\u589E ${result.addedArtifactRelationLocks.length} | \u66F4\u65B0 ${result.updatedArtifactRelationLocks.length} | \u4FDD\u7559\u5B64\u7ACB ${result.retainedArtifactRelationOrphans.length} | \u5220\u9664 ${result.removedArtifactRelationLocks.length}`,
+    `- \u963B\u65AD\u7B56\u7565: refresh \u56FA\u5B9A\u6309 --strict-missing-lock \u5224\u5B9A\uFF0Cmissing_lock \u4E5F\u4F1A\u963B\u65AD`,
+    `- \u5237\u65B0\u540E\u5BA1\u8BA1\u95EE\u9898: ${result.postAudit.issues.length}\uFF08\u963B\u65AD ${blockingCount}\uFF0C\u4E0D\u963B\u65AD ${nonBlockingCount}\uFF09`,
+    "",
+    "\u9501\u6587\u4EF6\u5DF2\u5199\u5165\u3002\u82E5\u9501\u6587\u4EF6\u76F8\u5BF9\u6682\u5B58\u533A\u6709\u53D8\u5316\uFF08\u4F8B\u5982 pre-commit \u573A\u666F\uFF09\uFF0C\u8BF7\u5148\u5BA1\u67E5\u5E76\u6682\u5B58\uFF1A",
     "",
-    `Root: \`${result.root}\``,
-    `Lock: \`${result.lockPath}\``,
-    `Mode: \`${result.mode}\``,
-    `Changed paths: ${result.changedPaths.length}`,
-    `Affected edges: ${result.affectedEdges.length}`,
-    `Added: ${result.addedLocks.length} | Updated: ${result.updatedLocks.length} | Retained orphans: ${result.retainedOrphans.length} | Removed orphans: ${result.removedOrphans.length}`,
-    `Artifact Relations \u2014 Added: ${result.addedArtifactRelationLocks.length} | Updated: ${result.updatedArtifactRelationLocks.length} | Retained orphans: ${result.retainedArtifactRelationOrphans.length} | Removed: ${result.removedArtifactRelationLocks.length}`,
-    `Post-audit issues: ${result.postAudit.issues.length}`,
+    "1. `git diff artifacts/traceability-version-lock.json`",
+    "2. `git add artifacts/traceability-version-lock.json`",
+    "3. \u91CD\u65B0\u6267\u884C `git commit`",
     ""
   ];
-  appendList(lines, "Added Locks", result.addedLocks);
-  appendList(lines, "Updated Locks", result.updatedLocks);
-  appendList(lines, "Retained Orphans", result.retainedOrphans);
-  appendList(lines, "Removed Orphans", result.removedOrphans);
-  appendList(lines, "Added Artifact Relation Locks", result.addedArtifactRelationLocks);
-  appendList(lines, "Updated Artifact Relation Locks", result.updatedArtifactRelationLocks);
-  appendList(lines, "Retained Artifact Relation Orphans", result.retainedArtifactRelationOrphans);
-  appendList(lines, "Removed Artifact Relation Locks", result.removedArtifactRelationLocks);
-  appendList(lines, "Warnings", result.warnings);
+  appendList(lines, "\u65B0\u589E\u7684\u9501", result.addedLocks);
+  appendList(lines, "\u66F4\u65B0\u7684\u9501", result.updatedLocks);
+  appendList(lines, "\u4FDD\u7559\u7684\u5B64\u7ACB\u9501", result.retainedOrphans);
+  if (result.retainedOrphans.length > 0) {
+    lines.push("> \u4EE5\u4E0A\u662F\u5DF2\u5220\u9664/\u62C6\u5206\u5236\u54C1\u6216\u5931\u6548\u8FFD\u6EAF\u8FB9\u9057\u7559\u7684\u9501\u3002\u786E\u8BA4\u4E0D\u518D\u9700\u8981\u540E\u8FD0\u884C `artifact-graph version-lock refresh --all --remove-orphans --format markdown` \u6E05\u7406\uFF0C\u5BA1\u67E5 `git diff artifacts/traceability-version-lock.json` \u540E\u518D\u6682\u5B58\u3002");
+    lines.push("");
+  }
+  appendList(lines, "\u5220\u9664\u7684\u5B64\u7ACB\u9501", result.removedOrphans);
+  appendList(lines, "\u65B0\u589E\u7684\u5236\u54C1\u5173\u7CFB\u9501", result.addedArtifactRelationLocks);
+  appendList(lines, "\u66F4\u65B0\u7684\u5236\u54C1\u5173\u7CFB\u9501", result.updatedArtifactRelationLocks);
+  appendList(lines, "\u4FDD\u7559\u7684\u5B64\u7ACB\u5236\u54C1\u5173\u7CFB\u9501", result.retainedArtifactRelationOrphans);
+  if (result.retainedArtifactRelationOrphans.length > 0) {
+    lines.push("> \u4EE5\u4E0A\u662F\u5931\u6548\u5236\u54C1\u5173\u7CFB\u9057\u7559\u7684\u9501\u3002\u786E\u8BA4\u540E\u8FD0\u884C `artifact-graph version-lock refresh --all --remove-orphans --format markdown` \u6E05\u7406\uFF0C\u5BA1\u67E5\u9501 diff \u540E\u518D\u6682\u5B58\u3002");
+    lines.push("");
+  }
+  appendList(lines, "\u5220\u9664\u7684\u5236\u54C1\u5173\u7CFB\u9501", result.removedArtifactRelationLocks);
+  appendList(lines, "\u63D0\u9192", result.warnings);
   if (result.postAudit.issues.length > 0) {
-    lines.push("## Post-Audit Issues");
-    for (const issue2 of result.postAudit.issues) {
-      lines.push(`- [${issue2.status}] \`${issue2.edgeId}\` \u2014 ${issue2.message}`);
+    if (blockingCount > 0) {
+      lines.push(`## \u5237\u65B0\u540E\u5BA1\u8BA1\u95EE\u9898\uFF08\u963B\u65AD ${blockingCount}\uFF0C\u4E0D\u963B\u65AD ${nonBlockingCount}\uFF09`);
+    } else {
+      lines.push(`## \u5237\u65B0\u540E\u5BA1\u8BA1\u95EE\u9898\uFF08\u5F53\u524D\u7B56\u7565\u4E0B\u5168\u90E8\u4E0D\u963B\u65AD\uFF09`);
     }
     lines.push("");
+    appendIssueDetails(lines, result.postAudit.issues, strictMissingLock);
   }
   return `${lines.join("\n")}
 `;
@@ -2455,7 +2592,7 @@ async function isFileActiveInRunner(root, filePath, runner) {
 function sortUnique(items) {
   return [...new Set(items)].sort((left, right) => left.localeCompare(right));
 }
-var VERSION_LOCK_PATH, VERSION_INDEX_SCHEMA_VERSION, VERSION_LOCK_SCHEMA_VERSION;
+var VERSION_LOCK_PATH, VERSION_INDEX_SCHEMA_VERSION, VERSION_LOCK_SCHEMA_VERSION, LIVENESS_MESSAGE_PREFIX, VERSION_LOCK_STATUS_LABELS;
 var init_versioned_traceability = __esm({
   "src/versioned-traceability.ts"() {
     "use strict";
@@ -2464,6 +2601,16 @@ var init_versioned_traceability = __esm({
     VERSION_LOCK_PATH = "artifacts/traceability-version-lock.json";
     VERSION_INDEX_SCHEMA_VERSION = "1.0";
     VERSION_LOCK_SCHEMA_VERSION = "1.0";
+    LIVENESS_MESSAGE_PREFIX = "Liveness:";
+    VERSION_LOCK_STATUS_LABELS = {
+      fresh: "\u65B0\u9C9C",
+      target_not_found: "\u76EE\u6807\u5236\u54C1\u4E0D\u5B58\u5728",
+      artifact_changed: "\u5236\u54C1\u5DF2\u53D8\u5316",
+      source_changed: "\u6E90\u7801/\u6D4B\u8BD5\u5DF2\u53D8\u5316",
+      verified_by_changed: "\u9A8C\u8BC1\u6587\u4EF6\u5DF2\u53D8\u5316",
+      missing_lock: "\u7F3A\u5C11\u7248\u672C\u9501",
+      orphan_lock: "\u5B64\u7ACB\u9501"
+    };
   }
 });
 
@@ -9408,7 +9555,7 @@ async function runCli(argv, io = {}) {
             out(`${JSON.stringify(result, null, 2)}
 `);
           } else {
-            out(renderVersionLockAuditMarkdown(result));
+            out(renderVersionLockAuditMarkdown(result, { strictMissingLock: parsed.flags["strict-missing-lock"] === true }));
           }
           return hasBlockingVersionIssues(result.issues, parsed.flags["strict-missing-lock"] === true) && !parsed.flags["warning-only"] ? 1 : 0;
         }
@@ -9925,7 +10072,11 @@ async function runCli(argv, io = {}) {
   }
 }
 function hasBlockingVersionIssues(issues, strictMissingLock) {
-  return issues.some((issue2) => issue2.status !== "missing_lock" || strictMissingLock);
+  return issues.some((issue2) => isVersionLockIssueBlocking({
+    status: issue2.status,
+    message: issue2.message ?? "",
+    severity: issue2.severity
+  }, strictMissingLock));
 }
 function isGraphRelevantPath(path) {
   return path === "artifact-graph.config.yaml" || path === VERSION_LOCK_PATH || path.startsWith("artifacts/") || /\.(md|mdx|json|ya?ml|ts|tsx|js|jsx|mts|cts|rs|py|go)$/.test(path);
@@ -9988,6 +10139,12 @@ Commands:
   version-lock update --target <type:id> --source <path> [--verified-by <path,path>] [--lock-path <path>]
   version-lock bootstrap [--force] [--lock-path <path>]
   version-lock refresh (--all | --changed-only (--staged | --worktree | --base <ref>)) [--remove-orphans] [--format json|markdown] [--lock-path <path>]
+      --remove-orphans  delete locks whose artifact, source, or traceability edge no longer
+                        exists (default: retain them). Typical cleanup after deleting or
+                        splitting artifacts:
+                          artifact-graph version-lock refresh --all --remove-orphans --format markdown
+                          git diff artifacts/traceability-version-lock.json   # review
+                          git add artifacts/traceability-version-lock.json    # stage, then commit
   trace-version --target <type:id> [--format json|markdown] [--warning-only] [--strict-missing-lock] [--lock-path <path>]
   hooks install-git [--hook pre-commit|pre-push|all] [--uninstall]
   next-id <type> --range <name>

package/dist/index.cjs

@@ -1563,6 +1563,7 @@ async function auditVersionLock(root, lockPath = VERSION_LOCK_PATH, graph, confi
         status: "orphan_lock",
         edgeId: entry.edgeId,
         message: `Liveness: ${sourcePath} is not active in any configured runner \u2014 locked verifies edges may reference dead tests`,
+        severity: "warning",
         artifact: entry.artifact,
         source: entry.source
       });
@@ -1692,7 +1693,84 @@ async function auditVersionLock(root, lockPath = VERSION_LOCK_PATH, graph, confi
     fresh,
     totalArtifactRelationLocks: artifactRelationLocks.length,
     artifactRelationFresh,
-    issues: sortBy(issues, (issue2) => `${issue2.status}	${issue2.edgeId}	${issue2.verifiedByPath ?? ""}`)
+    issues: sortBy(issues.map(enrichVersionLockIssue), (issue2) => `${issue2.status}	${issue2.edgeId}	${issue2.verifiedByPath ?? ""}`)
+  };
+}
+function isLivenessIssue(issue2) {
+  return issue2.status === "orphan_lock" && issue2.message.startsWith(LIVENESS_MESSAGE_PREFIX);
+}
+function versionLockIssueSeverity(issue2) {
+  if (issue2.severity) {
+    return issue2.severity;
+  }
+  if (issue2.status === "missing_lock") {
+    return "warning";
+  }
+  if (issue2.status === "orphan_lock" && issue2.message.startsWith(LIVENESS_MESSAGE_PREFIX)) {
+    return "warning";
+  }
+  return "error";
+}
+function isVersionLockIssueBlocking(issue2, strictMissingLock) {
+  if (issue2.status === "missing_lock") {
+    return strictMissingLock;
+  }
+  return versionLockIssueSeverity(issue2) === "error";
+}
+function versionLockIssueRemediation(issue2) {
+  switch (issue2.status) {
+    case "artifact_changed":
+      return [
+        "\u786E\u8BA4\u8FD9\u6B21\u5236\u54C1\u53D8\u66F4\uFF08\u5185\u5BB9\u6216\u8DEF\u5F84\uFF09\u662F\u6709\u610F\u7684\u3002",
+        "\u8FD0\u884C `artifact-graph version-lock refresh --changed-only --worktree --format markdown`\uFF08\u65E5\u5E38\u5F00\u53D1\uFF09\u6216 `artifact-graph version-lock refresh --changed-only --staged --format markdown`\uFF08\u63D0\u4EA4\u524D\uFF09\u5237\u65B0\u53D7\u5F71\u54CD\u7684\u9501\u3002",
+        "\u8FD0\u884C `git diff artifacts/traceability-version-lock.json` \u5BA1\u67E5\u9501\u53D8\u66F4\uFF0C\u786E\u8BA4\u540E `git add artifacts/traceability-version-lock.json` \u5E76\u91CD\u65B0\u63D0\u4EA4\u3002"
+      ];
+    case "source_changed":
+      return [
+        "\u786E\u8BA4\u8FD9\u6B21\u6E90\u7801/\u6D4B\u8BD5\u53D8\u66F4\uFF08\u5185\u5BB9\u6216\u8DEF\u5F84\uFF09\u662F\u6709\u610F\u7684\u3002",
+        "\u8FD0\u884C `artifact-graph version-lock refresh --changed-only --worktree --format markdown`\uFF08\u65E5\u5E38\u5F00\u53D1\uFF09\u6216 `artifact-graph version-lock refresh --changed-only --staged --format markdown`\uFF08\u63D0\u4EA4\u524D\uFF09\u5237\u65B0\u53D7\u5F71\u54CD\u7684\u9501\u3002",
+        "\u8FD0\u884C `git diff artifacts/traceability-version-lock.json` \u5BA1\u67E5\u9501\u53D8\u66F4\uFF0C\u786E\u8BA4\u540E `git add artifacts/traceability-version-lock.json` \u5E76\u91CD\u65B0\u63D0\u4EA4\u3002"
+      ];
+    case "verified_by_changed":
+      return [
+        "\u786E\u8BA4\u8FD9\u6B21\u9A8C\u8BC1\u6587\u4EF6\u53D8\u66F4\u662F\u6709\u610F\u7684\u3002",
+        "\u8FD0\u884C `artifact-graph version-lock refresh --changed-only --worktree --format markdown`\uFF08\u65E5\u5E38\u5F00\u53D1\uFF09\u6216 `artifact-graph version-lock refresh --changed-only --staged --format markdown`\uFF08\u63D0\u4EA4\u524D\uFF09\u5237\u65B0\u53D7\u5F71\u54CD\u7684\u9501\u3002",
+        "\u8FD0\u884C `git diff artifacts/traceability-version-lock.json` \u5BA1\u67E5\u9501\u53D8\u66F4\uFF0C\u786E\u8BA4\u540E `git add artifacts/traceability-version-lock.json` \u5E76\u91CD\u65B0\u63D0\u4EA4\u3002"
+      ];
+    case "missing_lock":
+      return [
+        "\u65B0\u589E\u8FFD\u6EAF\u8FB9\u8FD8\u6CA1\u6709\u5BF9\u5E94\u7248\u672C\u9501\uFF1B\u9ED8\u8BA4\u4E0D\u963B\u65AD\uFF0C`--strict-missing-lock` \u4E0B\u4F1A\u963B\u65AD\u3002",
+        "\u8FD0\u884C `artifact-graph version-lock refresh --changed-only --worktree --format markdown` \u4E3A\u53D7\u5F71\u54CD\u8FB9\u8865\u9501\uFF1B\u9996\u6B21\u5EFA\u7ACB\u57FA\u7EBF\u6216\u914D\u7F6E\u53D8\u66F4\u65F6\u7528 `artifact-graph version-lock refresh --all --format markdown`\u3002",
+        "\u8FD0\u884C `git diff artifacts/traceability-version-lock.json` \u5BA1\u67E5\u540E `git add artifacts/traceability-version-lock.json` \u6682\u5B58\u3002"
+      ];
+    case "orphan_lock":
+      if (isLivenessIssue(issue2)) {
+        return [
+          "\u8FD9\u662F liveness \u8B66\u544A\uFF0C\u4E0D\u662F\u6821\u9A8C\u5931\u8D25\uFF1A\u9501\u4ECD\u7136\u4FDD\u7559\uFF0C\u9ED8\u8BA4\u4E0D\u963B\u65AD\u3002",
+          "\u5982\u679C\u6D4B\u8BD5\u5DF2\u5E9F\u5F03\uFF1A\u5220\u9664\u8BE5\u6587\u4EF6\u6216\u79FB\u9664\u5176\u4E2D\u7684\u8FFD\u6EAF\u6CE8\u91CA\uFF0C\u7136\u540E\u8FD0\u884C `artifact-graph version-lock refresh --all --remove-orphans --format markdown` \u6E05\u7406\u5BF9\u5E94\u7684\u9501\u3002",
+          "\u5982\u679C\u6D4B\u8BD5\u4ECD\u7136\u6709\u6548\uFF1A\u628A\u5B83\u52A0\u5165 artifact-graph.config.yaml \u4E2D\u67D0\u4E2A e2e runner \u7684 include\uFF0C\u6216\u68C0\u67E5 exclude/testIgnore \u662F\u5426\u8BEF\u4F24\u3002"
+        ];
+      }
+      return [
+        "\u9501\u5F15\u7528\u7684\u5236\u54C1\u3001\u6E90\u7801\u6216\u8FFD\u6EAF\u8FB9\u5728\u5F53\u524D\u56FE\u4E2D\u5DF2\u4E0D\u5B58\u5728\uFF0C\u5E38\u89C1\u4E8E\u5236\u54C1\u5220\u9664\u6216\u62C6\u5206\u4E4B\u540E\u3002",
+        "\u786E\u8BA4\u5220\u9664\u662F\u6709\u610F\u7684\u540E\uFF0C\u8FD0\u884C `artifact-graph version-lock refresh --all --remove-orphans --format markdown` \u6E05\u7406\u5B64\u7ACB\u9501\u3002",
+        "\u8FD0\u884C `git diff artifacts/traceability-version-lock.json` \u5BA1\u67E5\u88AB\u79FB\u9664\u7684\u9501\u6761\u76EE\uFF0C\u786E\u8BA4\u540E `git add artifacts/traceability-version-lock.json` \u6682\u5B58\u3002",
+        "\u5982\u679C\u5220\u9664\u662F\u8BEF\u64CD\u4F5C\uFF0C\u5148\u6062\u590D\u5BF9\u5E94\u5236\u54C1\u6216\u6E90\u7801\u6587\u4EF6\uFF0C\u518D\u8FD0\u884C\u4E0D\u5E26 `--remove-orphans` \u7684 refresh \u5237\u65B0\u54C8\u5E0C\u3002"
+      ];
+    case "target_not_found":
+      return [
+        "\u68C0\u67E5 `--target` \u7684 `type:id` \u662F\u5426\u62FC\u5199\u6B63\u786E\u3002",
+        "\u5982\u679C\u8BE5\u5236\u54C1\u5DF2\u88AB\u5220\u9664\u6216\u6539\u540D\uFF0C\u6539\u7528\u5F53\u524D\u5B58\u5728\u7684\u5236\u54C1\u6807\u8BC6\u91CD\u8BD5\u3002"
+      ];
+    default:
+      return [];
+  }
+}
+function enrichVersionLockIssue(issue2) {
+  return {
+    ...issue2,
+    severity: versionLockIssueSeverity(issue2),
+    remediation: issue2.remediation ?? versionLockIssueRemediation(issue2)
   };
 }
 async function updateVersionLock(root, options) {
@@ -1990,59 +2068,118 @@ async function traceVersion(root, target, lockPath = VERSION_LOCK_PATH) {
     currentEdges: index.edges.filter((edge2) => edge2.from === targetUid || edge2.to === targetUid),
     locks: lock.locks.filter((entry) => `${entry.artifact.type}:${entry.artifact.id}` === targetUid),
     artifactRelations: targetArtifactRelations,
-    issues: [...targetIssues, ...audit.issues.filter((issue2) => `${issue2.artifact?.type}:${issue2.artifact?.id}` === targetUid || issue2.edgeId.includes(`#${targetUid}`))]
+    issues: [...targetIssues.map(enrichVersionLockIssue), ...audit.issues.filter((issue2) => `${issue2.artifact?.type}:${issue2.artifact?.id}` === targetUid || issue2.edgeId.includes(`#${targetUid}`))]
   };
 }
-function renderVersionLockAuditMarkdown(result) {
+function renderIssueBlockingTag(issue2, strictMissingLock) {
+  return isVersionLockIssueBlocking(issue2, strictMissingLock) ? "\u963B\u65AD" : "\u8B66\u544A";
+}
+function renderIssueBlockingExplanation(issue2, strictMissingLock) {
+  if (!isVersionLockIssueBlocking(issue2, strictMissingLock)) {
+    return "\u5426\uFF08\u4EC5\u63D0\u9192\uFF0C\u4E0D\u963B\u65AD\uFF09";
+  }
+  if (issue2.status === "missing_lock" && versionLockIssueSeverity(issue2) !== "error") {
+    return "\u662F\uFF08\u5DF2\u7531 --strict-missing-lock \u5347\u7EA7\u4E3A\u963B\u65AD\uFF09";
+  }
+  return "\u662F\uFF08\u4F1A\u4F7F\u547D\u4EE4\u4EE5\u975E\u96F6\u9000\u51FA\u7801\u7ED3\u675F\uFF09";
+}
+function appendIssueDetails(lines, issues, strictMissingLock) {
+  issues.forEach((issue2, index) => {
+    const label = VERSION_LOCK_STATUS_LABELS[issue2.status] ?? issue2.status;
+    lines.push(`### ${index + 1}. [${renderIssueBlockingTag(issue2, strictMissingLock)}] ${label}\uFF08\`${issue2.status}\`\uFF09`);
+    lines.push("");
+    lines.push(`- \u8FB9: \`${issue2.edgeId}\``);
+    lines.push(`- \u8BE6\u60C5: ${issue2.message}`);
+    lines.push(`- \u662F\u5426\u963B\u65AD: ${renderIssueBlockingExplanation(issue2, strictMissingLock)}`);
+    const remediation = issue2.remediation ?? [];
+    if (remediation.length > 0) {
+      lines.push("- \u89E3\u51B3\u6B65\u9AA4:");
+      remediation.forEach((step, stepIndex) => {
+        lines.push(`  ${stepIndex + 1}. ${step}`);
+      });
+    }
+    lines.push("");
+  });
+}
+function renderVersionLockAuditMarkdown(result, options = {}) {
+  const strictMissingLock = options.strictMissingLock === true;
+  const blockingCount = result.issues.filter((issue2) => isVersionLockIssueBlocking(issue2, strictMissingLock)).length;
+  const nonBlockingCount = result.issues.length - blockingCount;
   const lines = [
-    "# Version Lock Audit",
+    "# \u7248\u672C\u9501\u5BA1\u8BA1\uFF08version-lock audit\uFF09",
     "",
-    `Root: \`${result.root}\``,
-    `Lock: \`${result.lockPath}\``,
-    `Locks: ${result.totalLocks} | Fresh: ${result.fresh} | Issues: ${result.issues.length}`,
-    `Artifact Relations: ${result.totalArtifactRelationLocks} | Fresh: ${result.artifactRelationFresh}`,
+    `- \u6839\u76EE\u5F55: \`${result.root}\``,
+    `- \u9501\u6587\u4EF6: \`${result.lockPath}\``,
+    `- \u5B9E\u73B0/\u9A8C\u8BC1\u9501: ${result.totalLocks}\uFF08\u65B0\u9C9C ${result.fresh}\uFF09`,
+    `- \u5236\u54C1\u5173\u7CFB\u9501: ${result.totalArtifactRelationLocks}\uFF08\u65B0\u9C9C ${result.artifactRelationFresh}\uFF09`,
+    `- \u963B\u65AD\u7B56\u7565: ${strictMissingLock ? "--strict-missing-lock\uFF08missing_lock \u5347\u7EA7\u4E3A\u963B\u65AD\uFF09" : "\u9ED8\u8BA4\uFF08missing_lock \u4E0D\u963B\u65AD\uFF09"}`,
+    `- \u95EE\u9898: ${result.issues.length}\uFF08\u963B\u65AD ${blockingCount}\uFF0C\u4E0D\u963B\u65AD ${nonBlockingCount}\uFF09`,
     ""
   ];
   if (result.issues.length === 0) {
-    lines.push("No version lock issues.");
+    lines.push("\u672A\u53D1\u73B0\u7248\u672C\u9501\u95EE\u9898\u3002");
     return `${lines.join("\n")}
 `;
   }
-  for (const issue2 of result.issues) {
-    lines.push(`- [${issue2.status}] \`${issue2.edgeId}\` \u2014 ${issue2.message}`);
+  if (blockingCount > 0) {
+    lines.push(`\u5F53\u524D\u7B56\u7565\u4E0B\u5B58\u5728 ${blockingCount} \u4E2A\u963B\u65AD\u95EE\u9898\uFF0C\u547D\u4EE4\u5C06\u4EE5\u975E\u96F6\u9000\u51FA\u7801\u7ED3\u675F\uFF1B\u8BF7\u6309\u4E0B\u65B9\u6B65\u9AA4\u9010\u9879\u5904\u7406\u3002`);
+  } else {
+    lines.push("\u5F53\u524D\u7B56\u7565\u4E0B\u6CA1\u6709\u963B\u65AD\u95EE\u9898\uFF0C\u4EE5\u4E0B\u4EC5\u4E3A\u63D0\u9192\uFF0C\u547D\u4EE4\u4EE5\u96F6\u9000\u51FA\u7801\u7ED3\u675F\u3002");
   }
+  lines.push("");
+  lines.push("## \u95EE\u9898\u6E05\u5355");
+  lines.push("");
+  appendIssueDetails(lines, result.issues, strictMissingLock);
   return `${lines.join("\n")}
 `;
 }
 function renderVersionLockRefreshMarkdown(result) {
+  const strictMissingLock = true;
+  const blockingCount = result.postAudit.issues.filter((issue2) => isVersionLockIssueBlocking(issue2, strictMissingLock)).length;
+  const nonBlockingCount = result.postAudit.issues.length - blockingCount;
   const lines = [
-    "# Version Lock Refresh",
+    "# \u7248\u672C\u9501\u5237\u65B0\uFF08version-lock refresh\uFF09",
+    "",
+    `- \u6839\u76EE\u5F55: \`${result.root}\``,
+    `- \u9501\u6587\u4EF6: \`${result.lockPath}\``,
+    `- \u6A21\u5F0F: \`${result.mode}\`\uFF08\u53D8\u66F4\u8DEF\u5F84 ${result.changedPaths.length} \u4E2A\uFF0C\u53D7\u5F71\u54CD\u8FB9 ${result.affectedEdges.length} \u6761\uFF09`,
+    `- \u5B9E\u73B0/\u9A8C\u8BC1\u9501: \u65B0\u589E ${result.addedLocks.length} | \u66F4\u65B0 ${result.updatedLocks.length} | \u4FDD\u7559\u5B64\u7ACB ${result.retainedOrphans.length} | \u5220\u9664\u5B64\u7ACB ${result.removedOrphans.length}`,
+    `- \u5236\u54C1\u5173\u7CFB\u9501: \u65B0\u589E ${result.addedArtifactRelationLocks.length} | \u66F4\u65B0 ${result.updatedArtifactRelationLocks.length} | \u4FDD\u7559\u5B64\u7ACB ${result.retainedArtifactRelationOrphans.length} | \u5220\u9664 ${result.removedArtifactRelationLocks.length}`,
+    `- \u963B\u65AD\u7B56\u7565: refresh \u56FA\u5B9A\u6309 --strict-missing-lock \u5224\u5B9A\uFF0Cmissing_lock \u4E5F\u4F1A\u963B\u65AD`,
+    `- \u5237\u65B0\u540E\u5BA1\u8BA1\u95EE\u9898: ${result.postAudit.issues.length}\uFF08\u963B\u65AD ${blockingCount}\uFF0C\u4E0D\u963B\u65AD ${nonBlockingCount}\uFF09`,
+    "",
+    "\u9501\u6587\u4EF6\u5DF2\u5199\u5165\u3002\u82E5\u9501\u6587\u4EF6\u76F8\u5BF9\u6682\u5B58\u533A\u6709\u53D8\u5316\uFF08\u4F8B\u5982 pre-commit \u573A\u666F\uFF09\uFF0C\u8BF7\u5148\u5BA1\u67E5\u5E76\u6682\u5B58\uFF1A",
     "",
-    `Root: \`${result.root}\``,
-    `Lock: \`${result.lockPath}\``,
-    `Mode: \`${result.mode}\``,
-    `Changed paths: ${result.changedPaths.length}`,
-    `Affected edges: ${result.affectedEdges.length}`,
-    `Added: ${result.addedLocks.length} | Updated: ${result.updatedLocks.length} | Retained orphans: ${result.retainedOrphans.length} | Removed orphans: ${result.removedOrphans.length}`,
-    `Artifact Relations \u2014 Added: ${result.addedArtifactRelationLocks.length} | Updated: ${result.updatedArtifactRelationLocks.length} | Retained orphans: ${result.retainedArtifactRelationOrphans.length} | Removed: ${result.removedArtifactRelationLocks.length}`,
-    `Post-audit issues: ${result.postAudit.issues.length}`,
+    "1. `git diff artifacts/traceability-version-lock.json`",
+    "2. `git add artifacts/traceability-version-lock.json`",
+    "3. \u91CD\u65B0\u6267\u884C `git commit`",
     ""
   ];
-  appendList(lines, "Added Locks", result.addedLocks);
-  appendList(lines, "Updated Locks", result.updatedLocks);
-  appendList(lines, "Retained Orphans", result.retainedOrphans);
-  appendList(lines, "Removed Orphans", result.removedOrphans);
-  appendList(lines, "Added Artifact Relation Locks", result.addedArtifactRelationLocks);
-  appendList(lines, "Updated Artifact Relation Locks", result.updatedArtifactRelationLocks);
-  appendList(lines, "Retained Artifact Relation Orphans", result.retainedArtifactRelationOrphans);
-  appendList(lines, "Removed Artifact Relation Locks", result.removedArtifactRelationLocks);
-  appendList(lines, "Warnings", result.warnings);
+  appendList(lines, "\u65B0\u589E\u7684\u9501", result.addedLocks);
+  appendList(lines, "\u66F4\u65B0\u7684\u9501", result.updatedLocks);
+  appendList(lines, "\u4FDD\u7559\u7684\u5B64\u7ACB\u9501", result.retainedOrphans);
+  if (result.retainedOrphans.length > 0) {
+    lines.push("> \u4EE5\u4E0A\u662F\u5DF2\u5220\u9664/\u62C6\u5206\u5236\u54C1\u6216\u5931\u6548\u8FFD\u6EAF\u8FB9\u9057\u7559\u7684\u9501\u3002\u786E\u8BA4\u4E0D\u518D\u9700\u8981\u540E\u8FD0\u884C `artifact-graph version-lock refresh --all --remove-orphans --format markdown` \u6E05\u7406\uFF0C\u5BA1\u67E5 `git diff artifacts/traceability-version-lock.json` \u540E\u518D\u6682\u5B58\u3002");
+    lines.push("");
+  }
+  appendList(lines, "\u5220\u9664\u7684\u5B64\u7ACB\u9501", result.removedOrphans);
+  appendList(lines, "\u65B0\u589E\u7684\u5236\u54C1\u5173\u7CFB\u9501", result.addedArtifactRelationLocks);
+  appendList(lines, "\u66F4\u65B0\u7684\u5236\u54C1\u5173\u7CFB\u9501", result.updatedArtifactRelationLocks);
+  appendList(lines, "\u4FDD\u7559\u7684\u5B64\u7ACB\u5236\u54C1\u5173\u7CFB\u9501", result.retainedArtifactRelationOrphans);
+  if (result.retainedArtifactRelationOrphans.length > 0) {
+    lines.push("> \u4EE5\u4E0A\u662F\u5931\u6548\u5236\u54C1\u5173\u7CFB\u9057\u7559\u7684\u9501\u3002\u786E\u8BA4\u540E\u8FD0\u884C `artifact-graph version-lock refresh --all --remove-orphans --format markdown` \u6E05\u7406\uFF0C\u5BA1\u67E5\u9501 diff \u540E\u518D\u6682\u5B58\u3002");
+    lines.push("");
+  }
+  appendList(lines, "\u5220\u9664\u7684\u5236\u54C1\u5173\u7CFB\u9501", result.removedArtifactRelationLocks);
+  appendList(lines, "\u63D0\u9192", result.warnings);
   if (result.postAudit.issues.length > 0) {
-    lines.push("## Post-Audit Issues");
-    for (const issue2 of result.postAudit.issues) {
-      lines.push(`- [${issue2.status}] \`${issue2.edgeId}\` \u2014 ${issue2.message}`);
+    if (blockingCount > 0) {
+      lines.push(`## \u5237\u65B0\u540E\u5BA1\u8BA1\u95EE\u9898\uFF08\u963B\u65AD ${blockingCount}\uFF0C\u4E0D\u963B\u65AD ${nonBlockingCount}\uFF09`);
+    } else {
+      lines.push(`## \u5237\u65B0\u540E\u5BA1\u8BA1\u95EE\u9898\uFF08\u5F53\u524D\u7B56\u7565\u4E0B\u5168\u90E8\u4E0D\u963B\u65AD\uFF09`);
     }
     lines.push("");
+    appendIssueDetails(lines, result.postAudit.issues, strictMissingLock);
   }
   return `${lines.join("\n")}
 `;
@@ -2497,7 +2634,7 @@ async function isFileActiveInRunner(root, filePath, runner) {
 function sortUnique(items) {
   return [...new Set(items)].sort((left, right) => left.localeCompare(right));
 }
-var import_node_crypto, import_node_fs, import_promises2, import_node_path2, VERSION_LOCK_PATH, VERSION_INDEX_SCHEMA_VERSION, VERSION_LOCK_SCHEMA_VERSION;
+var import_node_crypto, import_node_fs, import_promises2, import_node_path2, VERSION_LOCK_PATH, VERSION_INDEX_SCHEMA_VERSION, VERSION_LOCK_SCHEMA_VERSION, LIVENESS_MESSAGE_PREFIX, VERSION_LOCK_STATUS_LABELS;
 var init_versioned_traceability = __esm({
   "src/versioned-traceability.ts"() {
     "use strict";
@@ -2510,6 +2647,16 @@ var init_versioned_traceability = __esm({
     VERSION_LOCK_PATH = "artifacts/traceability-version-lock.json";
     VERSION_INDEX_SCHEMA_VERSION = "1.0";
     VERSION_LOCK_SCHEMA_VERSION = "1.0";
+    LIVENESS_MESSAGE_PREFIX = "Liveness:";
+    VERSION_LOCK_STATUS_LABELS = {
+      fresh: "\u65B0\u9C9C",
+      target_not_found: "\u76EE\u6807\u5236\u54C1\u4E0D\u5B58\u5728",
+      artifact_changed: "\u5236\u54C1\u5DF2\u53D8\u5316",
+      source_changed: "\u6E90\u7801/\u6D4B\u8BD5\u5DF2\u53D8\u5316",
+      verified_by_changed: "\u9A8C\u8BC1\u6587\u4EF6\u5DF2\u53D8\u5316",
+      missing_lock: "\u7F3A\u5C11\u7248\u672C\u9501",
+      orphan_lock: "\u5B64\u7ACB\u9501"
+    };
   }
 });
 
@@ -4351,6 +4498,7 @@ __export(index_exports, {
   isPacketTargetType: () => isPacketTargetType,
   isPacketTargetTypeDynamic: () => isPacketTargetTypeDynamic,
   isTargetArtifactType: () => isTargetArtifactType,
+  isVersionLockIssueBlocking: () => isVersionLockIssueBlocking,
   loadConfig: () => loadConfig,
   loadContract: () => loadContract,
   loadContractCatalog: () => loadContractCatalog,
@@ -4391,6 +4539,7 @@ __export(index_exports, {
   validateScenarioPrdLinkIndex: () => validateScenarioPrdLinkIndex,
   validateScenarioPrdLinks: () => validateScenarioPrdLinks,
   verifyDigest: () => verifyDigest,
+  versionLockIssueSeverity: () => versionLockIssueSeverity,
   writeGraphCache: () => writeGraphCache
 });
 module.exports = __toCommonJS(index_exports);
@@ -8457,6 +8606,7 @@ init_index();
   isPacketTargetType,
   isPacketTargetTypeDynamic,
   isTargetArtifactType,
+  isVersionLockIssueBlocking,
   loadConfig,
   loadContract,
   loadContractCatalog,
@@ -8497,5 +8647,6 @@ init_index();
   validateScenarioPrdLinkIndex,
   validateScenarioPrdLinks,
   verifyDigest,
+  versionLockIssueSeverity,
   writeGraphCache
 });

package/dist/index.d.cts

@@ -509,10 +509,20 @@ interface VersionLockFile {
     locks: VersionLockEntry[];
     artifactRelations?: ArtifactRelationLock[];
 }
+type VersionLockIssueSeverity = 'error' | 'warning';
 interface VersionLockIssue {
     status: VersionLockStatus;
     edgeId: string;
     message: string;
+    /**
+     * Backward-compatible severity. `error` issues block audit/refresh exit codes;
+     * `warning` issues (e.g. runner liveness hints, non-strict missing_lock) never
+     * block on their own. Older producers may omit it; consumers should fall back
+     * via `versionLockIssueSeverity`.
+     */
+    severity?: VersionLockIssueSeverity;
+    /** Human-readable remediation steps (Chinese), ordered. */
+    remediation?: string[];
     artifact?: VersionLockRef;
     source?: VersionLockSourceRef | VersionLockRef;
     currentArtifactHash?: string;
@@ -580,11 +590,42 @@ interface VersionLockRefreshResult {
 }
 declare function buildVersionIndex(root: string, graph?: ArtifactGraph): Promise<VersionIndex>;
 declare function auditVersionLock(root: string, lockPath?: string, graph?: ArtifactGraph, config?: ArtifactSchema): Promise<VersionLockAuditResult>;
+/**
+ * Resolve the effective severity of an issue, tolerating issues produced before
+ * the severity field existed. Structural orphans and stale hashes are errors;
+ * runner liveness hints and missing locks are warnings (missing_lock is only
+ * escalated to blocking by the --strict-missing-lock policy, not by severity).
+ */
+declare function versionLockIssueSeverity(issue: {
+    status: string;
+    message: string;
+    severity?: VersionLockIssueSeverity;
+}): VersionLockIssueSeverity;
+/**
+ * Decide whether an issue blocks the current command under the given policy.
+ * This is deliberately separate from the intrinsic `severity`: missing_lock is
+ * a warning by nature, but the --strict-missing-lock policy (always on for
+ * `version-lock refresh`, opt-in for `audit`/`trace-version`) escalates it to
+ * blocking. CLI exit codes and Markdown rendering must both go through this
+ * function so they never disagree.
+ */
+declare function isVersionLockIssueBlocking(issue: {
+    status: string;
+    message: string;
+    severity?: VersionLockIssueSeverity;
+}, strictMissingLock: boolean): boolean;
 declare function updateVersionLock(root: string, options: VersionLockUpdateOptions): Promise<VersionLockFile>;
 declare function bootstrapVersionLock(root: string, options?: VersionLockBootstrapOptions): Promise<VersionLockFile>;
 declare function refreshVersionLock(root: string, options?: VersionLockRefreshOptions): Promise<VersionLockRefreshResult>;
 declare function traceVersion(root: string, target: string, lockPath?: string): Promise<TraceVersionResult>;
-declare function renderVersionLockAuditMarkdown(result: VersionLockAuditResult): string;
+interface VersionLockAuditMarkdownOptions {
+    /**
+     * 当前命令的 missing_lock 阻断策略。CLI 必须传入实际的
+     * --strict-missing-lock flag，否则 markdown 的“是否阻断”会与退出码不一致。
+     */
+    strictMissingLock?: boolean;
+}
+declare function renderVersionLockAuditMarkdown(result: VersionLockAuditResult, options?: VersionLockAuditMarkdownOptions): string;
 declare function renderVersionLockRefreshMarkdown(result: VersionLockRefreshResult): string;
 declare function renderTraceVersionMarkdown(result: TraceVersionResult): string;
 
@@ -1456,4 +1497,4 @@ declare function discoverTargets(graph: ArtifactGraph, options?: DiscoverOptions
 declare function resolveArtifactContext(graph: ArtifactGraph, opts: ContextOptions): ContextManifest;
 declare function formatContextMarkdown(manifest: ContextManifest): string;
 
-export { ALWAYS_PRESENT_ITEMS as ALWAYS_PRESENT, type ArtifactChainDoctorReport, type ArtifactEdge, type ArtifactEdgeRule, type ArtifactExtraFieldSchema, type ArtifactGraph, type ArtifactGraphCliCandidate, type ArtifactGraphCliResolution, type ArtifactGraphCliSource, type ArtifactNode, type ArtifactSchema, type ArtifactTarget, type ArtifactTypeMetadata, type ArtifactTypeRole, type ArtifactTypeSchema, BASELINE_CONSTRAINTS, BASELINE_CONSTRAINTS_COUNT, BASELINE_ITEMS_COUNT, type BatchDefinition, CONTRACT_ERROR_CODES, type CanonicalIR, type CollectChangedPathsOptions, type ContextItem, type ContextManifest, type ContextMode, type ContextOptions, type ContextTier, ContractCatalog, type ContractCatalogEntry, type ContractDefinition, ContractError, type ContractErrorCode, type ContractIdentity, ContractRegistry, type ContractRegistryEntry, type ContractSchema, DEFAULT_MAX_CHARS, DEFAULT_SCHEMA, type DiscoverOptions, E2E_NORMALIZER_CONFIG, type E2eCoverageStats, type E2eCoverageThresholds, type E2eRegistry, type E2eRegistryBatch, type E2eRunnerConfig, type E2eWaiver, type Evidence, type EvidenceObject, type ExecutorType, type Finding, type FindingLocation, type FindingSeverity, type FindingStatus, type GitChangeMode, type GitChangeResult, type GitHookName, type HookInstallResult, type ImplementationBlueprintDraft, type ImplementationPacket, type LegacyFieldMapping, type LoadContractOptions, MIN_PROMPT_CHARS, type ManagedHookBlockOptions, type MissingDetail, type NormalizationResult, type NormalizerConfig, type PacketAuditEntry, type PacketAuditSummary, type PacketCategory, type PacketItem, type PacketOmittedItem, type PacketOptions, type PacketPromptError, type PacketPromptOptions, type PacketTarget, type PacketTargetType, type PacketValidationIssue, type PacketValidationResult, type PolicyCompatibilityResult, type PreparedManagedHookBlock, type Producer, type ProjectPolicy, type PromptValidationIssue, type PromptValidationResult, type QueryOptions, type RepairData, type RepairValidation, type ResolveArtifactGraphCliOptions, type ReviewData, type ReviewDecision, type ReviewMetrics, type ReviewOrderStep, type ReviewResult, type ReviewStatus, type RiskChecklistItem, type SchemaValidationResult, TARGET_ARTIFACT_TYPES, type TargetArtifactType, type TraceVersionResult, VALID_PACKET_TARGET_TYPES, VERSION_INDEX_SCHEMA_VERSION, VERSION_LOCK_PATH, VERSION_LOCK_SCHEMA_VERSION, type ValidationError, type ValidationIssue, type VersionEdgeKind, type VersionIndex, type VersionLockAuditResult, type VersionLockBootstrapOptions, type VersionLockEntry, type VersionLockFile, type VersionLockIssue, type VersionLockRef, type VersionLockRefreshOptions, type VersionLockRefreshResult, type VersionLockSourceRef, type VersionLockStatus, type VersionLockUpdateOptions, type VersionSourceKind, type VersionedEdge, type VersionedNode, applyPreparedManagedHookBlocks, assemblePacket, auditPackets, auditVersionLock, bootstrapVersionLock, buildGraph, buildVersionIndex, collectChangedPaths, computeE2eCoverageStats, computeRevisionDigest, discoverAndAuditPackets, discoverTargets, doctorArtifactChain, formatContextMarkdown, generateE2eRegistry, getArtifactTypeMetadata, getTargetArtifactTypes, installManagedHookBlock, isOfficialNamespace, isPacketTargetType, isPacketTargetTypeDynamic, isTargetArtifactType, loadConfig, loadContract, loadContractCatalog, loadContractsFromDirectory, nextId, normalizeE2eLegacyArtifact, normalizeToCanonical, parseTargetSelector, parseTargetsFile, prepareManagedHookBlock, queryGraph, refreshVersionLock, renderDoctorMarkdown, renderMermaid, renderPacketMarkdown, renderPacketPrompt, renderTraceVersionMarkdown, renderVersionLockAuditMarkdown, renderVersionLockRefreshMarkdown, resolveArtifactContext, resolveArtifactGraphCli, resolveArtifactTypeName, resolveCliTarget, resolveGitHookPath, resolveMatrixEdges, scanArtifacts, traceVersion, updateVersionLock, validateContractAgainstSchema, validateExecutableTraceability, validateGraph, validateNamespaceAuthority, validatePacket, validatePacketMarkdown, validatePacketPrompt, validatePolicyCompatibility, validateReviewResult, validateScenarioPrdLinkIndex, validateScenarioPrdLinks, verifyDigest, writeGraphCache };
+export { ALWAYS_PRESENT_ITEMS as ALWAYS_PRESENT, type ArtifactChainDoctorReport, type ArtifactEdge, type ArtifactEdgeRule, type ArtifactExtraFieldSchema, type ArtifactGraph, type ArtifactGraphCliCandidate, type ArtifactGraphCliResolution, type ArtifactGraphCliSource, type ArtifactNode, type ArtifactSchema, type ArtifactTarget, type ArtifactTypeMetadata, type ArtifactTypeRole, type ArtifactTypeSchema, BASELINE_CONSTRAINTS, BASELINE_CONSTRAINTS_COUNT, BASELINE_ITEMS_COUNT, type BatchDefinition, CONTRACT_ERROR_CODES, type CanonicalIR, type CollectChangedPathsOptions, type ContextItem, type ContextManifest, type ContextMode, type ContextOptions, type ContextTier, ContractCatalog, type ContractCatalogEntry, type ContractDefinition, ContractError, type ContractErrorCode, type ContractIdentity, ContractRegistry, type ContractRegistryEntry, type ContractSchema, DEFAULT_MAX_CHARS, DEFAULT_SCHEMA, type DiscoverOptions, E2E_NORMALIZER_CONFIG, type E2eCoverageStats, type E2eCoverageThresholds, type E2eRegistry, type E2eRegistryBatch, type E2eRunnerConfig, type E2eWaiver, type Evidence, type EvidenceObject, type ExecutorType, type Finding, type FindingLocation, type FindingSeverity, type FindingStatus, type GitChangeMode, type GitChangeResult, type GitHookName, type HookInstallResult, type ImplementationBlueprintDraft, type ImplementationPacket, type LegacyFieldMapping, type LoadContractOptions, MIN_PROMPT_CHARS, type ManagedHookBlockOptions, type MissingDetail, type NormalizationResult, type NormalizerConfig, type PacketAuditEntry, type PacketAuditSummary, type PacketCategory, type PacketItem, type PacketOmittedItem, type PacketOptions, type PacketPromptError, type PacketPromptOptions, type PacketTarget, type PacketTargetType, type PacketValidationIssue, type PacketValidationResult, type PolicyCompatibilityResult, type PreparedManagedHookBlock, type Producer, type ProjectPolicy, type PromptValidationIssue, type PromptValidationResult, type QueryOptions, type RepairData, type RepairValidation, type ResolveArtifactGraphCliOptions, type ReviewData, type ReviewDecision, type ReviewMetrics, type ReviewOrderStep, type ReviewResult, type ReviewStatus, type RiskChecklistItem, type SchemaValidationResult, TARGET_ARTIFACT_TYPES, type TargetArtifactType, type TraceVersionResult, VALID_PACKET_TARGET_TYPES, VERSION_INDEX_SCHEMA_VERSION, VERSION_LOCK_PATH, VERSION_LOCK_SCHEMA_VERSION, type ValidationError, type ValidationIssue, type VersionEdgeKind, type VersionIndex, type VersionLockAuditMarkdownOptions, type VersionLockAuditResult, type VersionLockBootstrapOptions, type VersionLockEntry, type VersionLockFile, type VersionLockIssue, type VersionLockIssueSeverity, type VersionLockRef, type VersionLockRefreshOptions, type VersionLockRefreshResult, type VersionLockSourceRef, type VersionLockStatus, type VersionLockUpdateOptions, type VersionSourceKind, type VersionedEdge, type VersionedNode, applyPreparedManagedHookBlocks, assemblePacket, auditPackets, auditVersionLock, bootstrapVersionLock, buildGraph, buildVersionIndex, collectChangedPaths, computeE2eCoverageStats, computeRevisionDigest, discoverAndAuditPackets, discoverTargets, doctorArtifactChain, formatContextMarkdown, generateE2eRegistry, getArtifactTypeMetadata, getTargetArtifactTypes, installManagedHookBlock, isOfficialNamespace, isPacketTargetType, isPacketTargetTypeDynamic, isTargetArtifactType, isVersionLockIssueBlocking, loadConfig, loadContract, loadContractCatalog, loadContractsFromDirectory, nextId, normalizeE2eLegacyArtifact, normalizeToCanonical, parseTargetSelector, parseTargetsFile, prepareManagedHookBlock, queryGraph, refreshVersionLock, renderDoctorMarkdown, renderMermaid, renderPacketMarkdown, renderPacketPrompt, renderTraceVersionMarkdown, renderVersionLockAuditMarkdown, renderVersionLockRefreshMarkdown, resolveArtifactContext, resolveArtifactGraphCli, resolveArtifactTypeName, resolveCliTarget, resolveGitHookPath, resolveMatrixEdges, scanArtifacts, traceVersion, updateVersionLock, validateContractAgainstSchema, validateExecutableTraceability, validateGraph, validateNamespaceAuthority, validatePacket, validatePacketMarkdown, validatePacketPrompt, validatePolicyCompatibility, validateReviewResult, validateScenarioPrdLinkIndex, validateScenarioPrdLinks, verifyDigest, versionLockIssueSeverity, writeGraphCache };

package/dist/index.d.ts

@@ -509,10 +509,20 @@ interface VersionLockFile {
     locks: VersionLockEntry[];
     artifactRelations?: ArtifactRelationLock[];
 }
+type VersionLockIssueSeverity = 'error' | 'warning';
 interface VersionLockIssue {
     status: VersionLockStatus;
     edgeId: string;
     message: string;
+    /**
+     * Backward-compatible severity. `error` issues block audit/refresh exit codes;
+     * `warning` issues (e.g. runner liveness hints, non-strict missing_lock) never
+     * block on their own. Older producers may omit it; consumers should fall back
+     * via `versionLockIssueSeverity`.
+     */
+    severity?: VersionLockIssueSeverity;
+    /** Human-readable remediation steps (Chinese), ordered. */
+    remediation?: string[];
     artifact?: VersionLockRef;
     source?: VersionLockSourceRef | VersionLockRef;
     currentArtifactHash?: string;
@@ -580,11 +590,42 @@ interface VersionLockRefreshResult {
 }
 declare function buildVersionIndex(root: string, graph?: ArtifactGraph): Promise<VersionIndex>;
 declare function auditVersionLock(root: string, lockPath?: string, graph?: ArtifactGraph, config?: ArtifactSchema): Promise<VersionLockAuditResult>;
+/**
+ * Resolve the effective severity of an issue, tolerating issues produced before
+ * the severity field existed. Structural orphans and stale hashes are errors;
+ * runner liveness hints and missing locks are warnings (missing_lock is only
+ * escalated to blocking by the --strict-missing-lock policy, not by severity).
+ */
+declare function versionLockIssueSeverity(issue: {
+    status: string;
+    message: string;
+    severity?: VersionLockIssueSeverity;
+}): VersionLockIssueSeverity;
+/**
+ * Decide whether an issue blocks the current command under the given policy.
+ * This is deliberately separate from the intrinsic `severity`: missing_lock is
+ * a warning by nature, but the --strict-missing-lock policy (always on for
+ * `version-lock refresh`, opt-in for `audit`/`trace-version`) escalates it to
+ * blocking. CLI exit codes and Markdown rendering must both go through this
+ * function so they never disagree.
+ */
+declare function isVersionLockIssueBlocking(issue: {
+    status: string;
+    message: string;
+    severity?: VersionLockIssueSeverity;
+}, strictMissingLock: boolean): boolean;
 declare function updateVersionLock(root: string, options: VersionLockUpdateOptions): Promise<VersionLockFile>;
 declare function bootstrapVersionLock(root: string, options?: VersionLockBootstrapOptions): Promise<VersionLockFile>;
 declare function refreshVersionLock(root: string, options?: VersionLockRefreshOptions): Promise<VersionLockRefreshResult>;
 declare function traceVersion(root: string, target: string, lockPath?: string): Promise<TraceVersionResult>;
-declare function renderVersionLockAuditMarkdown(result: VersionLockAuditResult): string;
+interface VersionLockAuditMarkdownOptions {
+    /**
+     * 当前命令的 missing_lock 阻断策略。CLI 必须传入实际的
+     * --strict-missing-lock flag，否则 markdown 的“是否阻断”会与退出码不一致。
+     */
+    strictMissingLock?: boolean;
+}
+declare function renderVersionLockAuditMarkdown(result: VersionLockAuditResult, options?: VersionLockAuditMarkdownOptions): string;
 declare function renderVersionLockRefreshMarkdown(result: VersionLockRefreshResult): string;
 declare function renderTraceVersionMarkdown(result: TraceVersionResult): string;
 
@@ -1456,4 +1497,4 @@ declare function discoverTargets(graph: ArtifactGraph, options?: DiscoverOptions
 declare function resolveArtifactContext(graph: ArtifactGraph, opts: ContextOptions): ContextManifest;
 declare function formatContextMarkdown(manifest: ContextManifest): string;
 
-export { ALWAYS_PRESENT_ITEMS as ALWAYS_PRESENT, type ArtifactChainDoctorReport, type ArtifactEdge, type ArtifactEdgeRule, type ArtifactExtraFieldSchema, type ArtifactGraph, type ArtifactGraphCliCandidate, type ArtifactGraphCliResolution, type ArtifactGraphCliSource, type ArtifactNode, type ArtifactSchema, type ArtifactTarget, type ArtifactTypeMetadata, type ArtifactTypeRole, type ArtifactTypeSchema, BASELINE_CONSTRAINTS, BASELINE_CONSTRAINTS_COUNT, BASELINE_ITEMS_COUNT, type BatchDefinition, CONTRACT_ERROR_CODES, type CanonicalIR, type CollectChangedPathsOptions, type ContextItem, type ContextManifest, type ContextMode, type ContextOptions, type ContextTier, ContractCatalog, type ContractCatalogEntry, type ContractDefinition, ContractError, type ContractErrorCode, type ContractIdentity, ContractRegistry, type ContractRegistryEntry, type ContractSchema, DEFAULT_MAX_CHARS, DEFAULT_SCHEMA, type DiscoverOptions, E2E_NORMALIZER_CONFIG, type E2eCoverageStats, type E2eCoverageThresholds, type E2eRegistry, type E2eRegistryBatch, type E2eRunnerConfig, type E2eWaiver, type Evidence, type EvidenceObject, type ExecutorType, type Finding, type FindingLocation, type FindingSeverity, type FindingStatus, type GitChangeMode, type GitChangeResult, type GitHookName, type HookInstallResult, type ImplementationBlueprintDraft, type ImplementationPacket, type LegacyFieldMapping, type LoadContractOptions, MIN_PROMPT_CHARS, type ManagedHookBlockOptions, type MissingDetail, type NormalizationResult, type NormalizerConfig, type PacketAuditEntry, type PacketAuditSummary, type PacketCategory, type PacketItem, type PacketOmittedItem, type PacketOptions, type PacketPromptError, type PacketPromptOptions, type PacketTarget, type PacketTargetType, type PacketValidationIssue, type PacketValidationResult, type PolicyCompatibilityResult, type PreparedManagedHookBlock, type Producer, type ProjectPolicy, type PromptValidationIssue, type PromptValidationResult, type QueryOptions, type RepairData, type RepairValidation, type ResolveArtifactGraphCliOptions, type ReviewData, type ReviewDecision, type ReviewMetrics, type ReviewOrderStep, type ReviewResult, type ReviewStatus, type RiskChecklistItem, type SchemaValidationResult, TARGET_ARTIFACT_TYPES, type TargetArtifactType, type TraceVersionResult, VALID_PACKET_TARGET_TYPES, VERSION_INDEX_SCHEMA_VERSION, VERSION_LOCK_PATH, VERSION_LOCK_SCHEMA_VERSION, type ValidationError, type ValidationIssue, type VersionEdgeKind, type VersionIndex, type VersionLockAuditResult, type VersionLockBootstrapOptions, type VersionLockEntry, type VersionLockFile, type VersionLockIssue, type VersionLockRef, type VersionLockRefreshOptions, type VersionLockRefreshResult, type VersionLockSourceRef, type VersionLockStatus, type VersionLockUpdateOptions, type VersionSourceKind, type VersionedEdge, type VersionedNode, applyPreparedManagedHookBlocks, assemblePacket, auditPackets, auditVersionLock, bootstrapVersionLock, buildGraph, buildVersionIndex, collectChangedPaths, computeE2eCoverageStats, computeRevisionDigest, discoverAndAuditPackets, discoverTargets, doctorArtifactChain, formatContextMarkdown, generateE2eRegistry, getArtifactTypeMetadata, getTargetArtifactTypes, installManagedHookBlock, isOfficialNamespace, isPacketTargetType, isPacketTargetTypeDynamic, isTargetArtifactType, loadConfig, loadContract, loadContractCatalog, loadContractsFromDirectory, nextId, normalizeE2eLegacyArtifact, normalizeToCanonical, parseTargetSelector, parseTargetsFile, prepareManagedHookBlock, queryGraph, refreshVersionLock, renderDoctorMarkdown, renderMermaid, renderPacketMarkdown, renderPacketPrompt, renderTraceVersionMarkdown, renderVersionLockAuditMarkdown, renderVersionLockRefreshMarkdown, resolveArtifactContext, resolveArtifactGraphCli, resolveArtifactTypeName, resolveCliTarget, resolveGitHookPath, resolveMatrixEdges, scanArtifacts, traceVersion, updateVersionLock, validateContractAgainstSchema, validateExecutableTraceability, validateGraph, validateNamespaceAuthority, validatePacket, validatePacketMarkdown, validatePacketPrompt, validatePolicyCompatibility, validateReviewResult, validateScenarioPrdLinkIndex, validateScenarioPrdLinks, verifyDigest, writeGraphCache };
+export { ALWAYS_PRESENT_ITEMS as ALWAYS_PRESENT, type ArtifactChainDoctorReport, type ArtifactEdge, type ArtifactEdgeRule, type ArtifactExtraFieldSchema, type ArtifactGraph, type ArtifactGraphCliCandidate, type ArtifactGraphCliResolution, type ArtifactGraphCliSource, type ArtifactNode, type ArtifactSchema, type ArtifactTarget, type ArtifactTypeMetadata, type ArtifactTypeRole, type ArtifactTypeSchema, BASELINE_CONSTRAINTS, BASELINE_CONSTRAINTS_COUNT, BASELINE_ITEMS_COUNT, type BatchDefinition, CONTRACT_ERROR_CODES, type CanonicalIR, type CollectChangedPathsOptions, type ContextItem, type ContextManifest, type ContextMode, type ContextOptions, type ContextTier, ContractCatalog, type ContractCatalogEntry, type ContractDefinition, ContractError, type ContractErrorCode, type ContractIdentity, ContractRegistry, type ContractRegistryEntry, type ContractSchema, DEFAULT_MAX_CHARS, DEFAULT_SCHEMA, type DiscoverOptions, E2E_NORMALIZER_CONFIG, type E2eCoverageStats, type E2eCoverageThresholds, type E2eRegistry, type E2eRegistryBatch, type E2eRunnerConfig, type E2eWaiver, type Evidence, type EvidenceObject, type ExecutorType, type Finding, type FindingLocation, type FindingSeverity, type FindingStatus, type GitChangeMode, type GitChangeResult, type GitHookName, type HookInstallResult, type ImplementationBlueprintDraft, type ImplementationPacket, type LegacyFieldMapping, type LoadContractOptions, MIN_PROMPT_CHARS, type ManagedHookBlockOptions, type MissingDetail, type NormalizationResult, type NormalizerConfig, type PacketAuditEntry, type PacketAuditSummary, type PacketCategory, type PacketItem, type PacketOmittedItem, type PacketOptions, type PacketPromptError, type PacketPromptOptions, type PacketTarget, type PacketTargetType, type PacketValidationIssue, type PacketValidationResult, type PolicyCompatibilityResult, type PreparedManagedHookBlock, type Producer, type ProjectPolicy, type PromptValidationIssue, type PromptValidationResult, type QueryOptions, type RepairData, type RepairValidation, type ResolveArtifactGraphCliOptions, type ReviewData, type ReviewDecision, type ReviewMetrics, type ReviewOrderStep, type ReviewResult, type ReviewStatus, type RiskChecklistItem, type SchemaValidationResult, TARGET_ARTIFACT_TYPES, type TargetArtifactType, type TraceVersionResult, VALID_PACKET_TARGET_TYPES, VERSION_INDEX_SCHEMA_VERSION, VERSION_LOCK_PATH, VERSION_LOCK_SCHEMA_VERSION, type ValidationError, type ValidationIssue, type VersionEdgeKind, type VersionIndex, type VersionLockAuditMarkdownOptions, type VersionLockAuditResult, type VersionLockBootstrapOptions, type VersionLockEntry, type VersionLockFile, type VersionLockIssue, type VersionLockIssueSeverity, type VersionLockRef, type VersionLockRefreshOptions, type VersionLockRefreshResult, type VersionLockSourceRef, type VersionLockStatus, type VersionLockUpdateOptions, type VersionSourceKind, type VersionedEdge, type VersionedNode, applyPreparedManagedHookBlocks, assemblePacket, auditPackets, auditVersionLock, bootstrapVersionLock, buildGraph, buildVersionIndex, collectChangedPaths, computeE2eCoverageStats, computeRevisionDigest, discoverAndAuditPackets, discoverTargets, doctorArtifactChain, formatContextMarkdown, generateE2eRegistry, getArtifactTypeMetadata, getTargetArtifactTypes, installManagedHookBlock, isOfficialNamespace, isPacketTargetType, isPacketTargetTypeDynamic, isTargetArtifactType, isVersionLockIssueBlocking, loadConfig, loadContract, loadContractCatalog, loadContractsFromDirectory, nextId, normalizeE2eLegacyArtifact, normalizeToCanonical, parseTargetSelector, parseTargetsFile, prepareManagedHookBlock, queryGraph, refreshVersionLock, renderDoctorMarkdown, renderMermaid, renderPacketMarkdown, renderPacketPrompt, renderTraceVersionMarkdown, renderVersionLockAuditMarkdown, renderVersionLockRefreshMarkdown, resolveArtifactContext, resolveArtifactGraphCli, resolveArtifactTypeName, resolveCliTarget, resolveGitHookPath, resolveMatrixEdges, scanArtifacts, traceVersion, updateVersionLock, validateContractAgainstSchema, validateExecutableTraceability, validateGraph, validateNamespaceAuthority, validatePacket, validatePacketMarkdown, validatePacketPrompt, validatePolicyCompatibility, validateReviewResult, validateScenarioPrdLinkIndex, validateScenarioPrdLinks, verifyDigest, versionLockIssueSeverity, writeGraphCache };

package/dist/index.js

@@ -1540,6 +1540,7 @@ async function auditVersionLock(root, lockPath = VERSION_LOCK_PATH, graph, confi
         status: "orphan_lock",
         edgeId: entry.edgeId,
         message: `Liveness: ${sourcePath} is not active in any configured runner \u2014 locked verifies edges may reference dead tests`,
+        severity: "warning",
         artifact: entry.artifact,
         source: entry.source
       });
@@ -1669,7 +1670,84 @@ async function auditVersionLock(root, lockPath = VERSION_LOCK_PATH, graph, confi
     fresh,
     totalArtifactRelationLocks: artifactRelationLocks.length,
     artifactRelationFresh,
-    issues: sortBy(issues, (issue2) => `${issue2.status}	${issue2.edgeId}	${issue2.verifiedByPath ?? ""}`)
+    issues: sortBy(issues.map(enrichVersionLockIssue), (issue2) => `${issue2.status}	${issue2.edgeId}	${issue2.verifiedByPath ?? ""}`)
+  };
+}
+function isLivenessIssue(issue2) {
+  return issue2.status === "orphan_lock" && issue2.message.startsWith(LIVENESS_MESSAGE_PREFIX);
+}
+function versionLockIssueSeverity(issue2) {
+  if (issue2.severity) {
+    return issue2.severity;
+  }
+  if (issue2.status === "missing_lock") {
+    return "warning";
+  }
+  if (issue2.status === "orphan_lock" && issue2.message.startsWith(LIVENESS_MESSAGE_PREFIX)) {
+    return "warning";
+  }
+  return "error";
+}
+function isVersionLockIssueBlocking(issue2, strictMissingLock) {
+  if (issue2.status === "missing_lock") {
+    return strictMissingLock;
+  }
+  return versionLockIssueSeverity(issue2) === "error";
+}
+function versionLockIssueRemediation(issue2) {
+  switch (issue2.status) {
+    case "artifact_changed":
+      return [
+        "\u786E\u8BA4\u8FD9\u6B21\u5236\u54C1\u53D8\u66F4\uFF08\u5185\u5BB9\u6216\u8DEF\u5F84\uFF09\u662F\u6709\u610F\u7684\u3002",
+        "\u8FD0\u884C `artifact-graph version-lock refresh --changed-only --worktree --format markdown`\uFF08\u65E5\u5E38\u5F00\u53D1\uFF09\u6216 `artifact-graph version-lock refresh --changed-only --staged --format markdown`\uFF08\u63D0\u4EA4\u524D\uFF09\u5237\u65B0\u53D7\u5F71\u54CD\u7684\u9501\u3002",
+        "\u8FD0\u884C `git diff artifacts/traceability-version-lock.json` \u5BA1\u67E5\u9501\u53D8\u66F4\uFF0C\u786E\u8BA4\u540E `git add artifacts/traceability-version-lock.json` \u5E76\u91CD\u65B0\u63D0\u4EA4\u3002"
+      ];
+    case "source_changed":
+      return [
+        "\u786E\u8BA4\u8FD9\u6B21\u6E90\u7801/\u6D4B\u8BD5\u53D8\u66F4\uFF08\u5185\u5BB9\u6216\u8DEF\u5F84\uFF09\u662F\u6709\u610F\u7684\u3002",
+        "\u8FD0\u884C `artifact-graph version-lock refresh --changed-only --worktree --format markdown`\uFF08\u65E5\u5E38\u5F00\u53D1\uFF09\u6216 `artifact-graph version-lock refresh --changed-only --staged --format markdown`\uFF08\u63D0\u4EA4\u524D\uFF09\u5237\u65B0\u53D7\u5F71\u54CD\u7684\u9501\u3002",
+        "\u8FD0\u884C `git diff artifacts/traceability-version-lock.json` \u5BA1\u67E5\u9501\u53D8\u66F4\uFF0C\u786E\u8BA4\u540E `git add artifacts/traceability-version-lock.json` \u5E76\u91CD\u65B0\u63D0\u4EA4\u3002"
+      ];
+    case "verified_by_changed":
+      return [
+        "\u786E\u8BA4\u8FD9\u6B21\u9A8C\u8BC1\u6587\u4EF6\u53D8\u66F4\u662F\u6709\u610F\u7684\u3002",
+        "\u8FD0\u884C `artifact-graph version-lock refresh --changed-only --worktree --format markdown`\uFF08\u65E5\u5E38\u5F00\u53D1\uFF09\u6216 `artifact-graph version-lock refresh --changed-only --staged --format markdown`\uFF08\u63D0\u4EA4\u524D\uFF09\u5237\u65B0\u53D7\u5F71\u54CD\u7684\u9501\u3002",
+        "\u8FD0\u884C `git diff artifacts/traceability-version-lock.json` \u5BA1\u67E5\u9501\u53D8\u66F4\uFF0C\u786E\u8BA4\u540E `git add artifacts/traceability-version-lock.json` \u5E76\u91CD\u65B0\u63D0\u4EA4\u3002"
+      ];
+    case "missing_lock":
+      return [
+        "\u65B0\u589E\u8FFD\u6EAF\u8FB9\u8FD8\u6CA1\u6709\u5BF9\u5E94\u7248\u672C\u9501\uFF1B\u9ED8\u8BA4\u4E0D\u963B\u65AD\uFF0C`--strict-missing-lock` \u4E0B\u4F1A\u963B\u65AD\u3002",
+        "\u8FD0\u884C `artifact-graph version-lock refresh --changed-only --worktree --format markdown` \u4E3A\u53D7\u5F71\u54CD\u8FB9\u8865\u9501\uFF1B\u9996\u6B21\u5EFA\u7ACB\u57FA\u7EBF\u6216\u914D\u7F6E\u53D8\u66F4\u65F6\u7528 `artifact-graph version-lock refresh --all --format markdown`\u3002",
+        "\u8FD0\u884C `git diff artifacts/traceability-version-lock.json` \u5BA1\u67E5\u540E `git add artifacts/traceability-version-lock.json` \u6682\u5B58\u3002"
+      ];
+    case "orphan_lock":
+      if (isLivenessIssue(issue2)) {
+        return [
+          "\u8FD9\u662F liveness \u8B66\u544A\uFF0C\u4E0D\u662F\u6821\u9A8C\u5931\u8D25\uFF1A\u9501\u4ECD\u7136\u4FDD\u7559\uFF0C\u9ED8\u8BA4\u4E0D\u963B\u65AD\u3002",
+          "\u5982\u679C\u6D4B\u8BD5\u5DF2\u5E9F\u5F03\uFF1A\u5220\u9664\u8BE5\u6587\u4EF6\u6216\u79FB\u9664\u5176\u4E2D\u7684\u8FFD\u6EAF\u6CE8\u91CA\uFF0C\u7136\u540E\u8FD0\u884C `artifact-graph version-lock refresh --all --remove-orphans --format markdown` \u6E05\u7406\u5BF9\u5E94\u7684\u9501\u3002",
+          "\u5982\u679C\u6D4B\u8BD5\u4ECD\u7136\u6709\u6548\uFF1A\u628A\u5B83\u52A0\u5165 artifact-graph.config.yaml \u4E2D\u67D0\u4E2A e2e runner \u7684 include\uFF0C\u6216\u68C0\u67E5 exclude/testIgnore \u662F\u5426\u8BEF\u4F24\u3002"
+        ];
+      }
+      return [
+        "\u9501\u5F15\u7528\u7684\u5236\u54C1\u3001\u6E90\u7801\u6216\u8FFD\u6EAF\u8FB9\u5728\u5F53\u524D\u56FE\u4E2D\u5DF2\u4E0D\u5B58\u5728\uFF0C\u5E38\u89C1\u4E8E\u5236\u54C1\u5220\u9664\u6216\u62C6\u5206\u4E4B\u540E\u3002",
+        "\u786E\u8BA4\u5220\u9664\u662F\u6709\u610F\u7684\u540E\uFF0C\u8FD0\u884C `artifact-graph version-lock refresh --all --remove-orphans --format markdown` \u6E05\u7406\u5B64\u7ACB\u9501\u3002",
+        "\u8FD0\u884C `git diff artifacts/traceability-version-lock.json` \u5BA1\u67E5\u88AB\u79FB\u9664\u7684\u9501\u6761\u76EE\uFF0C\u786E\u8BA4\u540E `git add artifacts/traceability-version-lock.json` \u6682\u5B58\u3002",
+        "\u5982\u679C\u5220\u9664\u662F\u8BEF\u64CD\u4F5C\uFF0C\u5148\u6062\u590D\u5BF9\u5E94\u5236\u54C1\u6216\u6E90\u7801\u6587\u4EF6\uFF0C\u518D\u8FD0\u884C\u4E0D\u5E26 `--remove-orphans` \u7684 refresh \u5237\u65B0\u54C8\u5E0C\u3002"
+      ];
+    case "target_not_found":
+      return [
+        "\u68C0\u67E5 `--target` \u7684 `type:id` \u662F\u5426\u62FC\u5199\u6B63\u786E\u3002",
+        "\u5982\u679C\u8BE5\u5236\u54C1\u5DF2\u88AB\u5220\u9664\u6216\u6539\u540D\uFF0C\u6539\u7528\u5F53\u524D\u5B58\u5728\u7684\u5236\u54C1\u6807\u8BC6\u91CD\u8BD5\u3002"
+      ];
+    default:
+      return [];
+  }
+}
+function enrichVersionLockIssue(issue2) {
+  return {
+    ...issue2,
+    severity: versionLockIssueSeverity(issue2),
+    remediation: issue2.remediation ?? versionLockIssueRemediation(issue2)
   };
 }
 async function updateVersionLock(root, options) {
@@ -1967,59 +2045,118 @@ async function traceVersion(root, target, lockPath = VERSION_LOCK_PATH) {
     currentEdges: index.edges.filter((edge2) => edge2.from === targetUid || edge2.to === targetUid),
     locks: lock.locks.filter((entry) => `${entry.artifact.type}:${entry.artifact.id}` === targetUid),
     artifactRelations: targetArtifactRelations,
-    issues: [...targetIssues, ...audit.issues.filter((issue2) => `${issue2.artifact?.type}:${issue2.artifact?.id}` === targetUid || issue2.edgeId.includes(`#${targetUid}`))]
+    issues: [...targetIssues.map(enrichVersionLockIssue), ...audit.issues.filter((issue2) => `${issue2.artifact?.type}:${issue2.artifact?.id}` === targetUid || issue2.edgeId.includes(`#${targetUid}`))]
   };
 }
-function renderVersionLockAuditMarkdown(result) {
+function renderIssueBlockingTag(issue2, strictMissingLock) {
+  return isVersionLockIssueBlocking(issue2, strictMissingLock) ? "\u963B\u65AD" : "\u8B66\u544A";
+}
+function renderIssueBlockingExplanation(issue2, strictMissingLock) {
+  if (!isVersionLockIssueBlocking(issue2, strictMissingLock)) {
+    return "\u5426\uFF08\u4EC5\u63D0\u9192\uFF0C\u4E0D\u963B\u65AD\uFF09";
+  }
+  if (issue2.status === "missing_lock" && versionLockIssueSeverity(issue2) !== "error") {
+    return "\u662F\uFF08\u5DF2\u7531 --strict-missing-lock \u5347\u7EA7\u4E3A\u963B\u65AD\uFF09";
+  }
+  return "\u662F\uFF08\u4F1A\u4F7F\u547D\u4EE4\u4EE5\u975E\u96F6\u9000\u51FA\u7801\u7ED3\u675F\uFF09";
+}
+function appendIssueDetails(lines, issues, strictMissingLock) {
+  issues.forEach((issue2, index) => {
+    const label = VERSION_LOCK_STATUS_LABELS[issue2.status] ?? issue2.status;
+    lines.push(`### ${index + 1}. [${renderIssueBlockingTag(issue2, strictMissingLock)}] ${label}\uFF08\`${issue2.status}\`\uFF09`);
+    lines.push("");
+    lines.push(`- \u8FB9: \`${issue2.edgeId}\``);
+    lines.push(`- \u8BE6\u60C5: ${issue2.message}`);
+    lines.push(`- \u662F\u5426\u963B\u65AD: ${renderIssueBlockingExplanation(issue2, strictMissingLock)}`);
+    const remediation = issue2.remediation ?? [];
+    if (remediation.length > 0) {
+      lines.push("- \u89E3\u51B3\u6B65\u9AA4:");
+      remediation.forEach((step, stepIndex) => {
+        lines.push(`  ${stepIndex + 1}. ${step}`);
+      });
+    }
+    lines.push("");
+  });
+}
+function renderVersionLockAuditMarkdown(result, options = {}) {
+  const strictMissingLock = options.strictMissingLock === true;
+  const blockingCount = result.issues.filter((issue2) => isVersionLockIssueBlocking(issue2, strictMissingLock)).length;
+  const nonBlockingCount = result.issues.length - blockingCount;
   const lines = [
-    "# Version Lock Audit",
+    "# \u7248\u672C\u9501\u5BA1\u8BA1\uFF08version-lock audit\uFF09",
     "",
-    `Root: \`${result.root}\``,
-    `Lock: \`${result.lockPath}\``,
-    `Locks: ${result.totalLocks} | Fresh: ${result.fresh} | Issues: ${result.issues.length}`,
-    `Artifact Relations: ${result.totalArtifactRelationLocks} | Fresh: ${result.artifactRelationFresh}`,
+    `- \u6839\u76EE\u5F55: \`${result.root}\``,
+    `- \u9501\u6587\u4EF6: \`${result.lockPath}\``,
+    `- \u5B9E\u73B0/\u9A8C\u8BC1\u9501: ${result.totalLocks}\uFF08\u65B0\u9C9C ${result.fresh}\uFF09`,
+    `- \u5236\u54C1\u5173\u7CFB\u9501: ${result.totalArtifactRelationLocks}\uFF08\u65B0\u9C9C ${result.artifactRelationFresh}\uFF09`,
+    `- \u963B\u65AD\u7B56\u7565: ${strictMissingLock ? "--strict-missing-lock\uFF08missing_lock \u5347\u7EA7\u4E3A\u963B\u65AD\uFF09" : "\u9ED8\u8BA4\uFF08missing_lock \u4E0D\u963B\u65AD\uFF09"}`,
+    `- \u95EE\u9898: ${result.issues.length}\uFF08\u963B\u65AD ${blockingCount}\uFF0C\u4E0D\u963B\u65AD ${nonBlockingCount}\uFF09`,
     ""
   ];
   if (result.issues.length === 0) {
-    lines.push("No version lock issues.");
+    lines.push("\u672A\u53D1\u73B0\u7248\u672C\u9501\u95EE\u9898\u3002");
     return `${lines.join("\n")}
 `;
   }
-  for (const issue2 of result.issues) {
-    lines.push(`- [${issue2.status}] \`${issue2.edgeId}\` \u2014 ${issue2.message}`);
+  if (blockingCount > 0) {
+    lines.push(`\u5F53\u524D\u7B56\u7565\u4E0B\u5B58\u5728 ${blockingCount} \u4E2A\u963B\u65AD\u95EE\u9898\uFF0C\u547D\u4EE4\u5C06\u4EE5\u975E\u96F6\u9000\u51FA\u7801\u7ED3\u675F\uFF1B\u8BF7\u6309\u4E0B\u65B9\u6B65\u9AA4\u9010\u9879\u5904\u7406\u3002`);
+  } else {
+    lines.push("\u5F53\u524D\u7B56\u7565\u4E0B\u6CA1\u6709\u963B\u65AD\u95EE\u9898\uFF0C\u4EE5\u4E0B\u4EC5\u4E3A\u63D0\u9192\uFF0C\u547D\u4EE4\u4EE5\u96F6\u9000\u51FA\u7801\u7ED3\u675F\u3002");
   }
+  lines.push("");
+  lines.push("## \u95EE\u9898\u6E05\u5355");
+  lines.push("");
+  appendIssueDetails(lines, result.issues, strictMissingLock);
   return `${lines.join("\n")}
 `;
 }
 function renderVersionLockRefreshMarkdown(result) {
+  const strictMissingLock = true;
+  const blockingCount = result.postAudit.issues.filter((issue2) => isVersionLockIssueBlocking(issue2, strictMissingLock)).length;
+  const nonBlockingCount = result.postAudit.issues.length - blockingCount;
   const lines = [
-    "# Version Lock Refresh",
+    "# \u7248\u672C\u9501\u5237\u65B0\uFF08version-lock refresh\uFF09",
+    "",
+    `- \u6839\u76EE\u5F55: \`${result.root}\``,
+    `- \u9501\u6587\u4EF6: \`${result.lockPath}\``,
+    `- \u6A21\u5F0F: \`${result.mode}\`\uFF08\u53D8\u66F4\u8DEF\u5F84 ${result.changedPaths.length} \u4E2A\uFF0C\u53D7\u5F71\u54CD\u8FB9 ${result.affectedEdges.length} \u6761\uFF09`,
+    `- \u5B9E\u73B0/\u9A8C\u8BC1\u9501: \u65B0\u589E ${result.addedLocks.length} | \u66F4\u65B0 ${result.updatedLocks.length} | \u4FDD\u7559\u5B64\u7ACB ${result.retainedOrphans.length} | \u5220\u9664\u5B64\u7ACB ${result.removedOrphans.length}`,
+    `- \u5236\u54C1\u5173\u7CFB\u9501: \u65B0\u589E ${result.addedArtifactRelationLocks.length} | \u66F4\u65B0 ${result.updatedArtifactRelationLocks.length} | \u4FDD\u7559\u5B64\u7ACB ${result.retainedArtifactRelationOrphans.length} | \u5220\u9664 ${result.removedArtifactRelationLocks.length}`,
+    `- \u963B\u65AD\u7B56\u7565: refresh \u56FA\u5B9A\u6309 --strict-missing-lock \u5224\u5B9A\uFF0Cmissing_lock \u4E5F\u4F1A\u963B\u65AD`,
+    `- \u5237\u65B0\u540E\u5BA1\u8BA1\u95EE\u9898: ${result.postAudit.issues.length}\uFF08\u963B\u65AD ${blockingCount}\uFF0C\u4E0D\u963B\u65AD ${nonBlockingCount}\uFF09`,
+    "",
+    "\u9501\u6587\u4EF6\u5DF2\u5199\u5165\u3002\u82E5\u9501\u6587\u4EF6\u76F8\u5BF9\u6682\u5B58\u533A\u6709\u53D8\u5316\uFF08\u4F8B\u5982 pre-commit \u573A\u666F\uFF09\uFF0C\u8BF7\u5148\u5BA1\u67E5\u5E76\u6682\u5B58\uFF1A",
     "",
-    `Root: \`${result.root}\``,
-    `Lock: \`${result.lockPath}\``,
-    `Mode: \`${result.mode}\``,
-    `Changed paths: ${result.changedPaths.length}`,
-    `Affected edges: ${result.affectedEdges.length}`,
-    `Added: ${result.addedLocks.length} | Updated: ${result.updatedLocks.length} | Retained orphans: ${result.retainedOrphans.length} | Removed orphans: ${result.removedOrphans.length}`,
-    `Artifact Relations \u2014 Added: ${result.addedArtifactRelationLocks.length} | Updated: ${result.updatedArtifactRelationLocks.length} | Retained orphans: ${result.retainedArtifactRelationOrphans.length} | Removed: ${result.removedArtifactRelationLocks.length}`,
-    `Post-audit issues: ${result.postAudit.issues.length}`,
+    "1. `git diff artifacts/traceability-version-lock.json`",
+    "2. `git add artifacts/traceability-version-lock.json`",
+    "3. \u91CD\u65B0\u6267\u884C `git commit`",
     ""
   ];
-  appendList(lines, "Added Locks", result.addedLocks);
-  appendList(lines, "Updated Locks", result.updatedLocks);
-  appendList(lines, "Retained Orphans", result.retainedOrphans);
-  appendList(lines, "Removed Orphans", result.removedOrphans);
-  appendList(lines, "Added Artifact Relation Locks", result.addedArtifactRelationLocks);
-  appendList(lines, "Updated Artifact Relation Locks", result.updatedArtifactRelationLocks);
-  appendList(lines, "Retained Artifact Relation Orphans", result.retainedArtifactRelationOrphans);
-  appendList(lines, "Removed Artifact Relation Locks", result.removedArtifactRelationLocks);
-  appendList(lines, "Warnings", result.warnings);
+  appendList(lines, "\u65B0\u589E\u7684\u9501", result.addedLocks);
+  appendList(lines, "\u66F4\u65B0\u7684\u9501", result.updatedLocks);
+  appendList(lines, "\u4FDD\u7559\u7684\u5B64\u7ACB\u9501", result.retainedOrphans);
+  if (result.retainedOrphans.length > 0) {
+    lines.push("> \u4EE5\u4E0A\u662F\u5DF2\u5220\u9664/\u62C6\u5206\u5236\u54C1\u6216\u5931\u6548\u8FFD\u6EAF\u8FB9\u9057\u7559\u7684\u9501\u3002\u786E\u8BA4\u4E0D\u518D\u9700\u8981\u540E\u8FD0\u884C `artifact-graph version-lock refresh --all --remove-orphans --format markdown` \u6E05\u7406\uFF0C\u5BA1\u67E5 `git diff artifacts/traceability-version-lock.json` \u540E\u518D\u6682\u5B58\u3002");
+    lines.push("");
+  }
+  appendList(lines, "\u5220\u9664\u7684\u5B64\u7ACB\u9501", result.removedOrphans);
+  appendList(lines, "\u65B0\u589E\u7684\u5236\u54C1\u5173\u7CFB\u9501", result.addedArtifactRelationLocks);
+  appendList(lines, "\u66F4\u65B0\u7684\u5236\u54C1\u5173\u7CFB\u9501", result.updatedArtifactRelationLocks);
+  appendList(lines, "\u4FDD\u7559\u7684\u5B64\u7ACB\u5236\u54C1\u5173\u7CFB\u9501", result.retainedArtifactRelationOrphans);
+  if (result.retainedArtifactRelationOrphans.length > 0) {
+    lines.push("> \u4EE5\u4E0A\u662F\u5931\u6548\u5236\u54C1\u5173\u7CFB\u9057\u7559\u7684\u9501\u3002\u786E\u8BA4\u540E\u8FD0\u884C `artifact-graph version-lock refresh --all --remove-orphans --format markdown` \u6E05\u7406\uFF0C\u5BA1\u67E5\u9501 diff \u540E\u518D\u6682\u5B58\u3002");
+    lines.push("");
+  }
+  appendList(lines, "\u5220\u9664\u7684\u5236\u54C1\u5173\u7CFB\u9501", result.removedArtifactRelationLocks);
+  appendList(lines, "\u63D0\u9192", result.warnings);
   if (result.postAudit.issues.length > 0) {
-    lines.push("## Post-Audit Issues");
-    for (const issue2 of result.postAudit.issues) {
-      lines.push(`- [${issue2.status}] \`${issue2.edgeId}\` \u2014 ${issue2.message}`);
+    if (blockingCount > 0) {
+      lines.push(`## \u5237\u65B0\u540E\u5BA1\u8BA1\u95EE\u9898\uFF08\u963B\u65AD ${blockingCount}\uFF0C\u4E0D\u963B\u65AD ${nonBlockingCount}\uFF09`);
+    } else {
+      lines.push(`## \u5237\u65B0\u540E\u5BA1\u8BA1\u95EE\u9898\uFF08\u5F53\u524D\u7B56\u7565\u4E0B\u5168\u90E8\u4E0D\u963B\u65AD\uFF09`);
     }
     lines.push("");
+    appendIssueDetails(lines, result.postAudit.issues, strictMissingLock);
   }
   return `${lines.join("\n")}
 `;
@@ -2474,7 +2611,7 @@ async function isFileActiveInRunner(root, filePath, runner) {
 function sortUnique(items) {
   return [...new Set(items)].sort((left, right) => left.localeCompare(right));
 }
-var VERSION_LOCK_PATH, VERSION_INDEX_SCHEMA_VERSION, VERSION_LOCK_SCHEMA_VERSION;
+var VERSION_LOCK_PATH, VERSION_INDEX_SCHEMA_VERSION, VERSION_LOCK_SCHEMA_VERSION, LIVENESS_MESSAGE_PREFIX, VERSION_LOCK_STATUS_LABELS;
 var init_versioned_traceability = __esm({
   "src/versioned-traceability.ts"() {
     "use strict";
@@ -2483,6 +2620,16 @@ var init_versioned_traceability = __esm({
     VERSION_LOCK_PATH = "artifacts/traceability-version-lock.json";
     VERSION_INDEX_SCHEMA_VERSION = "1.0";
     VERSION_LOCK_SCHEMA_VERSION = "1.0";
+    LIVENESS_MESSAGE_PREFIX = "Liveness:";
+    VERSION_LOCK_STATUS_LABELS = {
+      fresh: "\u65B0\u9C9C",
+      target_not_found: "\u76EE\u6807\u5236\u54C1\u4E0D\u5B58\u5728",
+      artifact_changed: "\u5236\u54C1\u5DF2\u53D8\u5316",
+      source_changed: "\u6E90\u7801/\u6D4B\u8BD5\u5DF2\u53D8\u5316",
+      verified_by_changed: "\u9A8C\u8BC1\u6587\u4EF6\u5DF2\u53D8\u5316",
+      missing_lock: "\u7F3A\u5C11\u7248\u672C\u9501",
+      orphan_lock: "\u5B64\u7ACB\u9501"
+    };
   }
 });
 
@@ -8343,6 +8490,7 @@ export {
   isPacketTargetType,
   isPacketTargetTypeDynamic,
   isTargetArtifactType,
+  isVersionLockIssueBlocking,
   loadConfig,
   loadContract,
   loadContractCatalog,
@@ -8383,5 +8531,6 @@ export {
   validateScenarioPrdLinkIndex,
   validateScenarioPrdLinks,
   verifyDigest,
+  versionLockIssueSeverity,
   writeGraphCache
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "artifact-graph",
-  "version": "0.8.3",
+  "version": "0.8.4",
   "description": "Git-native Markdown artifact graph scanner and validator",
   "license": "Apache-2.0",
   "type": "module",

package/templates/git-hooks/pre-commit.sh

@@ -37,7 +37,10 @@ else
 fi
 
 if ! git diff --quiet -- artifacts/traceability-version-lock.json; then
-  echo "artifact-chain-assistant: version lock changed during pre-commit." >&2
-  echo "Please review and stage artifacts/traceability-version-lock.json, then commit again." >&2
+  echo "artifact-chain-assistant: 版本锁刷新成功，但更新后的锁文件尚未进入本次提交。" >&2
+  echo "这不是校验失败，只需把新锁纳入提交：" >&2
+  echo "  1. 审查锁变更:  git diff artifacts/traceability-version-lock.json" >&2
+  echo "  2. 暂存锁文件:  git add artifacts/traceability-version-lock.json" >&2
+  echo "  3. 重新提交:    git commit" >&2
   exit 1
 fi