artifact-graph 0.4.1 → 0.5.0

package/dist/cli.js

@@ -4,15 +4,16 @@
 import yaml2 from "js-yaml";
 import { realpathSync } from "fs";
 import { access as access2, mkdir as mkdir6, readFile as readFile3, writeFile as writeFile5 } from "fs/promises";
-import { isAbsolute as isAbsolute3, join as join7 } from "path";
+import { isAbsolute as isAbsolute4, join as join7 } from "path";
 import { fileURLToPath } from "url";
 
 // src/index.ts
 import Database from "better-sqlite3";
 import matter from "gray-matter";
 import yaml from "js-yaml";
+import { accessSync, constants as fsConstants, statSync } from "fs";
 import { mkdir as mkdir4, readFile as readFile2, readdir, writeFile as writeFile3 } from "fs/promises";
-import { basename as basename2, dirname as dirname3, extname, join as join5, relative as relative2 } from "path";
+import { basename as basename2, dirname as dirname3, extname, isAbsolute as isAbsolute3, join as join5, relative as relative2, resolve as resolve3 } from "path";
 
 // src/packet-constants.ts
 var ALWAYS_PRESENT_ITEMS = [
@@ -91,13 +92,76 @@ function validatePacket(packet, schema) {
       path: "target.id"
     });
   }
