@rqml/cli 0.1.0 → 0.2.0

package/dist/index.js

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 import { __commonJS, __toESM } from './chunk-5WRI5ZAA.js';
-import { existsSync, writeFileSync, readFileSync, readdirSync } from 'fs';
-import { resolve, isAbsolute } from 'path';
+import { createHash } from 'crypto';
+import { writeFileSync, existsSync, readFileSync, mkdirSync, statSync, readdirSync } from 'fs';
+import { resolve, join, dirname, isAbsolute } from 'path';
 import { fileURLToPath } from 'url';
 
 // ../../node_modules/.pnpm/fast-xml-parser@4.5.6/node_modules/fast-xml-parser/src/util.js
@@ -3008,6 +3009,64 @@ function resolveTrace(doc) {
   }));
   return { edges, diagnostics };
 }
+function endpointKey(locator) {
+  return locator.kind === "local" ? locator.id : locator.uri;
+}
+function impactOf(doc, id) {
+  const idIndex = declaredIdIndex(doc);
+  const visited = /* @__PURE__ */ new Set([id]);
+  const affected = [];
+  let frontier = [{ key: id, path: [] }];
+  let distance = 0;
+  while (frontier.length > 0) {
+    distance += 1;
+    const next = [];
+    for (const node of frontier) {
+      for (const edge of doc.trace) {
+        const fromKey = endpointKey(edge.from);
+        const toKey = endpointKey(edge.to);
+        const hops = [
+          { direction: "outgoing", here: fromKey, far: edge.to },
+          { direction: "incoming", here: toKey, far: edge.from }
+        ];
+        for (const hop of hops) {
+          const farKey = endpointKey(hop.far);
+          if (hop.here !== node.key || visited.has(farKey)) continue;
+          visited.add(farKey);
+          const local = hop.far.kind === "local";
+          const kind = local ? idIndex.get(farKey)?.kind ?? "unknown" : hop.far.kind;
+          const step = {
+            edgeId: edge.id,
+            type: edge.type,
+            direction: hop.direction,
+            target: farKey
+          };
+          const path = [...node.path, step];
+          affected.push({ id: farKey, kind, distance, path });
+          if (local) next.push({ key: farKey, path });
+        }
+      }
+    }
+    frontier = next;
+  }
+  affected.sort((a, b) => a.distance - b.distance || a.id.localeCompare(b.id));
+  const groupIndex = /* @__PURE__ */ new Map();
+  for (const artifact of affected) {
+    const last = artifact.path[artifact.path.length - 1];
+    if (last === void 0) continue;
+    const key = `${last.direction}:${last.type}`;
+    let group = groupIndex.get(key);
+    if (group === void 0) {
+      group = { direction: last.direction, type: last.type, ids: [] };
+      groupIndex.set(key, group);
+    }
+    group.ids.push(artifact.id);
+  }
+  const groups = [...groupIndex.values()].map((g) => ({ ...g, ids: [...new Set(g.ids)].sort() })).sort(
+    (a, b) => a.direction.localeCompare(b.direction) || a.type.localeCompare(b.type)
+  );
+  return { id, affected, groups };
+}
 var ATTR_PREFIX3 = "@_";
 var REFERENCE_ELEMENTS = /* @__PURE__ */ new Set(["local", "doc"]);
 var parser2 = new import_fast_xml_parser.XMLParser({
@@ -3047,7 +3106,7 @@ function flatRefs(edge, out) {
   if (from !== void 0) out.push({ refId: from, edgeId, side: "from", flat: true });
   if (to !== void 0) out.push({ refId: to, edgeId, side: "to", flat: true });
 }
-function walk(node, declared, refs) {
+function walk(node, declared, refs, machines) {
   for (const [key, value] of Object.entries(node)) {
     if (key.startsWith(ATTR_PREFIX3) || key === "#text") continue;
     for (const item of asArray2(value)) {
@@ -3056,7 +3115,8 @@ function walk(node, declared, refs) {
       if (id !== void 0 && !REFERENCE_ELEMENTS.has(key)) declared.push(id);
       if (key === "edge") nestedRefs(item, refs);
       else if (key === "traceEdge") flatRefs(item, refs);
-      walk(item, declared, refs);
+      else if (key === "stateMachine") machines.push(item);
+      walk(item, declared, refs, machines);
     }
   }
 }
@@ -3105,7 +3165,8 @@ function checkIntegrity(xml) {
   if (!root) return [];
   const declared = [];
   const refs = [];
-  walk(root, declared, refs);
+  const machines = [];
+  walk(root, declared, refs, machines);
   const starts = lineStarts(xml);
   const diagnostics = [];
   const counts = /* @__PURE__ */ new Map();
@@ -3146,8 +3207,372 @@ function checkIntegrity(xml) {
     if (lines.length > 0) diag.line = lines[0];
     diagnostics.push(diag);
   }
+  for (const sm of machines) {
+    const smId = attr2(sm, "id") ?? "";
+    const stateIds = /* @__PURE__ */ new Set();
+    const finalStates = /* @__PURE__ */ new Set();
+    for (const st of asArray2(sm.state).filter(isNode2)) {
+      const sid = attr2(st, "id");
+      if (sid === void 0) continue;
+      stateIds.add(sid);
+      if (attr2(st, "type") === "final") finalStates.add(sid);
+    }
+    const initial = attr2(sm, "initial");
+    if (initial !== void 0 && !stateIds.has(initial)) {
+      const re = new RegExp(
+        `<stateMachine\\b[^>]*?\\sinitial\\s*=\\s*"${escapeRegExp(initial)}"`,
+        "g"
+      );
+      const lines = matchLines(xml, starts, re);
+      const diag = {
+        source: "validate",
+        severity: "error",
+        rule: "unresolved-state-ref",
+        message: `State machine "${smId}" initial state "${initial}" is not a declared state of the machine.`
+      };
+      if (lines.length > 0) diag.line = lines[0];
+      diagnostics.push(diag);
+    }
+    for (const tr of asArray2(sm.transition).filter(isNode2)) {
+      const trId = attr2(tr, "id") ?? "";
+      for (const side of ["from", "to"]) {
+        const refId = attr2(tr, side);
+        if (refId === void 0 || stateIds.has(refId)) continue;
+        const re = new RegExp(
+          `<transition\\b[^>]*?\\s${side}\\s*=\\s*"${escapeRegExp(refId)}"`,
+          "g"
+        );
+        const lines = matchLines(xml, starts, re);
+        const diag = {
+          source: "validate",
+          severity: "error",
+          rule: "unresolved-state-ref",
+          message: `Transition "${trId}" (${side}) references unknown state "${refId}" in state machine "${smId}".`
+        };
+        if (lines.length > 0) diag.line = lines[0];
+        diagnostics.push(diag);
+      }
+      const from = attr2(tr, "from");
+      if (from !== void 0 && finalStates.has(from)) {
+        const re = new RegExp(
+          `<transition\\b[^>]*?\\sid\\s*=\\s*"${escapeRegExp(trId)}"`,
+          "g"
+        );
+        const lines = matchLines(xml, starts, re);
+        const diag = {
+          source: "validate",
+          severity: "error",
+          rule: "final-state-outgoing",
+          message: `Final state "${from}" has outgoing transition "${trId}" in state machine "${smId}".`
+        };
+        if (lines.length > 0) diag.line = lines[0];
+        diagnostics.push(diag);
+      }
+    }
+  }
   return diagnostics;
 }
+var ID_PATTERN = /^[A-Za-z][A-Za-z0-9._-]{1,79}$/;
+function escapeAttr(value) {
+  return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+function deriveEdgeId(type, artifactId, taken) {
+  const prefix = type === "implements" ? "E-IMPL-" : "E-VER-";
+  const base = prefix + artifactId.replace(/^REQ-/, "");
+  if (!taken(base)) return base;
+  for (let n = 2; ; n++) {
+    const candidate = `${base}-${n}`;
+    if (!taken(candidate)) return candidate;
+  }
+}
+function edgeBlock(request, edgeId, indent) {
+  const kind = request.kind ?? (request.type === "implements" ? "code" : "test");
+  const titleAttr = request.title !== void 0 ? ` title="${escapeAttr(request.title)}"` : "";
+  const external = `<external uri="${escapeAttr(request.uri)}" kind="${escapeAttr(kind)}"${titleAttr}/>`;
+  const local = `<local id="${request.artifactId}"/>`;
+  const [from, to] = request.type === "implements" ? [external, local] : [local, external];
+  return [
+    `${indent}<edge id="${edgeId}" type="${request.type}">`,
+    `${indent}  <from><locator>${from}</locator></from>`,
+    `${indent}  <to><locator>${to}</locator></to>`,
+    `${indent}</edge>`
+  ].join("\n");
+}
+function lineInfo(xml, index) {
+  const start = xml.lastIndexOf("\n", index - 1) + 1;
+  const prefix = xml.slice(start, index);
+  return { start, indent: /^[ \t]*$/.test(prefix) ? prefix : "" };
+}
+function appendTraceEdge(xml, request) {
+  const parsed = parse(xml);
+  if (!parsed.ok) {
+    return { ok: false, error: `document does not parse: ${parsed.error.message}` };
+  }
+  const idIndex = declaredIdIndex(parsed.document);
+  if (!idIndex.has(request.artifactId)) {
+    return {
+      ok: false,
+      error: `artifact "${request.artifactId}" is not declared in the document`
+    };
+  }
+  if (request.uri.trim() === "") {
+    return { ok: false, error: "locator uri must not be empty" };
+  }
+  let edgeId;
+  if (request.edgeId !== void 0) {
+    if (!ID_PATTERN.test(request.edgeId)) {
+      return {
+        ok: false,
+        error: `edge id "${request.edgeId}" does not match the RQML id pattern`
+      };
+    }
+    if (idIndex.has(request.edgeId)) {
+      return { ok: false, error: `edge id "${request.edgeId}" is already declared` };
+    }
+    edgeId = request.edgeId;
+  } else {
+    edgeId = deriveEdgeId(request.type, request.artifactId, (id) => idIndex.has(id));
+  }
+  let updated;
+  let edgeXml;
+  const closeIdx = xml.lastIndexOf("</trace>");
+  if (closeIdx >= 0) {
+    const { start, indent } = lineInfo(xml, closeIdx);
+    edgeXml = edgeBlock(request, edgeId, `${indent}  `);
+    updated = `${xml.slice(0, start)}${edgeXml}
+${xml.slice(start)}`;
+  } else {
+    const anchorIdx = (() => {
+      const gov = xml.indexOf("<governance");
+      return gov >= 0 ? gov : xml.lastIndexOf("</rqml>");
+    })();
+    if (anchorIdx < 0) return { ok: false, error: "no </rqml> close tag found" };
+    const { start, indent } = lineInfo(xml, anchorIdx);
+    const sectionIndent = indent === "" ? "  " : indent;
+    edgeXml = edgeBlock(request, edgeId, `${sectionIndent}  `);
+    const section = `${sectionIndent}<trace>
+${edgeXml}
+${sectionIndent}</trace>
+`;
+    updated = `${xml.slice(0, start)}${section}${xml.slice(start)}`;
+  }
+  const before = checkIntegrity(xml).length;
+  const reparsed = parse(updated);
+  if (!reparsed.ok) {
+    return {
+      ok: false,
+      error: `edit produced an unparseable document: ${reparsed.error.message}`
+    };
+  }
+  if (checkIntegrity(updated).length > before) {
+    return {
+      ok: false,
+      error: "edit introduced an integrity violation; document left unchanged"
+    };
+  }
+  return { ok: true, xml: updated, edgeId, edgeXml: edgeXml.trim() };
+}
+function endpointKey2(locator) {
+  return locator.kind === "local" ? locator.id : locator.uri;
+}
+function details(doc, id, kind) {
+  switch (kind) {
+    case "goal": {
+      const g = doc.goals?.goals?.find((x) => x.id === id);
+      return g ? {
+        title: g.title,
+        statement: g.statement,
+        status: g.status,
+        priority: g.priority,
+        rationale: g.rationale
+      } : {};
+    }
+    case "qgoal": {
+      const g = doc.goals?.qualityGoals?.find((x) => x.id === id);
+      return g ? {
+        title: g.title,
+        statement: g.statement,
+        status: g.status,
+        priority: g.priority,
+        notes: g.metric
+      } : {};
+    }
+    case "obstacle": {
+      const o = doc.goals?.obstacles?.find((x) => x.id === id);
+      return o ? { title: o.title, statement: o.statement, notes: o.mitigation } : {};
+    }
+    case "scenario":
+    case "misuseCase":
+    case "edgeCase": {
+      const all = [
+        ...doc.scenarios?.scenarios ?? [],
+        ...doc.scenarios?.misuseCases ?? [],
+        ...doc.scenarios?.edgeCases ?? []
+      ];
+      const s = all.find((x) => x.id === id);
+      return s ? { title: s.title, statement: s.narrative } : {};
+    }
+    case "testCase": {
+      const t = doc.verification?.testCases?.find((x) => x.id === id);
+      return t ? { title: t.title, statement: t.purpose, notes: t.expected } : {};
+    }
+    case "testSuite": {
+      const t = doc.verification?.testSuites?.find((x) => x.id === id);
+      return t ? { title: t.title, statement: t.description } : {};
+    }
+    case "risk": {
+      const r = doc.catalogs?.risks?.find((x) => x.id === id);
+      return r ? { statement: r.statement, notes: r.mitigation } : {};
+    }
+    case "constraint": {
+      const c = doc.catalogs?.constraints?.find((x) => x.id === id);
+      return c ? { statement: c.statement } : {};
+    }
+    case "decision": {
+      const d = doc.catalogs?.decisions?.find((x) => x.id === id);
+      return d ? { statement: d.decision, rationale: d.context, status: d.status } : {};
+    }
+    case "term": {
+      const t = doc.catalogs?.glossary?.find((x) => x.id === id);
+      return t ? { title: t.name, statement: t.definition } : {};
+    }
+    case "rule": {
+      const r = doc.domain?.businessRules?.find((x) => x.id === id);
+      return r ? { statement: r.statement, notes: r.examples } : {};
+    }
+    case "entity": {
+      const e = doc.domain?.entities?.find((x) => x.id === id);
+      return e ? { title: e.name, statement: e.description } : {};
+    }
+    case "stateMachine": {
+      const sm = doc.behavior?.stateMachines?.find((x) => x.id === id);
+      return sm ? { title: sm.name, statement: sm.description } : {};
+    }
+    default:
+      return {};
+  }
+}
+function extractArtifact(doc, id) {
+  const idIndex = declaredIdIndex(doc);
+  const ref = idIndex.get(id);
+  if (ref === void 0) return void 0;
+  const slice = { id, kind: ref.kind, edges: [] };
+  const req = requirementIndex(doc).get(id);
+  if (req !== void 0) {
+    slice.title = req.title;
+    slice.statement = req.statement;
+    slice.reqType = req.type;
+    if (req.status !== void 0) slice.status = req.status;
+    if (req.priority !== void 0) slice.priority = req.priority;
+    if (req.rationale !== void 0) slice.rationale = req.rationale;
+    if (req.notes !== void 0) slice.notes = req.notes;
+    if (req.acceptance.length > 0) slice.acceptance = req.acceptance;
+  } else {
+    const extra = Object.fromEntries(
+      Object.entries(details(doc, id, ref.kind)).filter(([, v]) => v !== void 0)
+    );
+    Object.assign(slice, extra);
+  }
+  for (const edge of doc.trace) {
+    const fromKey = endpointKey2(edge.from);
+    const toKey = endpointKey2(edge.to);
+    if (fromKey !== id && toKey !== id) continue;
+    const direction = fromKey === id ? "outgoing" : "incoming";
+    const far = direction === "outgoing" ? edge.to : edge.from;
+    const target = endpointKey2(far);
+    const targetKind = far.kind === "local" ? idIndex.get(target)?.kind ?? "unknown" : far.kind;
+    const sliceEdge = {
+      edgeId: edge.id,
+      type: edge.type,
+      direction,
+      target,
+      targetKind
+    };
+    if (far.kind !== "local" && far.title !== void 0) sliceEdge.title = far.title;
+    slice.edges.push(sliceEdge);
+  }
+  return slice;
+}
+function sliceToMarkdown(slice) {
+  const lines = [];
+  const heading = slice.title !== void 0 ? `${slice.id} \u2014 ${slice.title}` : slice.id;
+  lines.push(`## ${heading}`);
+  const facts = [
+    `kind: ${slice.kind}${slice.reqType !== void 0 ? ` (${slice.reqType})` : ""}`
+  ];
+  if (slice.status !== void 0) facts.push(`status: ${slice.status}`);
+  if (slice.priority !== void 0) facts.push(`priority: ${slice.priority}`);
+  lines.push(facts.join(" \xB7 "), "");
+  if (slice.statement !== void 0) lines.push(slice.statement.trim(), "");
+  if (slice.rationale !== void 0) {
+    lines.push(`**Rationale:** ${slice.rationale.trim()}`, "");
+  }
+  if (slice.notes !== void 0) lines.push(`**Notes:** ${slice.notes.trim()}`, "");
+  if (slice.acceptance !== void 0 && slice.acceptance.length > 0) {
+    lines.push("### Acceptance");
+    for (const c of slice.acceptance) {
+      const parts = [];
+      if (c.given !== void 0) parts.push(`GIVEN ${c.given.trim()}`);
+      if (c.when !== void 0) parts.push(`WHEN ${c.when.trim()}`);
+      parts.push(`THEN ${c.then.trim()}`);
+      lines.push(`- ${c.id !== void 0 ? `\`${c.id}\` ` : ""}${parts.join(" ")}`);
+    }
+    lines.push("");
+  }
+  if (slice.edges.length > 0) {
+    lines.push("### Trace");
+    for (const e of slice.edges) {
+      const arrow = e.direction === "outgoing" ? "\u2192" : "\u2190";
+      lines.push(`- ${arrow} ${e.type} ${e.target} (${e.targetKind}, \`${e.edgeId}\`)`);
+    }
+    lines.push("");
+  }
+  return `${lines.join("\n").trimEnd()}
+`;
+}
+var SKELETON_KINDS = [
+  "req",
+  "edge",
+  "testCase",
+  "stateMachine"
+];
+var TEMPLATES = {
+  req: (id) => `<req id="${id}" type="FR" title="Title" status="draft" priority="must">
+  <statement>The system SHALL ...</statement>
+  <acceptance>
+    <criterion id="${id}-CRIT-1">
+      <given>...</given>
+      <when>...</when>
+      <then>...</then>
+    </criterion>
+  </acceptance>
+</req>`,
+  edge: (id) => `<edge id="${id}" type="satisfies">
+  <from><locator><local id="REQ-AREA-001"/></locator></from>
+  <to><locator><local id="GOAL-NAME"/></locator></to>
+</edge>`,
+  testCase: (id) => `<testCase id="${id}" type="unit" title="Title">
+  <purpose>...</purpose>
+  <steps>...</steps>
+  <expected>...</expected>
+</testCase>`,
+  stateMachine: (id) => `<stateMachine id="${id}" name="Name" initial="ST-START">
+  <state id="ST-START" name="Start" type="initial"/>
+  <state id="ST-DONE" name="Done" type="final"/>
+  <transition id="TR-FINISH" from="ST-START" to="ST-DONE" event="finish"/>
+</stateMachine>`
+};
+var DEFAULT_IDS = {
+  req: "REQ-AREA-001",
+  edge: "E-AREA-001",
+  testCase: "TC-NAME",
+  stateMachine: "SM-NAME"
+};
+function skeleton(kind, options = {}) {
+  const template = TEMPLATES[kind];
+  return `${template(options.id ?? DEFAULT_IDS[kind])}
+`;
+}
 var UPWARD_TARGET_KINDS = /* @__PURE__ */ new Set([
   "goal",
   "qgoal",
@@ -3200,15 +3625,20 @@ function computeCoverage(doc) {
     if (!(incoming.get(id)?.satisfies?.length ?? 0)) uncoveredGoals.push(id);
   }
   uncoveredGoals.sort();
+  const statusOf = new Map(reqs.map((r) => [r.id, r.status]));
   const unverifiedRequirements = [];
   const unimplementedRequirements = [];
+  const unimplementedApprovedRequirements = [];
   const orphanRequirements = [];
   for (const id of [...reqIds].sort()) {
     const out = outgoing.get(id) ?? {};
     const inc = incoming.get(id) ?? {};
     const verified = (out.verifiedBy?.length ?? 0) > 0 || (inc.covers?.length ?? 0) > 0;
     if (!verified) unverifiedRequirements.push(id);
-    if (!(inc.implements?.length ?? 0)) unimplementedRequirements.push(id);
+    if (!(inc.implements?.length ?? 0)) {
+      unimplementedRequirements.push(id);
+      if (statusOf.get(id) === "approved") unimplementedApprovedRequirements.push(id);
+    }
     const satisfiesUpward = (out.satisfies ?? []).some((edgeId) => {
       const edge = doc.trace.find((e) => e.id === edgeId);
       const to = edge?.to;
@@ -3218,6 +3648,15 @@ function computeCoverage(doc) {
     });
     if (!satisfiesUpward) orphanRequirements.push(id);
   }
+  const prematureImplementations = [];
+  for (const edge of doc.trace) {
+    if (edge.type !== "implements" || edge.to.kind !== "local") continue;
+    const requirementId = edge.to.id;
+    if (!reqIds.has(requirementId)) continue;
+    if (statusOf.get(requirementId) === "approved") continue;
+    prematureImplementations.push({ edgeId: edge.id, requirementId });
+  }
+  prematureImplementations.sort((a, b) => a.edgeId.localeCompare(b.edgeId));
   const diagnostics = [];
   for (const id of uncoveredGoals)
     diagnostics.push(
@@ -3251,12 +3690,22 @@ function computeCoverage(doc) {
         `Requirement "${id}" satisfies no goal or scenario.`
       )
     );
+  for (const p of prematureImplementations)
+    diagnostics.push(
+      finding(
+        "coverage",
+        "premature-implementation",
+        `implements edge "${p.edgeId}" targets requirement "${p.requirementId}", which is not approved.`
+      )
+    );
   diagnostics.push(...resolveTrace(doc).diagnostics);
   return {
     requirements,
     uncoveredGoals,
     unverifiedRequirements,
     unimplementedRequirements,
+    unimplementedApprovedRequirements,
+    prematureImplementations,
     orphanRequirements,
     diagnostics
   };
@@ -3264,6 +3713,51 @@ function computeCoverage(doc) {
 function finding(source, rule, message) {
   return { source, severity: "warning", rule, message };
 }
+var BASELINE_PATH = ".rqml/baseline.json";
+function hashFileAt(filePath) {
+  try {
+    return createHash("sha256").update(readFileSync(filePath)).digest("hex");
+  } catch {
+    return void 0;
+  }
+}
+function computeBaseline(doc, options = {}) {
+  const baseDir = options.baseDir ?? process.cwd();
+  const baseline = {};
+  for (const link of implementsLinks(doc)) {
+    const filePath = filePathFromUri(link.uri, baseDir);
+    if (filePath === void 0) continue;
+    const hash = hashFileAt(filePath);
+    if (hash !== void 0) baseline[link.edgeId] = hash;
+  }
+  return baseline;
+}
+function loadBaseline(baseDir) {
+  try {
+    const parsed = JSON.parse(
+      readFileSync(join(baseDir, BASELINE_PATH), "utf8")
+    );
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      return void 0;
+    }
+    const out = {};
+    for (const [edgeId, hash] of Object.entries(parsed)) {
+      if (typeof hash === "string") out[edgeId] = hash;
+    }
+    return out;
+  } catch {
+    return void 0;
+  }
+}
+function saveBaseline(baseDir, baseline) {
+  const path = join(baseDir, BASELINE_PATH);
+  mkdirSync(dirname(path), { recursive: true });
+  const sorted = Object.fromEntries(
+    Object.entries(baseline).sort(([a], [b]) => a.localeCompare(b))
+  );
+  writeFileSync(path, `${JSON.stringify(sorted, null, 2)}
+`);
+}
 function implementsLinks(doc) {
   const out = [];
   for (const edge of doc.trace) {
@@ -3289,16 +3783,22 @@ function filePathFromUri(uri, baseDir) {
   }
   return void 0;
 }
-function filesystemResolver(baseDir) {
+function filesystemResolver(baseDir, baseline) {
   return (link) => {
     const filePath = filePathFromUri(link.uri, baseDir);
     if (filePath === void 0) return "present";
-    return existsSync(filePath) ? "present" : "missing";
+    if (!existsSync(filePath)) return "missing";
+    const recorded = baseline?.[link.edgeId];
+    if (recorded !== void 0) {
+      const current = hashFileAt(filePath);
+      if (current !== void 0 && current !== recorded) return "changed";
+    }
+    return "present";
   };
 }
 function detectDrift(doc, options = {}) {
   const baseDir = options.baseDir ?? process.cwd();
-  const resolve4 = options.resolve ?? filesystemResolver(baseDir);
+  const resolve4 = options.resolve ?? filesystemResolver(baseDir, options.baseline);
   const links = implementsLinks(doc);
   const drifted = [];
   const diagnostics = [];
@@ -3370,17 +3870,29 @@ function parseArgs(rest) {
     positionals,
     json: flags.get("json") === true || flags.get("json") === "true",
     strictness,
-    baseDir: resolve(String(flags.get("base-dir") ?? process.cwd()))
+    baseDir: resolve(String(flags.get("base-dir") ?? process.cwd())),
+    flags
   };
 }
+function flagString(args, name) {
+  const value = args.flags.get(name);
+  return typeof value === "string" ? value : void 0;
+}
+function specArgs(args) {
+  const override = flagString(args, "spec");
+  return { ...args, positionals: override !== void 0 ? [override] : [] };
+}
 function resolveSpecPath(args) {
   const explicit = args.positionals[0];
   if (explicit !== void 0) {
     const p = resolve(args.baseDir, explicit);
     if (!existsSync(p)) throw new UsageError(`spec file not found: ${explicit}`);
+    if (statSync(p).isDirectory()) {
+      throw new UsageError(`"${explicit}" is a directory, not an .rqml file`);
+    }
     return p;
   }
-  const candidates = readdirSync(args.baseDir).filter((f) => f.endsWith(".rqml")).sort();
+  const candidates = readdirSync(args.baseDir, { withFileTypes: true }).filter((e) => e.isFile() && e.name.endsWith(".rqml")).map((e) => e.name).sort();
   if (candidates.length === 0) {
     throw new UsageError("no .rqml document found in this directory; pass a path");
   }
@@ -3404,10 +3916,13 @@ async function runCheck(rest) {
   const integrity = validation.valid ? checkIntegrity(xml) : [];
   const parsed = parse(xml);
   const coverage = parsed.ok ? computeCoverage(parsed.document) : void 0;
-  const drift = parsed.ok ? detectDrift(parsed.document, { baseDir: args.baseDir }) : void 0;
+  const driftOptions = { baseDir: args.baseDir };
+  const baseline = loadBaseline(args.baseDir);
+  if (baseline !== void 0) driftOptions.baseline = baseline;
+  const drift = parsed.ok ? detectDrift(parsed.document, driftOptions) : void 0;
   const validationFailed = !validation.valid || integrity.length > 0;
   const driftFailed = (drift?.drifted.length ?? 0) > 0;
-  const coverageProblemCount = (coverage?.uncoveredGoals.length ?? 0) + (coverage?.unverifiedRequirements.length ?? 0) + (coverage?.orphanRequirements.length ?? 0);
+  const coverageProblemCount = (coverage?.uncoveredGoals.length ?? 0) + (coverage?.unverifiedRequirements.length ?? 0) + (coverage?.orphanRequirements.length ?? 0) + (coverage?.unimplementedApprovedRequirements.length ?? 0) + (coverage?.prematureImplementations.length ?? 0);
   const coverageFailed = coverageBlocks(args.strictness) && coverageProblemCount > 0;
   const verdict = validationFailed || driftFailed || coverageFailed ? "fail" : "pass";
   const diagnostics = [
@@ -3427,6 +3942,8 @@ async function runCheck(rest) {
       uncoveredGoals: coverage.uncoveredGoals,
       unverifiedRequirements: coverage.unverifiedRequirements,
       unimplementedRequirements: coverage.unimplementedRequirements,
+      unimplementedApprovedRequirements: coverage.unimplementedApprovedRequirements,
+      prematureImplementations: coverage.prematureImplementations,
       orphanRequirements: coverage.orphanRequirements
     } : null,
     diagnostics
@@ -3446,8 +3963,54 @@ async function runCheck(rest) {
   return EXIT.OK;
 }
 
+// src/commands/impact.ts
+async function runImpact(rest) {
+  const args = parseArgs(rest);
+  const id = args.positionals[0];
+  if (id === void 0) {
+    throw new UsageError("usage: rqml impact <id> [--json] [--spec <path>]");
+  }
+  const { path, xml } = readSpec(specArgs(args));
+  const parsed = parse(xml);
+  if (!parsed.ok) {
+    process.stderr.write(`\u2717 ${path}: ${parsed.error.message}
+`);
+    return EXIT.VALIDATION;
+  }
+  if (!declaredIdIndex(parsed.document).has(id)) {
+    process.stderr.write(`\u2717 no artifact with id "${id}" in ${path}
+`);
+    return EXIT.USAGE;
+  }
+  const report = impactOf(parsed.document, id);
+  if (args.json) {
+    process.stdout.write(`${JSON.stringify(report, null, 2)}
+`);
+    return EXIT.OK;
+  }
+  process.stdout.write(`Impact of ${id} \u2014 ${report.affected.length} affected
+`);
+  for (const group of report.groups) {
+    const arrow = group.direction === "outgoing" ? "\u2192" : "\u2190";
+    process.stdout.write(`  ${arrow} ${group.type}: ${group.ids.join(", ")}
+`);
+  }
+  const transitive = report.affected.filter((a) => a.distance > 1);
+  if (transitive.length > 0) {
+    process.stdout.write("  transitively:\n");
+    for (const a of transitive) {
+      const path2 = a.path.map((s) => s.edgeId).join(" \u203A ");
+      process.stdout.write(
+        `    ${a.id} (${a.kind}, distance ${a.distance} via ${path2})
+`
+      );
+    }
+  }
+  return EXIT.OK;
+}
+
 // ../schema/dist/index.js
-var AGENTS_default = "# RQML Agent Guidelines\n\n## Strictness: `standard`\n\n| Level | Description |\n|-------|-------------|\n| `relaxed` | Prototyping. Spec is advisory. Quick iteration allowed. |\n| `standard` | Production default. Spec-first for features. Core traces. |\n| `strict` | Full traceability. All behavior specified. No ghost features. |\n| `certified` | Regulated/safety-critical. Audit-grade traces with metadata. |\n\n---\n\nThis project uses **RQML** as the single source of truth for system intent. Familiarize yourself with the documentation at https://rqml.org/docs/user-guide/\n\n**Specification file:** Specification lives in a single .rqml file in the root of the project - convention is `requirements.rqml`. Multiple .rqml files may be employed in multirepo projects, in such cases a .rqml spec applies to everything that is higher in the project tree, unless overridden by another .rqml file.\n\n**Schema file:**\nThe RQML XSD schema is at https://rqml.org/schema/rqml-2.1.0.xsd (insert correct version number). Make sure to adhere to the schema at all times and follow guidelines in schema comments. Use as much of the RQML tagset as is necessary to capture and describe high quality requirements.\n\n---\n\n## Core Principle: Spec-First Development\n\n```\n[Elicit] \u2192 [Specify] \u2192 [Implement] \u2192 [Verify] \u2192 [Trace]\n    \u2191____________________\u2190______________________|\n```\n\nCode follows specification, not the reverse. If code and spec diverge, the spec is authoritative\u2014update the code or negotiate a spec change with the developer.\n\n---\n\n## Workflow\n\n### 1. Elicit\nAsk clarifying questions until you understand the goal, scope, acceptance criteria, and constraints. Don't assume\u2014capture assumptions as `<notes>` or `<issue>` elements.\n\n### 2. Specify\n**Never implement unspecified behavior.** Update the `.rqml` file before coding:\n- Add a `<req>` with statement and acceptance criteria\n- Set appropriate `type`, `priority`, and `status=\"draft\"`\n- Get developer confirmation before proceeding\n\n### 3. Implement\nReference requirement IDs in code comments. If you discover missing requirements, stop and add them to the spec first.\n\n### 4. Verify\nAdd tests that reference requirement IDs. Update `<trace>` section with verification links.\n\n---\n\n## When Code and Spec Diverge\n\n1. **Spec gap** (code has behavior not in spec): Propose adding the requirement, mark as `status=\"review\"`\n2. **Code bug** (code doesn't match spec): Fix the code\n3. **Spec bug** (spec is wrong): Propose correction, wait for developer confirmation\n\n**Never silently change the spec to match code.**\n\n---\n\n## Strictness Reference\n\n| Aspect | relaxed | standard | strict | certified |\n|--------|---------|----------|--------|-----------|\n| Elicitation | Major features | Testable reqs | Edge cases | Formal |\n| Spec-first | Recommended | Required | Required | Approved first |\n| Code traces | Optional | New features | All changes | With metadata |\n| Test traces | Optional | New reqs | All reqs | Full matrix |\n| Ghost features | Allowed | Blocked | Blocked | Blocked |\n\n---\n\n## Change Summary Template\n\nFor PRs and commits:\n\n```\n## RQML Trace Summary\n\n**Requirements:** REQ-xxx (added/modified/implemented)\n**Implementation:** `path/to/file` \u2014 what changed\n**Verification:** `path/to/test` \u2014 what it verifies\n**Open items:** gaps, assumptions, follow-ups\n```\n\n---\n\n## Schema Validation\n\nThe `.rqml` file must remain valid XML conforming to the version of RQML referenced in the version attribute in the spec document.\n\n**To validate:** Try xmllint first (pre-installed on macOS/Linux):\n```bash\nxmllint --schema https://rqml.org/schema/rqml-2.1.0.xsd <rqml-file-name> --noout\n```\n\nIf xmllint is unavailable, use Python with lxml:\n```bash\npip install lxml\npython -c \"from lxml import etree; s=etree.XMLSchema(etree.parse('https://rqml.org/schema/rqml-2.1.0.xsd')); print('Valid' if s.validate(etree.parse('<rqml-file-name>')) else s.error_log)\"\n```\n\n**IDE validation:** If the `.rqml` file includes `xsi:schemaLocation`, XML-aware editors (VS Code with XML extension, IntelliJ) validate automatically.\n\nThe schema comments contain detailed guidance on document structure, ID conventions, and requirement quality criteria.\n\n**If unsure:** Ask the developer before making structural changes to the spec.\n";
+var AGENTS_default = '# RQML Agent Guidelines\n\n## Strictness: `standard`\n\n| Level | Description |\n|-------|-------------|\n| `relaxed` | Prototyping. Spec is advisory. Quick iteration allowed. |\n| `standard` | Production default. Spec-first for features. Core traces. |\n| `strict` | Full traceability. All behavior specified. No ghost features. |\n| `certified` | Regulated/safety-critical. Audit-grade traces with metadata. |\n\n---\n\nThis project uses **RQML** as the single source of truth for system intent. Familiarize yourself with the documentation at https://rqml.org/docs/user-guide/\n\n**Specification file:** Specification lives in a single .rqml file in the root of the project - convention is `requirements.rqml`. Multiple .rqml files may be employed in multirepo projects, in such cases a .rqml spec applies to everything that is higher in the project tree, unless overridden by another .rqml file.\n\n**Schema file:**\nThe RQML XSD schema is at https://rqml.org/schema/rqml-2.1.0.xsd (insert correct version number). Make sure to adhere to the schema at all times and follow guidelines in schema comments. Use as much of the RQML tagset as is necessary to capture and describe high quality requirements.\n\n---\n\n## Toolchain\n\nThe spec-first loop is enforced by the `rqml` CLI (npm: `@rqml/cli`; the `@rqml/mcp` server exposes the same engine as agent tools):\n\n```bash\nrqml check                 # deterministic gate: validation + coverage + drift (exit 0 = pass)\nrqml status                # re-anchor: spec, coverage, and drift state\nrqml show <REQ-ID>         # one requirement: statement, acceptance criteria, trace neighborhood\nrqml impact <ID>           # what is affected, transitively, if this artifact changes\nrqml link <REQ-ID> <path>  # record an implements edge + drift baseline (--type verifiedBy for tests)\nrqml skeleton <kind>       # schema-valid snippet: req | edge | testCase | stateMachine\n```\n\nRun `rqml status` when you start a session to re-anchor on the spec. Run `rqml check` before finishing any task \u2014 it must exit 0.\n\n---\n\n## Core Principle: Spec-First Development\n\n```\n[Elicit] \u2192 [Specify] \u2192 [Implement] \u2192 [Verify] \u2192 [Trace]\n    \u2191____________________\u2190______________________|\n```\n\nCode follows specification, not the reverse. If code and spec diverge, the spec is authoritative\u2014update the code or negotiate a spec change with the developer.\n\n---\n\n## Workflow\n\n### 1. Elicit\nAsk clarifying questions until you understand the goal, scope, acceptance criteria, and constraints. Don\'t assume\u2014capture assumptions as `<notes>` or `<issue>` elements.\n\n### 2. Specify\n**Never implement unspecified behavior.** Update the `.rqml` file before coding:\n- Add a `<req>` with statement and acceptance criteria\n- Set appropriate `type`, `priority`, and `status="draft"`\n- Get developer confirmation before proceeding\n\n### 3. Implement\nRead the requirement first: `rqml show REQ-XXX`. Check blast radius before changing existing artifacts: `rqml impact REQ-XXX`. If you discover missing requirements, stop and add them to the spec first. After implementing, record the trace link:\n\n```bash\nrqml link REQ-XXX src/path/to/implementation.ts\n```\n\n### 4. Verify\nAdd tests that reference requirement IDs, then record verification:\n\n```bash\nrqml link REQ-XXX test/path/to/test.ts --type verifiedBy\nrqml check   # must exit 0 before you are done\n```\n\n---\n\n## When Code and Spec Diverge\n\n1. **Spec gap** (code has behavior not in spec): Propose adding the requirement, mark as `status="review"`\n2. **Code bug** (code doesn\'t match spec): Fix the code\n3. **Spec bug** (spec is wrong): Propose correction, wait for developer confirmation\n\n**Never silently change the spec to match code.**\n\n---\n\n## Strictness Reference\n\n| Aspect | relaxed | standard | strict | certified |\n|--------|---------|----------|--------|-----------|\n| Elicitation | Major features | Testable reqs | Edge cases | Formal |\n| Spec-first | Recommended | Required | Required | Approved first |\n| Code traces | Optional | New features | All changes | With metadata |\n| Test traces | Optional | New reqs | All reqs | Full matrix |\n| Ghost features | Allowed | Blocked | Blocked | Blocked |\n\n---\n\n## Change Summary Template\n\nFor PRs and commits:\n\n```\n## RQML Trace Summary\n\n**Requirements:** REQ-xxx (added/modified/implemented)\n**Implementation:** `path/to/file` \u2014 what changed\n**Verification:** `path/to/test` \u2014 what it verifies\n**Open items:** gaps, assumptions, follow-ups\n```\n\n---\n\n## Schema Validation\n\nThe `.rqml` file must remain valid XML conforming to the version of RQML referenced in the version attribute in the spec document.\n\n**To validate:** Use the toolchain \u2014 it validates offline against the bundled schema and also checks referential integrity the XSD alone cannot enforce:\n```bash\nrqml validate\n```\n\nIf the `rqml` CLI is not installed, `npx @rqml/cli validate` works without installation. As a last resort, xmllint (pre-installed on macOS/Linux) checks XSD validity only:\n```bash\nxmllint --schema https://rqml.org/schema/rqml-2.1.0.xsd <rqml-file-name> --noout\n```\n\n**IDE validation:** If the `.rqml` file includes `xsi:schemaLocation`, XML-aware editors (VS Code with XML extension, IntelliJ) validate automatically.\n\nThe schema comments contain detailed guidance on document structure, ID conventions, and requirement quality criteria.\n\n**If unsure:** Ask the developer before making structural changes to the spec.\n';
 var AGENTS_TEMPLATE = AGENTS_default;
 
 // src/commands/init.ts
@@ -3490,6 +4053,110 @@ async function runInit(rest) {
   if (!wrote) process.stdout.write("nothing to do; project already initialized\n");
   return EXIT.OK;
 }
+var USAGE = "usage: rqml link <artifact-id> <uri> [--type implements|verifiedBy] [--id <edge-id>] [--kind <k>] [--title <t>] [--spec <path>]";
+async function runLink(rest) {
+  const args = parseArgs(rest);
+  const [artifactId, uri] = args.positionals;
+  if (artifactId === void 0 || uri === void 0) throw new UsageError(USAGE);
+  const type = flagString(args, "type") ?? "implements";
+  if (type !== "implements" && type !== "verifiedBy") {
+    throw new UsageError(`unknown link type "${type}" (implements|verifiedBy)`);
+  }
+  const { path, xml } = readSpec(specArgs(args));
+  const request = { artifactId, uri, type };
+  const edgeId = flagString(args, "id");
+  if (edgeId !== void 0) request.edgeId = edgeId;
+  const kind = flagString(args, "kind");
+  if (kind !== void 0) request.kind = kind;
+  const title = flagString(args, "title");
+  if (title !== void 0) request.title = title;
+  const result = appendTraceEdge(xml, request);
+  if (!result.ok) {
+    process.stderr.write(`\u2717 link failed: ${result.error}
+`);
+    return EXIT.VALIDATION;
+  }
+  const { validate } = await import('./validate-O3LLP44J.js');
+  const validation = validate(result.xml);
+  if (!validation.valid) {
+    printDiagnostics(validation.diagnostics);
+    process.stderr.write("\u2717 link would invalidate the document; nothing written\n");
+    return EXIT.VALIDATION;
+  }
+  writeFileSync(path, result.xml);
+  let baselineRecorded = false;
+  const parsed = parse(result.xml);
+  if (parsed.ok) {
+    const fresh = computeBaseline(parsed.document, { baseDir: args.baseDir });
+    const hash = fresh[result.edgeId];
+    if (hash !== void 0) {
+      const baseline = loadBaseline(args.baseDir) ?? {};
+      baseline[result.edgeId] = hash;
+      saveBaseline(args.baseDir, baseline);
+      baselineRecorded = true;
+    }
+  }
+  if (args.json) {
+    const report = {
+      spec: path,
+      edgeId: result.edgeId,
+      type,
+      artifactId,
+      uri,
+      baselineRecorded
+    };
+    process.stdout.write(`${JSON.stringify(report, null, 2)}
+`);
+  } else {
+    const arrow = type === "implements" ? "\u2190" : "\u2192";
+    const baseline = baselineRecorded ? ", baseline recorded" : "";
+    process.stdout.write(
+      `\u2713 ${artifactId} ${arrow} ${uri} (${result.edgeId}, ${type}${baseline})
+`
+    );
+  }
+  return EXIT.OK;
+}
+
+// src/commands/show.ts
+async function runShow(rest) {
+  const args = parseArgs(rest);
+  const id = args.positionals[0];
+  if (id === void 0) {
+    throw new UsageError("usage: rqml show <id> [--json] [--spec <path>]");
+  }
+  const { path, xml } = readSpec(specArgs(args));
+  const parsed = parse(xml);
+  if (!parsed.ok) {
+    process.stderr.write(`\u2717 ${path}: ${parsed.error.message}
+`);
+    return EXIT.VALIDATION;
+  }
+  const slice = extractArtifact(parsed.document, id);
+  if (slice === void 0) {
+    process.stderr.write(`\u2717 no artifact with id "${id}" in ${path}
+`);
+    return EXIT.USAGE;
+  }
+  process.stdout.write(
+    args.json ? `${JSON.stringify(slice, null, 2)}
+` : sliceToMarkdown(slice)
+  );
+  return EXIT.OK;
+}
+
+// src/commands/skeleton.ts
+async function runSkeleton(rest) {
+  const args = parseArgs(rest);
+  const kind = args.positionals[0];
+  const kinds = SKELETON_KINDS.join("|");
+  if (kind === void 0 || !SKELETON_KINDS.includes(kind)) {
+    throw new UsageError(`usage: rqml skeleton <${kinds}> [--id <id>]`);
+  }
+  const id = flagString(args, "id");
+  process.stdout.write(skeleton(kind, id !== void 0 ? { id } : {}));
+  return EXIT.OK;
+}
 
 // src/commands/status.ts
 async function runStatus(rest) {
@@ -3516,6 +4183,8 @@ async function runStatus(rest) {
     uncoveredGoals: coverage.uncoveredGoals,
     unverifiedRequirements: coverage.unverifiedRequirements,
     unimplementedRequirements: coverage.unimplementedRequirements,
+    unimplementedApprovedRequirements: coverage.unimplementedApprovedRequirements,
+    prematureImplementations: coverage.prematureImplementations,
     orphanRequirements: coverage.orphanRequirements,
     danglingReferences: trace.diagnostics.length,
     lintFindings: lintDiags.length
@@ -3530,7 +4199,8 @@ async function runStatus(rest) {
   requirements: ${reqCount}   trace edges: ${doc.trace.length}
   uncovered goals: ${coverage.uncoveredGoals.length}
   unverified reqs: ${coverage.unverifiedRequirements.length}
-  unimplemented reqs: ${coverage.unimplementedRequirements.length}
+  unimplemented reqs: ${coverage.unimplementedRequirements.length} (approved: ${coverage.unimplementedApprovedRequirements.length})
+  premature implementations: ${coverage.prematureImplementations.length}
   dangling refs: ${trace.diagnostics.length}   lint findings: ${lintDiags.length}
 `
     );
@@ -3571,15 +4241,24 @@ Usage:
   rqml <command> [spec.rqml] [options]
 
 Commands:
-  init [path]      Scaffold a starter spec and AGENTS.md project marker
-  validate [path]  Validate XML well-formedness, XSD, and referential integrity
-  status [path]    Show spec, coverage, and lint summary
-  check [path]     Deterministic enforcement gate (validation + coverage + drift)
+  init [path]        Scaffold a starter spec and AGENTS.md project marker
+  validate [path]    Validate XML well-formedness, XSD, and referential integrity
+  status [path]      Show spec, coverage, and lint summary
+  check [path]       Deterministic enforcement gate (validation + coverage + drift)
+  link <id> <uri>    Record an implements/verifiedBy edge and its drift baseline
+  show <id>          Extract one artifact with its trace neighborhood
+  impact <id>        What is affected, transitively, if this artifact changes
+  skeleton <kind>    Print a schema-valid snippet (req|edge|testCase|stateMachine)
 
 Options:
-  --json                 Emit machine-readable JSON (status, check, validate)
+  --json                 Emit machine-readable JSON (status, check, validate, link, show, impact)
   --strictness <level>   relaxed | standard | strict | certified (default: standard)
   --base-dir <dir>       Directory to resolve the spec and code links against
+  --spec <path>          Explicit spec file (link, show, impact)
+  --type <type>          Link type: implements | verifiedBy (default: implements)
+  --id <id>              Explicit edge id (link) or skeleton root id
+  --kind <kind>          Locator kind hint for link (default: code/test by type)
+  --title <title>        Locator title hint for link
   -h, --help             Show this help
   -v, --version          Show version
 
@@ -3596,6 +4275,14 @@ async function main(argv) {
       return runCheck(rest);
     case "init":
       return runInit(rest);
+    case "link":
+      return runLink(rest);
+    case "show":
+      return runShow(rest);
+    case "impact":
+      return runImpact(rest);
+    case "skeleton":
+      return runSkeleton(rest);
     case "-v":
     case "--version":
       process.stdout.write(`${VERSION}