@rqml/cli 0.2.0 → 0.4.0

package/README.md

@@ -18,10 +18,16 @@ rqml <command> [spec.rqml] [options]
   validate [path]  XML well-formedness, XSD, and referential integrity
   status [path]    Spec, coverage, and lint summary
   check [path]     Deterministic enforcement gate (validation + coverage + drift)
-
-  --json                 Machine-readable output (REQ-CLI-JSON)
-  --strictness <level>   relaxed | standard | strict | certified
-  --base-dir <dir>       Resolve the spec and implements code links against <dir>
+  show <id>        One artifact: statement, acceptance criteria, trace neighborhood
+  impact <id>      What is affected, transitively, if this artifact changes
+  matrix [path]    Traceability matrix: status, goals, code, tests, coverage gaps
+  link <id> <uri>  Record an implements/verifiedBy edge and its drift baseline
+  skeleton <kind>  Print a schema-valid snippet (req|edge|testCase|stateMachine)
+
+  --json                     Machine-readable output (REQ-CLI-JSON)
+  --strictness <level>       relaxed | standard | strict | certified
+  --base-dir <dir>           Resolve the spec and implements code links against <dir>
+  --status/--type/--warning  Filter matrix rows (comma-separated, e.g. --warning unverified)
 ```
 
 When no spec path is given, the lone `*.rqml` in the working directory is used

package/dist/index.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { __commonJS, __toESM } from './chunk-5WRI5ZAA.js';
+import { createRequire } from 'module';
 import { createHash } from 'crypto';
 import { writeFileSync, existsSync, readFileSync, mkdirSync, statSync, readdirSync } from 'fs';
 import { resolve, join, dirname, isAbsolute } from 'path';
@@ -13,7 +14,7 @@ var require_util = __commonJS({
     var nameRegexp = "[" + nameStartChar + "][" + nameChar + "]*";
     var regexName = new RegExp("^" + nameRegexp + "$");
     var getAllMatches = function(string, regex) {
-      const matches = [];
+      const matches2 = [];
       let match = regex.exec(string);
       while (match) {
         const allmatches = [];
@@ -22,10 +23,10 @@ var require_util = __commonJS({
         for (let index = 0; index < len; index++) {
           allmatches.push(match[index]);
         }
-        matches.push(allmatches);
+        matches2.push(allmatches);
         match = regex.exec(string);
       }
-      return matches;
+      return matches2;
     };
     var isName = function(string) {
       const match = regexName.exec(string);
@@ -303,24 +304,24 @@ var require_validator = __commonJS({
     }
     var validAttrStrRegxp = new RegExp(`(\\s*)([^\\s=]+)(\\s*=)?(\\s*(['"])(([\\s\\S])*?)\\5)?`, "g");
     function validateAttributeString(attrStr, options) {
-      const matches = util.getAllMatches(attrStr, validAttrStrRegxp);
+      const matches2 = util.getAllMatches(attrStr, validAttrStrRegxp);
       const attrNames = {};
-      for (let i = 0; i < matches.length; i++) {
-        if (matches[i][1].length === 0) {
-          return getErrorObject("InvalidAttr", "Attribute '" + matches[i][2] + "' has no space in starting.", getPositionFromMatch(matches[i]));
-        } else if (matches[i][3] !== void 0 && matches[i][4] === void 0) {
-          return getErrorObject("InvalidAttr", "Attribute '" + matches[i][2] + "' is without value.", getPositionFromMatch(matches[i]));
-        } else if (matches[i][3] === void 0 && !options.allowBooleanAttributes) {
-          return getErrorObject("InvalidAttr", "boolean attribute '" + matches[i][2] + "' is not allowed.", getPositionFromMatch(matches[i]));
+      for (let i = 0; i < matches2.length; i++) {
+        if (matches2[i][1].length === 0) {
+          return getErrorObject("InvalidAttr", "Attribute '" + matches2[i][2] + "' has no space in starting.", getPositionFromMatch(matches2[i]));
+        } else if (matches2[i][3] !== void 0 && matches2[i][4] === void 0) {
+          return getErrorObject("InvalidAttr", "Attribute '" + matches2[i][2] + "' is without value.", getPositionFromMatch(matches2[i]));
+        } else if (matches2[i][3] === void 0 && !options.allowBooleanAttributes) {
+          return getErrorObject("InvalidAttr", "boolean attribute '" + matches2[i][2] + "' is not allowed.", getPositionFromMatch(matches2[i]));
         }
-        const attrName = matches[i][2];
+        const attrName = matches2[i][2];
         if (!validateAttrName(attrName)) {
-          return getErrorObject("InvalidAttr", "Attribute '" + attrName + "' is an invalid name.", getPositionFromMatch(matches[i]));
+          return getErrorObject("InvalidAttr", "Attribute '" + attrName + "' is an invalid name.", getPositionFromMatch(matches2[i]));
         }
         if (!attrNames.hasOwnProperty(attrName)) {
           attrNames[attrName] = 1;
         } else {
-          return getErrorObject("InvalidAttr", "Attribute '" + attrName + "' is repeated.", getPositionFromMatch(matches[i]));
+          return getErrorObject("InvalidAttr", "Attribute '" + attrName + "' is repeated.", getPositionFromMatch(matches2[i]));
         }
       }
       return true;
@@ -1057,15 +1058,15 @@ var require_OrderedObjParser = __commonJS({
     var attrsRegx = new RegExp(`([^\\s=]+)\\s*(=\\s*(['"])([\\s\\S]*?)\\3)?`, "gm");
     function buildAttributesMap(attrStr, jPath, tagName) {
       if (this.options.ignoreAttributes !== true && typeof attrStr === "string") {
-        const matches = util.getAllMatches(attrStr, attrsRegx);
-        const len = matches.length;
+        const matches2 = util.getAllMatches(attrStr, attrsRegx);
+        const len = matches2.length;
         const attrs = {};
         for (let i = 0; i < len; i++) {
-          const attrName = this.resolveNameSpace(matches[i][1]);
+          const attrName = this.resolveNameSpace(matches2[i][1]);
           if (this.ignoreAttributesFn(attrName, jPath)) {
             continue;
           }
-          let oldVal = matches[i][4];
+          let oldVal = matches2[i][4];
           let aName = this.options.attributeNamePrefix + attrName;
           if (attrName.length) {
             if (this.options.transformAttributeName) {
@@ -1327,9 +1328,9 @@ var require_OrderedObjParser = __commonJS({
       }
       for (let entityName in this.docTypeEntities) {
         const entity = this.docTypeEntities[entityName];
-        const matches = val.match(entity.regx);
-        if (matches) {
-          this.entityExpansionCount += matches.length;
+        const matches2 = val.match(entity.regx);
+        if (matches2) {
+          this.entityExpansionCount += matches2.length;
           if (entityConfig.maxTotalExpansions && this.entityExpansionCount > entityConfig.maxTotalExpansions) {
             throw new Error(
               `Entity expansion limit exceeded: ${this.entityExpansionCount} > ${entityConfig.maxTotalExpansions}`
@@ -1350,9 +1351,9 @@ var require_OrderedObjParser = __commonJS({
       if (val.indexOf("&") === -1) return val;
       for (const entityName of Object.keys(this.lastEntities)) {
         const entity = this.lastEntities[entityName];
-        const matches = val.match(entity.regex);
-        if (matches) {
-          this.entityExpansionCount += matches.length;
+        const matches2 = val.match(entity.regex);
+        if (matches2) {
+          this.entityExpansionCount += matches2.length;
           if (entityConfig.maxTotalExpansions && this.entityExpansionCount > entityConfig.maxTotalExpansions) {
             throw new Error(
               `Entity expansion limit exceeded: ${this.entityExpansionCount} > ${entityConfig.maxTotalExpansions}`
@@ -1365,9 +1366,9 @@ var require_OrderedObjParser = __commonJS({
       if (this.options.htmlEntities) {
         for (const entityName of Object.keys(this.htmlEntities)) {
           const entity = this.htmlEntities[entityName];
-          const matches = val.match(entity.regex);
-          if (matches) {
-            this.entityExpansionCount += matches.length;
+          const matches2 = val.match(entity.regex);
+          if (matches2) {
+            this.entityExpansionCount += matches2.length;
             if (entityConfig.maxTotalExpansions && this.entityExpansionCount > entityConfig.maxTotalExpansions) {
               throw new Error(
                 `Entity expansion limit exceeded: ${this.entityExpansionCount} > ${entityConfig.maxTotalExpansions}`
@@ -3372,6 +3373,157 @@ ${sectionIndent}</trace>
   }
   return { ok: true, xml: updated, edgeId, edgeXml: edgeXml.trim() };
 }
+function escapeRegExp2(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+var EXTERNAL_ELEMENT = /<external\b[^>]*(?:\/>|>[\s\S]*?<\/external>)/g;
+function updateTraceEdge(xml, request) {
+  const parsed = parse(xml);
+  if (!parsed.ok) {
+    return { ok: false, error: `document does not parse: ${parsed.error.message}` };
+  }
+  if (request.uri.trim() === "") {
+    return { ok: false, error: "locator uri must not be empty" };
+  }
+  const prefix = request.type === "implements" ? "E-IMPL-" : "E-VER-";
+  const edgeId = request.edgeId ?? prefix + request.artifactId.replace(/^REQ-/, "");
+  const edge = parsed.document.trace.find((e) => e.id === edgeId);
+  if (edge === void 0) {
+    return {
+      ok: false,
+      error: request.edgeId !== void 0 ? `no trace edge with id "${edgeId}" exists` : `no trace edge with the derived id "${edgeId}" exists; pass --id for an explicitly named edge`
+    };
+  }
+  if (edge.type !== request.type) {
+    return {
+      ok: false,
+      error: `edge "${edgeId}" has type "${edge.type}", not "${request.type}"`
+    };
+  }
+  const local = edge.from.kind === "local" ? edge.from : edge.to.kind === "local" ? edge.to : void 0;
+  if (local === void 0 || local.id !== request.artifactId) {
+    return {
+      ok: false,
+      error: `edge "${edgeId}" does not link artifact "${request.artifactId}"`
+    };
+  }
+  const external = edge.from.kind === "external" ? edge.from : edge.to.kind === "external" ? edge.to : void 0;
+  if (external === void 0) {
+    return { ok: false, error: `edge "${edgeId}" has no external locator to update` };
+  }
+  const openTag = new RegExp(`<edge\\b[^>]*\\bid="${escapeRegExp2(edgeId)}"[^>]*>`);
+  const open = openTag.exec(xml);
+  const closeIdx = open === null ? -1 : xml.indexOf("</edge>", open.index);
+  if (open === null || closeIdx < 0) {
+    return { ok: false, error: `could not locate edge "${edgeId}" in the document text` };
+  }
+  const span = xml.slice(open.index, closeIdx);
+  const occurrences = span.match(EXTERNAL_ELEMENT) ?? [];
+  if (occurrences.length !== 1) {
+    return {
+      ok: false,
+      error: `edge "${edgeId}" does not contain exactly one external locator element`
+    };
+  }
+  const kind = request.kind ?? external.hintKind ?? (request.type === "implements" ? "code" : "test");
+  const title = request.title ?? external.title;
+  const titleAttr = title !== void 0 ? ` title="${escapeAttr(title)}"` : "";
+  const replacement = `<external uri="${escapeAttr(request.uri)}" kind="${escapeAttr(kind)}"${titleAttr}/>`;
+  const editedSpan = span.replace(occurrences[0], () => replacement);
+  const updated = xml.slice(0, open.index) + editedSpan + xml.slice(closeIdx);
+  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: `${editedSpan}</edge>`.trim(),
+    previousUri: external.uri
+  };
+}
+function collectTitles(doc) {
+  const m = /* @__PURE__ */ new Map();
+  const set = (id, title) => {
+    if (id !== void 0 && title !== void 0 && title !== "" && !m.has(id)) {
+      m.set(id, title);
+    }
+  };
+  for (const p of doc.meta.profiles ?? []) set(p.id, p.type);
+  const c = doc.catalogs;
+  if (c) {
+    for (const t of c.glossary ?? []) set(t.id, t.name);
+    for (const a of c.actors ?? []) set(a.id, a.name);
+    for (const s of c.stakeholders ?? []) set(s.id, s.name);
+    for (const x of c.constraints ?? []) set(x.id, x.statement);
+    for (const x of c.policies ?? []) set(x.id, x.obligation);
+    for (const x of c.decisions ?? []) set(x.id, x.decision);
+    for (const x of c.risks ?? []) set(x.id, x.statement);
+  }
+  const d = doc.domain;
+  if (d) {
+    for (const e of d.entities ?? []) {
+      set(e.id, e.name);
+      for (const a of e.attrs ?? []) set(a.id, a.name);
+    }
+    for (const r of d.businessRules ?? []) set(r.id, r.statement);
+  }
+  const g = doc.goals;
+  if (g) {
+    for (const x of g.goals ?? []) set(x.id, x.title);
+    for (const x of g.qualityGoals ?? []) set(x.id, x.title);
+    for (const x of g.obstacles ?? []) set(x.id, x.title);
+    for (const x of g.goalLinks ?? []) set(x.id, x.id);
+  }
+  const sc = doc.scenarios;
+  if (sc) {
+    for (const x of sc.scenarios ?? []) set(x.id, x.title);
+    for (const x of sc.misuseCases ?? []) set(x.id, x.title);
+    for (const x of sc.edgeCases ?? []) set(x.id, x.title);
+  }
+  for (const p of doc.packages) {
+    set(p.id, p.title);
+    for (const r of p.requirements) set(r.id, r.title);
+  }
+  for (const r of doc.looseRequirements) set(r.id, r.title);
+  const b = doc.behavior;
+  if (b) {
+    for (const sm of b.stateMachines ?? []) {
+      set(sm.id, sm.name);
+      for (const st of sm.states) set(st.id, st.name);
+    }
+  }
+  const it = doc.interfaces;
+  if (it) {
+    for (const api of it.apis ?? []) {
+      set(api.id, api.name);
+      for (const ep of api.endpoints ?? []) set(ep.id, `${ep.method} ${ep.path}`);
+    }
+    for (const ev of it.events ?? []) set(ev.id, ev.name);
+  }
+  const v = doc.verification;
+  if (v) {
+    for (const ts of v.testSuites ?? []) set(ts.id, ts.title);
+    for (const tc of v.testCases ?? []) set(tc.id, tc.title);
+  }
+  const gv = doc.governance;
+  if (gv) {
+    for (const x of gv.issues ?? []) set(x.id, x.statement);
+    for (const x of gv.approvals ?? []) set(x.id, x.role);
+  }
+  return m;
+}
 function endpointKey2(locator) {
   return locator.kind === "local" ? locator.id : locator.uri;
 }
@@ -3713,6 +3865,131 @@ function computeCoverage(doc) {
 function finding(source, rule, message) {
   return { source, severity: "warning", rule, message };
 }
+function refFromEndpoint(ep, titleById) {
+  const loc = ep.locator;
+  if (loc.kind === "local") {
+    const ref2 = { id: loc.id };
+    const title = ep.requirement?.title ?? loc.title ?? titleById.get(loc.id);
+    if (title !== void 0) ref2.title = title;
+    if (ep.target === void 0) ref2.broken = true;
+    return ref2;
+  }
+  const ref = {
+    id: loc.kind === "doc" ? `${loc.uri}#${loc.id}` : loc.uri,
+    external: true
+  };
+  if (loc.title !== void 0) ref.title = loc.title;
+  return ref;
+}
+function matches(row, filter) {
+  if (filter === void 0) return true;
+  if (filter.status && !filter.status.includes(row.status)) return false;
+  if (filter.type && !filter.type.includes(row.type)) return false;
+  if (filter.warning && !filter.warning.some((w) => row.warnings.includes(w)))
+    return false;
+  return true;
+}
+function buildMatrix(doc, filter) {
+  const cov = computeCoverage(doc);
+  const reqById = new Map(allRequirements(doc).map((r) => [r.id, r]));
+  const titleById = collectTitles(doc);
+  const edgeById = new Map(resolveTrace(doc).edges.map((re) => [re.edge.id, re]));
+  const unverified = new Set(cov.unverifiedRequirements);
+  const unimplemented = new Set(cov.unimplementedRequirements);
+  const orphans = new Set(cov.orphanRequirements);
+  const premature = new Set(cov.prematureImplementations.map((p) => p.requirementId));
+  const rows = [];
+  for (const ac of cov.requirements) {
+    const req = reqById.get(ac.id);
+    if (req === void 0) continue;
+    const goals = (ac.outgoing.satisfies ?? []).flatMap((edgeId) => {
+      const re = edgeById.get(edgeId);
+      return re ? [refFromEndpoint(re.to, titleById)] : [];
+    });
+    const implementations = (ac.incoming.implements ?? []).flatMap((edgeId) => {
+      const re = edgeById.get(edgeId);
+      return re ? [refFromEndpoint(re.from, titleById)] : [];
+    });
+    const tests = (ac.outgoing.verifiedBy ?? []).flatMap((edgeId) => {
+      const re = edgeById.get(edgeId);
+      return re ? [refFromEndpoint(re.to, titleById)] : [];
+    });
+    const verification = unverified.has(ac.id) ? "unverified" : "verified";
+    const implementation = premature.has(ac.id) ? "premature" : unimplemented.has(ac.id) ? "unimplemented" : "implemented";
+    const warnings = [];
+    if (unverified.has(ac.id)) warnings.push("unverified");
+    if (unimplemented.has(ac.id)) warnings.push("unimplemented");
+    if (orphans.has(ac.id)) warnings.push("orphan");
+    if (premature.has(ac.id)) warnings.push("premature");
+    if ([...goals, ...implementations, ...tests].some((r) => r.broken))
+      warnings.push("broken-trace");
+    const row = {
+      id: ac.id,
+      title: req.title,
+      type: req.type,
+      status: req.status ?? "draft",
+      goals,
+      implementations,
+      tests,
+      verification,
+      implementation,
+      warnings
+    };
+    if (req.priority !== void 0) row.priority = req.priority;
+    rows.push(row);
+  }
+  const kept = rows.filter((r) => matches(r, filter));
+  const summary = {
+    total: kept.length,
+    verified: kept.filter((r) => r.verification === "verified").length,
+    unverified: kept.filter((r) => r.verification === "unverified").length,
+    implemented: kept.filter((r) => r.implementation === "implemented").length,
+    unimplemented: kept.filter((r) => r.implementation === "unimplemented").length,
+    premature: kept.filter((r) => r.implementation === "premature").length,
+    orphans: kept.filter((r) => r.warnings.includes("orphan")).length,
+    brokenTraces: kept.filter((r) => r.warnings.includes("broken-trace")).length
+  };
+  return { rows: kept, summary };
+}
+function escapeCell2(value) {
+  return value.replace(/\|/g, "\\|").replace(/\n/g, " ");
+}
+function refLabel(r) {
+  const base = r.title !== void 0 ? `${r.id} (${r.title})` : r.id;
+  return r.broken ? `${base} [broken]` : base;
+}
+function matrixToMarkdown(report) {
+  const s = report.summary;
+  const lines = [
+    "# Traceability matrix",
+    "",
+    `- **Requirements:** ${s.total}`,
+    `- **Verified:** ${s.verified} \xB7 **Unverified:** ${s.unverified}`,
+    `- **Implemented:** ${s.implemented} \xB7 **Unimplemented:** ${s.unimplemented} \xB7 **Premature:** ${s.premature}`,
+    `- **Orphans:** ${s.orphans} \xB7 **Broken traces:** ${s.brokenTraces}`,
+    "",
+    "| ID | Title | Type | Status | Verify | Impl | Goals | Implemented by | Verified by | Warnings |",
+    "| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |"
+  ];
+  for (const row of report.rows) {
+    const cells = [
+      row.id,
+      row.title,
+      row.type,
+      row.status,
+      row.verification,
+      row.implementation,
+      row.goals.map(refLabel).join(", "),
+      row.implementations.map(refLabel).join(", "),
+      row.tests.map(refLabel).join(", "),
+      row.warnings.join(", ")
+    ].map(escapeCell2);
+    lines.push(`| ${cells.join(" | ")} |`);
+  }
+  while (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
+  return `${lines.join("\n")}
+`;
+}
 var BASELINE_PATH = ".rqml/baseline.json";
 function hashFileAt(filePath) {
   try {
@@ -4010,7 +4287,7 @@ async function runImpact(rest) {
 }
 
 // ../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## 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_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/ and the development process at https://rqml.org/docs/development-process/\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\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\nRQML organizes work into a **five-stage process** (https://rqml.org/docs/development-process/). Each stage produces a durable artifact in version control; verification feeds back to the spec, so it is a loop:\n\n| Stage | Task | Output |\n|-------|------|--------|\n| **Spec** | Capture intent as requirements | `requirements.rqml` |\n| **Design** | Decide architecture, record decisions | ADRs in `.rqml/adr/` |\n| **Plan** | Break work into agent-sized stages | `.rqml/plan.md` |\n| **Code** | Implement specified behavior, keep traces current | code + tests |\n| **Verify** | Prove coverage and catch drift | trace graph + `rqml check` |\n\nNever skip ahead: do not implement behavior that is not specified, and do not make a significant architectural choice without recording it as an ADR.\n\n---\n\n## Workflow\n\n### 1. Spec\nAsk clarifying questions until you understand the goal, scope, acceptance criteria, and constraints. Don\'t assume\u2014capture assumptions as `<notes>` or `<issue>` elements. **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; only `status="approved"` requirements drive implementation\n\n### 2. Design\nBefore building, decide *how*. Record each significant architectural decision as an **Architecture Decision Record (ADR)** in `.rqml/adr/`, following the canonical format (https://rqml.org/docs/development-process/design): `NNNN-kebab-case-slug.md`, with Status, Classification, Context, Options considered, Decision, and Consequences. A decision is ADR-worthy when there are real alternatives or the choice constrains future work; skip ADRs for low-level implementation details. ADRs are immutable once accepted\u2014supersede, don\'t edit.\n\n### 3. Plan\nBreak approved requirements into a staged implementation plan at `.rqml/plan.md`, framed for coding agents: each stage names its goal, the requirement IDs it addresses, the files it touches, and how to verify it.\n\n### 4. Code (Implement)\nRead the requirement first: `rqml show REQ-XXX`. Check blast radius before changing existing artifacts: `rqml impact REQ-XXX`. Honor the ADRs. 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### 5. Verify\nAdd tests that reference requirement IDs, then record verification and run the gate:\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| Spec (elicitation) | Major features | Testable reqs | Edge cases | Formal |\n| Spec-first | Recommended | Required | Required | Approved first |\n| Design (ADRs) | Optional | Significant choices | All architectural choices | With approval |\n| Plan | Optional | For multi-stage work | Required | Required |\n| Code traces | Optional | New features | All changes | With metadata |\n| Verify (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**Design:** ADR-xxxx \u2014 decision recorded (if any)\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
@@ -4053,15 +4330,21 @@ 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>]";
+var USAGE = "usage: rqml link <artifact-id> <uri> [--update] [--type implements|verifiedBy] [--id <edge-id>] [--kind <k>] [--title <t>] [--spec <path>]\n       rqml link --refresh <edge-id> [--spec <path>]";
 async function runLink(rest) {
   const args = parseArgs(rest);
+  if (args.flags.has("refresh")) {
+    const edgeId2 = flagString(args, "refresh");
+    if (edgeId2 === void 0) throw new UsageError(USAGE);
+    return runRefresh(args, edgeId2);
+  }
   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 update = args.flags.get("update") === true || args.flags.get("update") === "true";
   const { path, xml } = readSpec(specArgs(args));
   const request = { artifactId, uri, type };
   const edgeId = flagString(args, "id");
@@ -4070,7 +4353,7 @@ async function runLink(rest) {
   if (kind !== void 0) request.kind = kind;
   const title = flagString(args, "title");
   if (title !== void 0) request.title = title;
-  const result = appendTraceEdge(xml, request);
+  const result = update ? updateTraceEdge(xml, request) : appendTraceEdge(xml, request);
   if (!result.ok) {
     process.stderr.write(`\u2717 link failed: ${result.error}
 `);
@@ -4099,6 +4382,7 @@ async function runLink(rest) {
   if (args.json) {
     const report = {
       spec: path,
+      mode: update ? "update" : "append",
       edgeId: result.edgeId,
       type,
       artifactId,
@@ -4109,12 +4393,81 @@ async function runLink(rest) {
 `);
   } else {
     const arrow = type === "implements" ? "\u2190" : "\u2192";
+    const mode = update ? ", updated" : "";
     const baseline = baselineRecorded ? ", baseline recorded" : "";
     process.stdout.write(
-      `\u2713 ${artifactId} ${arrow} ${uri} (${result.edgeId}, ${type}${baseline})
+      `\u2713 ${artifactId} ${arrow} ${uri} (${result.edgeId}, ${type}${mode}${baseline})
+`
+    );
+  }
+  return EXIT.OK;
+}
+function runRefresh(args, edgeId) {
+  const { path, xml } = readSpec(specArgs(args));
+  const parsed = parse(xml);
+  if (!parsed.ok) {
+    process.stderr.write(`\u2717 refresh failed: ${parsed.error.message}
+`);
+    return EXIT.VALIDATION;
+  }
+  const link = implementsLinks(parsed.document).find((l) => l.edgeId === edgeId);
+  if (link === void 0) {
+    process.stderr.write(
+      `\u2717 refresh failed: no implements edge "${edgeId}" with an external locator exists (only implements edges carry baselines)
 `
     );
+    return EXIT.VALIDATION;
   }
+  const hash = computeBaseline(parsed.document, { baseDir: args.baseDir })[edgeId];
+  if (hash === void 0) {
+    process.stderr.write(
+      `\u2717 refresh failed: "${link.uri}" cannot be hashed (missing file or non-filesystem URI)
+`
+    );
+    return EXIT.VALIDATION;
+  }
+  const baseline = loadBaseline(args.baseDir) ?? {};
+  baseline[edgeId] = hash;
+  saveBaseline(args.baseDir, baseline);
+  if (args.json) {
+    const report = { spec: path, mode: "refresh", edgeId, uri: link.uri, hash };
+    process.stdout.write(`${JSON.stringify(report, null, 2)}
+`);
+  } else {
+    process.stdout.write(`\u2713 baseline refreshed for ${edgeId} (${link.uri})
+`);
+  }
+  return EXIT.OK;
+}
+
+// src/commands/matrix.ts
+function list(value) {
+  if (value === void 0) return void 0;
+  const items = value.split(",").map((s) => s.trim()).filter(Boolean);
+  return items.length > 0 ? items : void 0;
+}
+async function runMatrix(rest) {
+  const args = parseArgs(rest);
+  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 status = list(flagString(args, "status"));
+  const type = list(flagString(args, "type"));
+  const warning = list(flagString(args, "warning"));
+  const filter = {};
+  if (status) filter.status = status;
+  if (type) filter.type = type;
+  if (warning) filter.warning = warning;
+  const filtered = status !== void 0 || type !== void 0 || warning !== void 0;
+  const matrix = buildMatrix(parsed.document, filtered ? filter : void 0);
+  process.stdout.write(
+    args.json ? `${JSON.stringify(matrix, null, 2)}
+` : matrixToMarkdown(matrix)
+  );
   return EXIT.OK;
 }
 
@@ -4234,7 +4587,7 @@ async function runValidate(rest) {
 }
 
 // src/index.ts
-var VERSION = "0.1.0";
+var VERSION = createRequire(import.meta.url)("../package.json").version;
 var HELP = `rqml \u2014 RQML reference CLI (v${VERSION})
 
 Usage:
@@ -4246,12 +4599,16 @@ Commands:
   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
+                     (--update repoints an existing edge; --refresh <edge-id>
+                     re-records only the baseline for an intentional change)
   show <id>          Extract one artifact with its trace neighborhood
   impact <id>        What is affected, transitively, if this artifact changes
+  matrix [path]      Traceability matrix: status, goals, code, tests, warnings
   skeleton <kind>    Print a schema-valid snippet (req|edge|testCase|stateMachine)
 
 Options:
-  --json                 Emit machine-readable JSON (status, check, validate, link, show, impact)
+  --json                 Emit machine-readable JSON (status, check, validate, link, show, impact, matrix)
+  --status/--type/--warning  Filter matrix rows (comma-separated, e.g. --warning unverified)
   --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)
@@ -4259,6 +4616,8 @@ Options:
   --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
+  --update               Replace the external locator of an existing edge (link)
+  --refresh <edge-id>    Re-record the drift baseline for one edge (link)
   -h, --help             Show this help
   -v, --version          Show version
 
@@ -4281,6 +4640,8 @@ async function main(argv) {
       return runShow(rest);
     case "impact":
       return runImpact(rest);
+    case "matrix":
+      return runMatrix(rest);
     case "skeleton":
       return runSkeleton(rest);
     case "-v":