-  if (packet.requiredBaseline.total !== BASELINE_ITEMS_COUNT) {
-    issues.push({
-      severity: "error",
-      code: "PKT-004",
-      message: `requiredBaseline.total must be ${BASELINE_ITEMS_COUNT}, got ${packet.requiredBaseline.total}`,
-      path: "requiredBaseline.total"
-    });
+  const isBaselineExplicitlyDisabled = packet.baselinePolicy === false;
+  const expectedPaths = new Set(ALWAYS_PRESENT_ITEMS.map((item) => item.path));
+  if (isBaselineExplicitlyDisabled) {
+    if (packet.requiredBaseline.total !== 0) {
+      issues.push({
+        severity: "error",
+        code: "PKT-004",
+        message: `baselinePolicy=false requires requiredBaseline.total=0, got ${packet.requiredBaseline.total}`,
+        path: "requiredBaseline.total"
+      });
+    }
+    if (packet.requiredBaseline.items.length !== 0) {
+      issues.push({
+        severity: "error",
+        code: "PKT-004",
+        message: `baselinePolicy=false requires requiredBaseline.items=[], got ${packet.requiredBaseline.items.length} item(s)`,
+        path: "requiredBaseline.items"
+      });
+    }
+  } else {
+    if (packet.requiredBaseline.total !== BASELINE_ITEMS_COUNT) {
+      issues.push({
+        severity: "error",
+        code: "PKT-004",
+        message: `requiredBaseline.total must be ${BASELINE_ITEMS_COUNT}, got ${packet.requiredBaseline.total}`,
+        path: "requiredBaseline.total"
+      });
+    }
+    if (packet.requiredBaseline.items.length !== BASELINE_ITEMS_COUNT) {
+      issues.push({
+        severity: "error",
+        code: "PKT-004",
+        message: `requiredBaseline.items.length must be ${BASELINE_ITEMS_COUNT}, got ${packet.requiredBaseline.items.length}`,
+        path: "requiredBaseline.items"
+      });
+    }
+    const actualPaths = packet.requiredBaseline.items.map((item) => item.path);
+    const actualPathSet = new Set(actualPaths);
+    if (actualPathSet.size !== actualPaths.length) {
+      issues.push({
+        severity: "error",
+        code: "PKT-004",
+        message: `requiredBaseline.items contains duplicate paths (${actualPaths.length} items, ${actualPathSet.size} unique)`,
+        path: "requiredBaseline.items"
+      });
+    }
+    const missingPaths = [];
+    for (const ep of expectedPaths) {
+      if (!actualPathSet.has(ep)) missingPaths.push(ep);
+    }
+    if (missingPaths.length > 0) {
+      issues.push({
+        severity: "error",
+        code: "PKT-004",
+        message: `requiredBaseline.items missing expected path(s): ${missingPaths.join(", ")}`,
+        path: "requiredBaseline.items"
+      });
+    }
+    const extraPaths = [];
+    for (const ap of actualPathSet) {
+      if (!expectedPaths.has(ap)) extraPaths.push(ap);
+    }
+    if (extraPaths.length > 0) {
+      issues.push({
+        severity: "error",
+        code: "PKT-004",
+        message: `requiredBaseline.items contains unexpected path(s): ${extraPaths.join(", ")}`,
+        path: "requiredBaseline.items"
+      });
+    }
   }
   const constraints = packet.implementationBlueprintDraft.constraints;
   if (constraints.length !== BASELINE_CONSTRAINTS_COUNT) {
@@ -499,7 +563,10 @@ function assemblePacket(manifest, options) {
     missing: [...manifest.missing],
     missingDetails: manifest.missingDetails ? [...manifest.missingDetails] : void 0,
     implementationBlueprintDraft: blueprintDraft,
-    validationCommands
+    validationCommands,
+    // @feature ACA17
+    // @decision D-ACA-17
+    baselinePolicy: manifest.baselinePolicy
   };
   return packet;
 }
@@ -720,7 +787,9 @@ async function auditSingleTarget(target, graph, options) {
     const manifest = resolveArtifactContext(graph, {
       target: { type: target.type, id: target.id },
       mode: options.mode,
-      maxPerCategory: options.maxPerCategory
+      maxPerCategory: options.maxPerCategory,
+      universalBaseline: options.universalBaseline,
+      root: options.root
     });
     const packet = assemblePacket(manifest, {
       mode: options.mode,
@@ -857,6 +926,7 @@ async function discoverAndAuditPackets(root, options) {
     type: d.type,
     id: d.id
   }));
+  const effectiveBaseline = options.universalBaseline ?? config.context?.universal_baseline;
   return auditPackets(root, targets, {
     root,
     outDir: options.outDir,
@@ -866,7 +936,8 @@ async function discoverAndAuditPackets(root, options) {
     summaryOnly: options.summaryOnly,
     sampleTargets: options.sampleTargets,
     summaryDetail: options.summaryDetail,
-    schema: config
+    schema: config,
+    universalBaseline: effectiveBaseline
   }, graph);
 }
 
@@ -2577,12 +2648,35 @@ var VALID_DECISIONS = /* @__PURE__ */ new Set([
 var VALID_SEVERITIES = /* @__PURE__ */ new Set(["block", "warn", "info"]);
 var VALID_FINDING_STATUSES = /* @__PURE__ */ new Set(["open", "resolved", "accepted", "superseded"]);
 var VALID_EXECUTORS = /* @__PURE__ */ new Set(["script", "worker", "agent", "manual", "cli"]);
+var TOP_LEVEL_FIELDS = /* @__PURE__ */ new Set([
+  "schema_version",
+  "run_id",
+  "stage_id",
+  "attempt",
+  "status",
+  "decision",
+  "summary",
+  "outputs",
+  "warnings",
+  "blocking_reason",
+  "degradation",
+  "producer",
+  "acceptance",
+  "evidence",
+  "review",
+  "repair"
+]);
 function validateReviewResult(input) {
   const errors = [];
   if (!input || typeof input !== "object" || Array.isArray(input)) {
     return [{ path: "$", message: "Root must be a non-null object" }];
   }
   const obj = input;
+  for (const key of Object.keys(obj)) {
+    if (!TOP_LEVEL_FIELDS.has(key)) {
+      errors.push({ path: `$.${key}`, message: "Unknown top-level property" });
+    }
+  }
   if (obj.schema_version !== "1.0") {
     errors.push({ path: "$.schema_version", message: `Must be "1.0", got ${JSON.stringify(obj.schema_version)}` });
   }
@@ -2601,8 +2695,8 @@ function validateReviewResult(input) {
   if (obj.stage_id !== void 0 && typeof obj.stage_id !== "string") {
     errors.push({ path: "$.stage_id", message: "Must be a string if present" });
   }
-  if (obj.attempt !== void 0 && (!Number.isInteger(obj.attempt) || obj.attempt < 1)) {
-    errors.push({ path: "$.attempt", message: "Must be a positive integer if present" });
+  if (obj.attempt !== void 0 && (!Number.isInteger(obj.attempt) || obj.attempt < 1 || obj.attempt > 3)) {
+    errors.push({ path: "$.attempt", message: "Must be an integer from 1 through 3 if present" });
   }
   if (obj.outputs !== void 0) {
     checkStringArray(obj.outputs, "$.outputs", errors);
@@ -2613,20 +2707,14 @@ function validateReviewResult(input) {
   checkOptionalNullableString(obj.blocking_reason, "$.blocking_reason", errors);
   checkOptionalNullableString(obj.degradation, "$.degradation", errors);
   if (obj.producer !== void 0) {
-    if (!isPlainObject(obj.producer)) {
-      errors.push({ path: "$.producer", message: "Must be an object" });
-    } else {
-      const p = obj.producer;
-      if (typeof p.executor !== "string") {
-        errors.push({ path: "$.producer.executor", message: "Must be a string" });
-      } else if (!VALID_EXECUTORS.has(p.executor)) {
-        errors.push({ path: "$.producer.executor", message: `Must be one of ${[...VALID_EXECUTORS].join(", ")}; got ${JSON.stringify(p.executor)}` });
-      }
-      if (typeof p.name !== "string") {
-        errors.push({ path: "$.producer.name", message: "Must be a string" });
-      }
-      checkOptionalString(p.skill, "$.producer.skill", errors);
-    }
+    validateProducer(obj.producer, "$.producer", errors);
+  }
+  const successfulAcceptance = obj.status === "SUCCEEDED" && (obj.decision === "PASS" || obj.decision === "PASS_WITH_RESIDUAL_MINOR");
+  if (successfulAcceptance && obj.producer === void 0) {
+    errors.push({ path: "$.producer", message: "Successful acceptance requires producer identity" });
+  }
+  if (obj.acceptance !== void 0) {
+    validateAcceptance(obj.acceptance, obj.producer, "$.acceptance", errors);
   }
   if (obj.evidence !== void 0) {
     if (!Array.isArray(obj.evidence)) {
@@ -2652,6 +2740,17 @@ function validateReviewResult(input) {
   }
   if (obj.review !== void 0) {
     validateReviewData(obj.review, "$.review", errors);
+    if (obj.decision === "PASS" || obj.decision === "PASS_WITH_RESIDUAL_MINOR") {
+      const findings = isPlainObject(obj.review) && Array.isArray(obj.review.findings) ? obj.review.findings : [];
+      findings.forEach((finding, index) => {
+        if (isPlainObject(finding) && finding.severity === "block" && (finding.status === void 0 || finding.status === "open")) {
+          errors.push({
+            path: `$.review.findings[${index}]`,
+            message: `${obj.decision} cannot contain an open block finding`
+          });
+        }
+      });
+    }
   }
   if (obj.repair !== void 0) {
     if (!isPlainObject(obj.repair)) {
@@ -2687,6 +2786,47 @@ function checkStringArray(val, path, errors) {
 function isPlainObject(val) {
   return typeof val === "object" && val !== null && !Array.isArray(val);
 }
+function validateProducer(val, path, errors) {
+  if (!isPlainObject(val)) {
+    errors.push({ path, message: "Must be an object" });
+    return;
+  }
+  if (typeof val.executor !== "string") {
+    errors.push({ path: `${path}.executor`, message: "Must be a string" });
+  } else if (!VALID_EXECUTORS.has(val.executor)) {
+    errors.push({ path: `${path}.executor`, message: `Must be one of ${[...VALID_EXECUTORS].join(", ")}; got ${JSON.stringify(val.executor)}` });
+  }
+  if (typeof val.name !== "string" || val.name.length === 0) {
+    errors.push({ path: `${path}.name`, message: "Must be a non-empty string" });
+  }
+  checkOptionalString(val.skill, `${path}.skill`, errors);
+}
+function producerIdentity(val) {
+  return JSON.stringify([val.executor, val.name]);
+}
+function validateAcceptance(val, resultProducer, path, errors) {
+  if (!isPlainObject(val)) {
+    errors.push({ path, message: "Must be an object" });
+    return;
+  }
+  validateProducer(val.reviewer, `${path}.reviewer`, errors);
+  if (!isPlainObject(val.source_result)) {
+    errors.push({ path: `${path}.source_result`, message: "Must be an object" });
+    return;
+  }
+  const source = val.source_result;
+  if (typeof source.run_id !== "string" || source.run_id.length === 0) {
+    errors.push({ path: `${path}.source_result.run_id`, message: "Must be a non-empty string" });
+  }
+  checkOptionalString(source.stage_id, `${path}.source_result.stage_id`, errors);
+  validateProducer(source.producer, `${path}.source_result.producer`, errors);
+  if (isPlainObject(val.reviewer) && isPlainObject(resultProducer) && producerIdentity(val.reviewer) !== producerIdentity(resultProducer)) {
+    errors.push({ path: `${path}.reviewer`, message: "Acceptance reviewer must match the result producer" });
+  }
+  if (isPlainObject(val.reviewer) && isPlainObject(source.producer) && producerIdentity(val.reviewer) === producerIdentity(source.producer)) {
+    errors.push({ path: `${path}.reviewer`, message: "Repair producer cannot accept its own result" });
+  }
+}
 function checkOptionalString(val, path, errors) {
   if (val !== void 0 && typeof val !== "string") {
     errors.push({ path, message: "Must be a string if present" });
@@ -2855,7 +2995,7 @@ var DEFAULT_SCHEMA = {
     scenario: { paths: ["artifacts/scenarios/**/*.md"], displayName: "\u573A\u666F\u5267\u672C", role: "scenario", layer: "scenario", aliases: ["scenarios", "scenario-script"] },
     design: { paths: ["artifacts/design/**/*.md"], displayName: "\u8BBE\u8BA1\u89C4\u683C", role: "design", layer: "design", aliases: ["design-spec", "design_docs"] },
     test: { paths: ["heimdall/packages/**/*.test.ts"], displayName: "\u4EE3\u7801\u6CE8\u91CA\u8FFD\u6EAF", role: "context", layer: "implementation", aliases: ["code-test", "code-trace", "unit-test"] },
-    e2e_test: { paths: ["artifacts/tests/e2e/*.md"], displayName: "E2E \u6D4B\u8BD5\u89C4\u683C", role: "e2e_test", layer: "verification", aliases: ["e2e-test", "e2e_tests"] },
+    e2e_test: { paths: ["artifacts/tests/e2e/*.md"], displayName: "E2E \u6D4B\u8BD5\u89C4\u683C", role: "e2e_test", layer: "verification", aliases: ["e2e-test", "e2e_tests", "tc"] },
     e2e_registry: { paths: ["artifacts/tests/e2e/e2e-test-registry.json"], displayName: "E2E \u6D4B\u8BD5\u6CE8\u518C\u8868", role: "context", layer: "verification", aliases: ["e2e-registry"] },
     "rule-golden-cases": { paths: ["artifacts/tests/rule-golden-cases.md"], displayName: "\u89C4\u5219\u9EC4\u91D1\u6D4B\u8BD5\u7528\u4F8B", role: "context", layer: "verification", aliases: ["rule_golden_cases"] },
     "test-strategy": { paths: ["artifacts/design/test-strategy.md"], displayName: "\u6D4B\u8BD5\u7B56\u7565", role: "context", layer: "verification", aliases: ["test_strategy"] },
@@ -2898,6 +3038,12 @@ async function loadConfig(root) {
       throw error;
     }
   }
+  const ub = parsed.context?.universal_baseline;
+  if (ub !== void 0 && typeof ub !== "boolean") {
+    throw new Error(
+      `Invalid context.universal_baseline: ${JSON.stringify(ub)}. Must be boolean (true or false).`
+    );
+  }
   return {
     ...DEFAULT_SCHEMA,
     ...parsed,
@@ -2910,7 +3056,7 @@ async function loadConfig(root) {
     idRanges: mergeRecord(DEFAULT_SCHEMA.idRanges, parsed.idRanges)
   };
 }
-function buildGraph(nodes, edges, diagnostics = []) {
+function buildGraph(nodes, edges, diagnostics = [], root) {
   const graphNodes = nodes.map((node) => ({ ...node, uid: toUid(node.type, node.code) }));
   graphNodes.sort(compareNode);
   edges.sort(compareEdge);
@@ -2927,6 +3073,7 @@ function buildGraph(nodes, edges, diagnostics = []) {
     nodes: graphNodes,
     edges: dedupedEdges,
     generatedAt: (/* @__PURE__ */ new Date(0)).toISOString(),
+    ...root ? { root } : {},
     diagnostics: diagnostics.sort((left, right) => left.code.localeCompare(right.code) || left.path.localeCompare(right.path) || left.line - right.line)
   };
 }
@@ -2958,7 +3105,8 @@ async function scanArtifacts(root, schema) {
       scanDiagnostics.push(...parsed.diagnostics);
     }
   }
-  const graph = buildGraph(nodes, edges, scanDiagnostics);
+  const absoluteRoot = isAbsolute3(root) ? root : resolve3(root);
+  const graph = buildGraph(nodes, edges, scanDiagnostics, absoluteRoot);
   return resolveMatrixEdges(graph);
 }
 function artifactTypeEntriesBySpecificity(schema) {
@@ -3298,23 +3446,34 @@ async function validateScenarioPrdLinkIndex(root, graph) {
 function validateCodeCommentTraceabilityFormat(graph) {
   const issues = [];
   for (const node of graph.nodes) {
-    if (node.type !== "test") {
+    if (node.type !== "test" && node.type !== "implementation") {
       continue;
     }
     const invalidComments = node.attrs?.invalidTraceabilityComments;
-    if (!Array.isArray(invalidComments)) {
-      continue;
+    if (Array.isArray(invalidComments)) {
+      for (const invalid of invalidComments) {
+        const line = typeof invalid?.line === "number" ? invalid.line : node.line;
+        const reason = typeof invalid?.reason === "string" ? invalid.reason : "traceability tags must use standalone // comments";
+        issues.push(issue(
+          "CODE_COMMENT_TRACEABILITY_FORMAT",
+          `${reason}: ${typeof invalid?.text === "string" ? invalid.text : ""}`.trim(),
+          node.path,
+          line,
+          { node: node.uid }
+        ));
+      }
     }
-    for (const invalid of invalidComments) {
-      const line = typeof invalid?.line === "number" ? invalid.line : node.line;
-      const reason = typeof invalid?.reason === "string" ? invalid.reason : "traceability tags must use standalone // comments";
-      issues.push(issue(
-        "CODE_COMMENT_TRACEABILITY_FORMAT",
-        `${reason}: ${typeof invalid?.text === "string" ? invalid.text : ""}`.trim(),
-        node.path,
-        line,
-        { node: node.uid }
-      ));
+    const deprecatedComments = node.attrs?.deprecatedTraceabilityComments;
+    if (Array.isArray(deprecatedComments)) {
+      for (const deprecated of deprecatedComments) {
+        issues.push(issue(
+          "E2E-TRACE-007",
+          "@tc is deprecated; use @e2e_test instead",
+          node.path,
+          typeof deprecated?.line === "number" ? deprecated.line : node.line,
+          { node: node.uid, severity: "warning" }
+        ));
+      }
     }
   }
   return issues;
@@ -3796,13 +3955,16 @@ function parseTest(path, raw, schema = DEFAULT_SCHEMA) {
   const isTest = isTestFile(path);
   const nodeType = isTest ? "test" : "implementation";
   const edgeKind = isTest ? "verifies" : "implements";
+  const attrs = {};
+  if (traceabilityComments.invalid.length > 0) attrs.invalidTraceabilityComments = traceabilityComments.invalid;
+  if (traceabilityComments.deprecated.length > 0) attrs.deprecatedTraceabilityComments = traceabilityComments.deprecated;
   const node = {
     type: nodeType,
     code: path,
     title: path.split("/").at(-1) ?? path,
     path,
     line: 1,
-    attrs: traceabilityComments.invalid.length > 0 ? { invalidTraceabilityComments: traceabilityComments.invalid } : {}
+    attrs
   };
   let hasTags = false;
   for (const { tags, lineNumber } of traceabilityComments.canonical) {
@@ -3813,7 +3975,7 @@ function parseTest(path, raw, schema = DEFAULT_SCHEMA) {
       }
     }
   }
-  if (hasTags || traceabilityComments.invalid.length > 0) {
+  if (hasTags || traceabilityComments.invalid.length > 0 || traceabilityComments.deprecated.length > 0) {
     nodes.push(node);
   }
   return { nodes, edges };
@@ -3821,6 +3983,7 @@ function parseTest(path, raw, schema = DEFAULT_SCHEMA) {
 function scanTraceabilityComments(raw, schema = DEFAULT_SCHEMA) {
   const canonical = [];
   const invalid = [];
+  const deprecated = [];
   for (const comment of scanCodeComments(raw)) {
     if (!containsTraceabilityTag(comment.text, schema)) {
       continue;
@@ -3836,6 +3999,9 @@ function scanTraceabilityComments(raw, schema = DEFAULT_SCHEMA) {
     const parsed = parseTraceabilityTagLine(comment.text.trim(), schema);
     if (parsed.valid) {
       canonical.push({ tags: parsed.tags, lineNumber: comment.lineNumber });
+      if (/(?:^|\s)@tc(?=\s|$)/.test(comment.text.trim())) {
+        deprecated.push({ line: comment.lineNumber, text: comment.text.trim() });
+      }
     } else {
       invalid.push({ line: comment.lineNumber, text: comment.text.trim(), reason: parsed.reason });
     }
@@ -3851,11 +4017,14 @@ function scanTraceabilityComments(raw, schema = DEFAULT_SCHEMA) {
     const parsed = parseTraceabilityTagLine(comment.text.trim(), schema);
     if (parsed.valid) {
       canonical.push({ tags: parsed.tags, lineNumber: comment.lineNumber });
+      if (/(?:^|\s)@tc(?=\s|$)/.test(comment.text.trim())) {
+        deprecated.push({ line: comment.lineNumber, text: comment.text.trim() });
+      }
     } else {
       invalid.push({ line: comment.lineNumber, text: comment.text.trim(), reason: parsed.reason });
     }
   }
-  return { canonical, invalid };
+  return { canonical, invalid, deprecated };
 }
 function scanCodeComments(raw) {
   const comments = [];
@@ -4022,7 +4191,14 @@ function expandCodeRange(value) {
   return Array.from({ length: end - start + 1 }, (_, index) => `${prefix}${String(start + index).padStart(width, "0")}`);
 }
 function containsTraceabilityTag(value, schema = DEFAULT_SCHEMA) {
-  return /@[\w][\w-]*\b/.test(value);
+  const tokens = /* @__PURE__ */ new Set();
+  for (const [type, definition] of Object.entries(schema.types)) {
+    tokens.add(type);
+    for (const alias of definition.aliases ?? []) tokens.add(alias);
+  }
+  if (tokens.size === 0) return false;
+  const alternatives = [...tokens].sort((a, b) => b.length - a.length).map((token) => token.replace(/[-\/\\^$*+?.()|[\]{}]/g, "\\$&")).join("|");
+  return new RegExp(`(?:^|\\s)@(?:${alternatives})(?=\\s|$)`).test(value);
 }
 function parseDesign(path, raw) {
   const parsed = matter(raw);
@@ -5139,8 +5315,8 @@ async function validateExecutableTraceability(root) {
     }
   }
   const refToSource = /* @__PURE__ */ new Map();
-  const tcAnnotationRegex = /\/\/!?\s*@tc\s+(\S+?)\s+\[(\w+)\]/;
-  const tcAnnotationNoLevelRegex = /\/\/!?\s*@tc\s+(\S+)/;
+  const tcAnnotationRegex = /\/\/!?\s*@(?:e2e_test|tc)\s+(\S+?)\s+\[(\w+)\]/;
+  const tcAnnotationNoLevelRegex = /\/\/!?\s*@(?:e2e_test|tc)\s+(\S+)/;
   for (const specFile of specFiles) {
     const fullSpecPath = join5(root, specFile);
     let content;
@@ -5229,7 +5405,7 @@ async function validateExecutableTraceability(root) {
         return normalizedAnnFile === normalizedRefFile;
       }) ?? false;
       if (!hasAnnotationInFile) {
-        issues.push(issue("E2E-TRACE-003", `executable_ref target ${entry.file} has no // @tc ${tcKey} line-comment annotation`, path, line, { node: tcKey, severity: "warning" }));
+        issues.push(issue("E2E-TRACE-003", `executable_ref target ${entry.file} has no E2E trace annotation ${tcKey}`, path, line, { node: tcKey, severity: "warning" }));
         continue;
       }
       validFiles.push(normalizedRefFile);
@@ -5240,13 +5416,13 @@ async function validateExecutableTraceability(root) {
     const batch = tcKey.split(":")[0];
     if (!mdBatches.has(batch)) {
       for (const ann of annotations) {
-        issues.push(issue("E2E-TRACE-002", `@tc annotation ${tcKey} references non-existent E2E batch "${batch}"`, ann.file, ann.line, { node: tcKey, severity: "warning" }));
+        issues.push(issue("E2E-TRACE-002", `E2E trace annotation ${tcKey} references non-existent E2E batch "${batch}"`, ann.file, ann.line, { node: tcKey, severity: "warning" }));
       }
       continue;
     }
     if (!mdToRef.has(tcKey) && !await hasMarkdownTc(tcKey, e2eDir)) {
       for (const ann of annotations) {
-        issues.push(issue("E2E-TRACE-002", `@tc annotation ${tcKey} references non-existent Markdown TC`, ann.file, ann.line, { node: tcKey, severity: "warning" }));
+        issues.push(issue("E2E-TRACE-002", `E2E trace annotation ${tcKey} references non-existent Markdown TC`, ann.file, ann.line, { node: tcKey, severity: "warning" }));
       }
     }
   }
@@ -5268,7 +5444,7 @@ async function validateExecutableTraceability(root) {
       const primaryRef = refEntries[0];
       const normalizedPrimary = primaryRef?.file.startsWith("heimdall/") ? primaryRef?.file : `heimdall/${primaryRef?.file ?? ""}`;
       const detail = `file: MD refs=[${refEntries.map((e) => e.file).join(", ")}] vs source=${ann.file}`;
-      issues.push(issue("E2E-TRACE-003", `executable_ref \u2194 @tc mismatch for ${tcKey}: ${detail}`, path, line, { node: tcKey, severity: "warning" }));
+      issues.push(issue("E2E-TRACE-003", `executable_ref \u2194 E2E trace annotation mismatch for ${tcKey}: ${detail}`, path, line, { node: tcKey, severity: "warning" }));
     }
   }
   for (const [tcKey, { chainType, path, line }] of mdToRef) {
@@ -5434,14 +5610,14 @@ async function validatePartialRustEvidence(tcFields, tcKey, root) {
       return { hasValidPartialRust: false, detail: `partial_rust file not found: ${ref.file}` };
     }
     const tcAnnotationPattern = new RegExp(
-      `//[/!]?\\s*@tc\\s+${escapeRegExp(tcKey)}\\s+\\[partial_rust\\]`
+      `//[/!]?\\s*@(?:e2e_test|tc)\\s+${escapeRegExp(tcKey)}\\s+\\[partial_rust\\]`
     );
     if (!tcAnnotationPattern.test(content)) {
-      const noLevelPattern = new RegExp(`//[/!]?\\s*@tc\\s+${escapeRegExp(tcKey)}\\b`);
+      const noLevelPattern = new RegExp(`//[/!]?\\s*@(?:e2e_test|tc)\\s+${escapeRegExp(tcKey)}\\b`);
       if (noLevelPattern.test(content)) {
-        return { hasValidPartialRust: false, detail: `partial_rust file ${ref.file} has @tc ${tcKey} but not tagged [partial_rust]` };
+        return { hasValidPartialRust: false, detail: `partial_rust file ${ref.file} has E2E trace annotation ${tcKey} but not tagged [partial_rust]` };
       }
-      return { hasValidPartialRust: false, detail: `partial_rust file ${ref.file} has no @tc ${tcKey} annotation` };
+      return { hasValidPartialRust: false, detail: `partial_rust file ${ref.file} has no E2E trace annotation ${tcKey}` };
     }
   }
   return { hasValidPartialRust: true, detail: "ok" };
@@ -5768,9 +5944,14 @@ function mergeRecord(base, override) {
 function mergeArtifactTypes(base, override) {
   const result = { ...base };
   for (const [type, definition] of Object.entries(override ?? {})) {
+    const aliases = [
+      ...base[type]?.aliases ?? [],
+      ...definition.aliases ?? []
+    ].filter((alias, index, all) => all.indexOf(alias) === index);
     result[type] = {
       ...base[type] ?? {},
-      ...definition
+      ...definition,
+      ...aliases.length > 0 ? { aliases } : {}
     };
   }
   return result;
@@ -5864,6 +6045,8 @@ var TIER_ORDER = ["baseline", "target", "direct", "matrix", "transitive"];
 function resolveArtifactContext(graph, opts) {
   const mode = opts.mode ?? "full";
   const maxPerCategory = opts.maxPerCategory ?? 20;
+  const universalBaseline = opts.universalBaseline ?? true;
+  const root = opts.root ?? graph.root;
   const legacyCount = [opts.feature, opts.scenario, opts.decision, opts.design, opts.e2e_test].filter(Boolean).length;
   if (opts.target && legacyCount > 0) {
     return {
@@ -6016,12 +6199,80 @@ function resolveArtifactContext(graph, opts) {
     return "direct";
   }
   const pathMap = /* @__PURE__ */ new Map();
-  for (const ap of ALWAYS_PRESENT_ITEMS) {
-    const existing = pathMap.get(ap.path);
-    if (existing) {
-      if (!existing.reasons.includes(ap.reason)) existing.reasons.push(ap.reason);
+  if (universalBaseline) {
+    for (const ap of ALWAYS_PRESENT_ITEMS) {
+      const existing = pathMap.get(ap.path);
+      if (existing) {
+        if (!existing.reasons.includes(ap.reason)) existing.reasons.push(ap.reason);
+      } else {
+        pathMap.set(ap.path, { path: ap.path, reasons: [ap.reason], category: "baseline", required: true, tier: "baseline" });
+      }
+    }
+    if (root) {
+      for (const ap of ALWAYS_PRESENT_ITEMS) {
+        const fullPath = join5(root, ap.path);
+        let stat;
+        try {
+          stat = statSync(fullPath);
+        } catch {
+          stat = null;
+        }
+        if (!stat) {
+          const msg = `Required baseline artifact not found: ${ap.path}`;
+          if (!missing.includes(msg)) {
+            missing.push(msg);
+            missingDetails.push({
+              ref: ap.path,
+              from: "baseline",
+              kind: "missing-baseline",
+              message: msg,
+              suggestedAction: `\u521B\u5EFA\u6587\u4EF6 ${ap.path} \u6216\u914D\u7F6E\u8DF3\u8FC7 universal baseline`
+            });
+          }
+        } else if (!stat.isFile()) {
+          const msg = `Required baseline artifact is not a regular file: ${ap.path}`;
+          if (!missing.includes(msg)) {
+            missing.push(msg);
+            missingDetails.push({
+              ref: ap.path,
+              from: "baseline",
+              kind: "missing-baseline",
+              message: msg,
+              suggestedAction: `\u5C06 ${ap.path} \u4ECE\u76EE\u5F55\u6539\u4E3A\u6587\u4EF6\uFF0C\u6216\u914D\u7F6E\u8DF3\u8FC7 universal baseline`
+            });
+          }
+        } else {
+          try {
+            accessSync(fullPath, fsConstants.R_OK);
+          } catch {
+            const msg = `Required baseline artifact is not readable: ${ap.path}`;
+            if (!missing.includes(msg)) {
+              missing.push(msg);
+              missingDetails.push({
+                ref: ap.path,
+                from: "baseline",
+                kind: "missing-baseline",
+                message: msg,
+                suggestedAction: `\u4FEE\u590D ${ap.path} \u7684\u6587\u4EF6\u6743\u9650\uFF0C\u6216\u914D\u7F6E\u8DF3\u8FC7 universal baseline`
+              });
+            }
+          }
+        }
+      }
     } else {
-      pathMap.set(ap.path, { path: ap.path, reasons: [ap.reason], category: "baseline", required: true, tier: "baseline" });
+      for (const ap of ALWAYS_PRESENT_ITEMS) {
+        const msg = `Cannot verify baseline without root: ${ap.path}`;
+        if (!missing.includes(msg)) {
+          missing.push(msg);
+          missingDetails.push({
+            ref: ap.path,
+            from: "baseline",
+            kind: "missing-baseline",
+            message: msg,
+            suggestedAction: `\u4F20\u9012 root \u53C2\u6570\u6216\u914D\u7F6E\u8DF3\u8FC7 universal baseline`
+          });
+        }
+      }
     }
   }
   pathMap.set(targetNode.path, {
@@ -6122,7 +6373,8 @@ function resolveArtifactContext(graph, opts) {
     context,
     missing,
     missingDetails,
-    omitted
+    omitted,
+    baselinePolicy: universalBaseline
   };
 }
 function formatContextMarkdown(manifest) {
@@ -6206,7 +6458,9 @@ async function auditSinglePromptTarget(target, graph, options) {
   try {
     const manifest = resolveArtifactContext(graph, {
       target: { type: target.type, id: target.id },
-      mode: "implementation"
+      mode: "implementation",
+      root: options.root,
+      universalBaseline: options.universalBaseline
     });
     if (manifest.missing.length > 0) {
       entry.ok = false;
@@ -6362,13 +6616,15 @@ async function discoverAndAuditPromptBatch(root, options) {
     type: d.type,
     id: d.id
   }));
+  const effectiveBaseline = options.universalBaseline ?? config.context?.universal_baseline;
   return auditPromptBatch(root, targets, {
     root,
     outDir: options.outDir,
     format: options.format,
     maxChars: options.maxChars,
     summaryOnly: options.summaryOnly,
-    summaryDetail: options.summaryDetail
+    summaryDetail: options.summaryDetail,
+    universalBaseline: effectiveBaseline
   }, graph);
 }
 
@@ -6380,7 +6636,8 @@ async function runCli(argv, io = {}) {
   const err = io.stderr ?? ((chunk) => process.stderr.write(chunk));
   const root = String(parsed.flags.root ?? cwd);
   try {
-    if (parsed.command === "--help" || parsed.command === "-h" || parsed.command === "help") {
+    const hasHelpFlag = parsed.flags.help === true || parsed.positional.some((p) => p === "--help" || p === "-h");
+    if (parsed.command === "--help" || parsed.command === "-h" || parsed.command === "help" || hasHelpFlag) {
       out(helpText());
       return 0;
     }
@@ -6487,7 +6744,9 @@ async function runCli(argv, io = {}) {
         const manifest = resolveArtifactContext(graph, {
           target: resolvedTarget,
           mode: contextMode,
-          maxPerCategory
+          maxPerCategory,
+          universalBaseline: config.context?.universal_baseline,
+          root
         });
         if (parsed.flags.format === "json") {
           out(`${JSON.stringify(manifest, null, 2)}
@@ -6528,7 +6787,9 @@ async function runCli(argv, io = {}) {
         const manifest = resolveArtifactContext(graph, {
           target: resolvedTarget,
           mode: packetMode,
-          maxPerCategory: packetMaxPerCategory
+          maxPerCategory: packetMaxPerCategory,
+          universalBaseline: config.context?.universal_baseline,
+          root
         });
         if (manifest.missing.length > 0) {
           err("Missing artifacts detected \u2014 cannot generate packet:\n");
@@ -6657,7 +6918,9 @@ async function runCli(argv, io = {}) {
           const graph = await scanArtifacts(root);
           const promptManifest = resolveArtifactContext(graph, {
             target: resolvedTarget,
-            mode: "implementation"
+            mode: "implementation",
+            universalBaseline: config.context?.universal_baseline,
+            root
           });
           if (promptManifest.missing.length > 0) {
             err("Missing artifacts detected \u2014 cannot generate prompt:\n");
@@ -6797,6 +7060,7 @@ async function runCli(argv, io = {}) {
         }
         let summary;
         if (discover) {
+          const discoverConfig = await loadConfig(root);
           summary = await discoverAndAuditPackets(root, {
             root,
             outDir: auditOutDir,
@@ -6806,7 +7070,8 @@ async function runCli(argv, io = {}) {
             limit: limit === 0 ? Infinity : limit,
             summaryOnly,
             sampleTargets,
-            summaryDetail
+            summaryDetail,
+            universalBaseline: discoverConfig.context?.universal_baseline
           });
         } else {
           const targetsContent = await readFile3(targetsFile, "utf-8");
@@ -6834,7 +7099,8 @@ async function runCli(argv, io = {}) {
             summaryOnly,
             sampleTargets,
             summaryDetail,
-            schema: auditConfig2
+            schema: auditConfig2,
+            universalBaseline: auditConfig2.context?.universal_baseline
           });
         }
         if (parsed.flags.format === "json") {
@@ -6914,6 +7180,7 @@ async function runCli(argv, io = {}) {
         }
         let ppaSummary;
         if (ppaDiscover) {
+          const ppaDiscoverConfig = await loadConfig(root);
           ppaSummary = await discoverAndAuditPromptBatch(root, {
             root,
             outDir: ppaOutDir,
@@ -6921,7 +7188,8 @@ async function runCli(argv, io = {}) {
             maxChars: ppaMaxChars,
             limit: ppaLimit === 0 ? Infinity : ppaLimit,
             summaryOnly: ppaSummaryOnly,
-            summaryDetail: ppaSummaryDetail
+            summaryDetail: ppaSummaryDetail,
+            universalBaseline: ppaDiscoverConfig.context?.universal_baseline
           });
           if (ppaSummary.total === 0) {
             err(`\u9519\u8BEF\uFF1Adiscover \u6A21\u5F0F\u5728 ${root} \u4E2D\u672A\u627E\u5230\u4EFB\u4F55 target\u3002\u8BF7\u786E\u8BA4\u8FD9\u662F\u4E00\u4E2A\u6709\u6548\u7684 artifact root\u3002
@@ -6963,7 +7231,8 @@ async function runCli(argv, io = {}) {
             maxChars: ppaMaxChars,
             sourceTargetsPath: ppaTargetsFile,
             summaryOnly: ppaSummaryOnly,
-            summaryDetail: ppaSummaryDetail
+            summaryDetail: ppaSummaryDetail,
+            universalBaseline: ppaConfig.context?.universal_baseline
           });
         }
         if (ppaFormat === "json") {
@@ -7076,6 +7345,10 @@ async function runCli(argv, io = {}) {
             err("Usage: artifact-graph version-lock refresh (--all | --changed-only (--staged | --worktree | --base <ref>)) [--remove-orphans] [--format json|markdown] [--lock-path <path>]\n");
             return 1;
           }
+          if (parsed.flags.help === true) {
+            out("Usage: artifact-graph version-lock refresh (--all | --changed-only (--staged | --worktree | --base <ref>)) [--remove-orphans] [--format json|markdown] [--lock-path <path>]\n");
+            return 0;
+          }
           if (refreshAll && refreshChangedOnly) {
             err("Error: --all and --changed-only are mutually exclusive\n");
             return 1;
@@ -7213,7 +7486,7 @@ async function runCli(argv, io = {}) {
           err("Usage: artifact-graph validate-review-result --file <path> [--format json]\n");
           return 1;
         }
-        const resolvedPath = isAbsolute3(filePath) ? filePath : join7(root, filePath);
+        const resolvedPath = isAbsolute4(filePath) ? filePath : join7(root, filePath);
         let content;
         try {
           content = await readFile3(resolvedPath, "utf-8");
@@ -7284,12 +7557,18 @@ function parseArgs(argv) {
     if (token.startsWith("--")) {
       const key = token.slice(2);
       const next = rest[index + 1];
-      if (next && !next.startsWith("--")) {
+      const nextLooksLikeFlag = next && next.startsWith("-") && next.length > 1 && !/\d/.test(next[1]);
+      if (next && !nextLooksLikeFlag) {
         flags[key] = next;
         index += 1;
       } else {
         flags[key] = true;
       }
+    } else if (token === "-h") {
+      flags.help = true;
+    } else if (token.startsWith("-") && token.length > 1) {
+      const key = token.slice(1);
+      flags[key] = true;
     } else {
       positional.push(token);
     }