@rqml/cli 0.4.1 → 0.5.0

package/dist/index.js

@@ -1,8 +1,8 @@
 #!/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 { createHash } from 'crypto';
 import { resolve, join, dirname, isAbsolute } from 'path';
 import { fileURLToPath } from 'url';
 
@@ -3453,6 +3453,18 @@ function updateTraceEdge(xml, request) {
     previousUri: external.uri
   };
 }
+function fields(...pairs) {
+  const out = [];
+  for (const [label, value] of pairs) {
+    if (value !== void 0 && value !== "") out.push({ label, value });
+  }
+  return out;
+}
+function locatorLabel(loc) {
+  if (loc.kind === "local") return loc.id;
+  if (loc.kind === "doc") return `${loc.uri}#${loc.id}`;
+  return loc.uri;
+}
 function collectTitles(doc) {
   const m = /* @__PURE__ */ new Map();
   const set = (id, title) => {
@@ -3524,206 +3536,632 @@ function collectTitles(doc) {
   }
   return m;
 }
-function endpointKey2(locator) {
-  return locator.kind === "local" ? locator.id : locator.uri;
+function endpointTitle(ep, titleById) {
+  if (ep.requirement !== void 0) return ep.requirement.title;
+  if (ep.locator.title !== void 0) return ep.locator.title;
+  if (ep.locator.kind === "local") return titleById.get(ep.locator.id);
+  return void 0;
 }
-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 endpointLabel(ep, titleById) {
+  let s = locatorLabel(ep.locator);
+  const hint = endpointTitle(ep, titleById);
+  if (hint !== void 0) s += ` (${hint})`;
+  if (ep.locator.kind === "local" && ep.target === void 0) s += " [unresolved]";
+  return s;
 }
-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)
+function buildOutline(doc) {
+  const res = resolveTrace(doc);
+  const titleById = collectTitles(doc);
+  const refsBySource = /* @__PURE__ */ new Map();
+  for (const re of res.edges) {
+    if (re.from.locator.kind !== "local") continue;
+    const toLoc = re.to.locator;
+    const targetId = toLoc.kind === "local" ? toLoc.id : toLoc.uri;
+    const resolved = toLoc.kind === "local" ? re.to.target !== void 0 : true;
+    const ref = { relation: re.edge.type, targetId, resolved };
+    const tt = endpointTitle(re.to, titleById);
+    if (tt !== void 0) ref.targetTitle = tt;
+    const arr = refsBySource.get(re.from.locator.id);
+    if (arr) arr.push(ref);
+    else refsBySource.set(re.from.locator.id, [ref]);
+  }
+  const node = (kind, id, title, flds, children) => {
+    const n = { kind, title, fields: flds };
+    if (id !== void 0) n.id = id;
+    const refs = id !== void 0 ? refsBySource.get(id) : void 0;
+    if (refs && refs.length > 0) n.refs = refs;
+    if (children && children.length > 0) n.children = children;
+    return n;
+  };
+  const sections = [];
+  const pushSection = (title, flds, nodes) => {
+    if (flds.length === 0 && nodes.length === 0) return;
+    const s = { kind: "section", title, fields: flds };
+    if (nodes.length > 0) s.children = nodes;
+    sections.push(s);
+  };
+  const meta = doc.meta;
+  pushSection(
+    "Meta",
+    fields(
+      ["Created", meta.dates?.created],
+      ["Updated", meta.dates?.updated],
+      ["Target release", meta.dates?.targetRelease],
+      ["Normative keywords", meta.conventions?.normativeKeywords],
+      ["ID conventions", meta.conventions?.idConventions]
+    ),
+    (meta.profiles ?? []).map(
+      (p) => node("profile", p.id, p.type, fields(["Description", p.description]))
+    )
+  );
+  const cat = doc.catalogs;
+  if (cat) {
+    pushSection(
+      "Glossary",
+      [],
+      (cat.glossary ?? []).map(
+        (t) => node(
+          "term",
+          t.id,
+          t.name,
+          fields(["Definition", t.definition], ["Synonyms", t.synonyms?.join(", ")])
+        )
+      )
+    );
+    pushSection(
+      "Actors",
+      [],
+      (cat.actors ?? []).map(
+        (a) => node(
+          "actor",
+          a.id,
+          a.name,
+          fields(
+            ["Type", a.type],
+            ["Description", a.description],
+            ["Goal refs", a.goalRefs?.join(", ")]
+          )
+        )
+      )
+    );
+    pushSection(
+      "Stakeholders",
+      [],
+      (cat.stakeholders ?? []).map(
+        (s) => node(
+          "stakeholder",
+          s.id,
+          s.name,
+          fields(["Org", s.org], ["Concerns", s.concerns])
+        )
+      )
+    );
+    pushSection(
+      "Constraints",
+      [],
+      (cat.constraints ?? []).map(
+        (c) => node(
+          "constraint",
+          c.id,
+          c.statement,
+          fields(["Severity", c.severity], ["Source", c.source])
+        )
+      )
+    );
+    pushSection(
+      "Policies",
+      [],
+      (cat.policies ?? []).map(
+        (p) => node(
+          "policy",
+          p.id,
+          p.obligation,
+          fields(["Source", p.source], ["Evidence", p.evidence])
+        )
+      )
+    );
+    pushSection(
+      "Decisions",
+      [],
+      (cat.decisions ?? []).map(
+        (d) => node(
+          "decision",
+          d.id,
+          d.decision,
+          fields(
+            ["Status", d.status],
+            ["Context", d.context],
+            ["Alternatives", d.alternatives],
+            ["Consequences", d.consequences]
+          )
+        )
+      )
+    );
+    pushSection(
+      "Risks",
+      [],
+      (cat.risks ?? []).map(
+        (r) => node(
+          "risk",
+          r.id,
+          r.statement,
+          fields(["Severity", r.severity], ["Mitigation", r.mitigation])
+        )
+      )
     );
-    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);
+  const dom = doc.domain;
+  if (dom) {
+    const entityNodes = (dom.entities ?? []).map(
+      (e) => node(
+        "entity",
+        e.id,
+        e.name,
+        fields(["Description", e.description]),
+        (e.attrs ?? []).map(
+          (a) => node(
+            "attr",
+            a.id,
+            a.name,
+            fields(
+              ["Type", a.type],
+              ["Required", a.required === void 0 ? void 0 : String(a.required)],
+              ["Description", a.description],
+              ["Constraints", a.constraints]
+            )
+          )
+        )
+      )
+    );
+    const ruleNodes = (dom.businessRules ?? []).map(
+      (r) => node("rule", r.id, r.statement, fields(["Examples", r.examples]))
+    );
+    pushSection("Domain", fields(["Overview", dom.overview]), [
+      ...entityNodes,
+      ...ruleNodes
+    ]);
+  }
+  const goals = doc.goals;
+  if (goals) {
+    pushSection(
+      "Goals",
+      [],
+      (goals.goals ?? []).map(
+        (g) => node(
+          "goal",
+          g.id,
+          g.title,
+          fields(
+            ["Priority", g.priority],
+            ["Status", g.status],
+            ["Owner", g.ownerRef],
+            ["Statement", g.statement],
+            ["Rationale", g.rationale]
+          )
+        )
+      )
+    );
+    pushSection(
+      "Quality goals",
+      [],
+      (goals.qualityGoals ?? []).map(
+        (g) => node(
+          "qgoal",
+          g.id,
+          g.title,
+          fields(
+            ["Priority", g.priority],
+            ["Status", g.status],
+            ["Statement", g.statement],
+            ["Metric", g.metric]
+          )
+        )
+      )
+    );
+    pushSection(
+      "Obstacles",
+      [],
+      (goals.obstacles ?? []).map(
+        (o) => node(
+          "obstacle",
+          o.id,
+          o.title,
+          fields(
+            ["Likelihood", o.likelihood],
+            ["Severity", o.severity],
+            ["Statement", o.statement],
+            ["Mitigation", o.mitigation]
+          )
+        )
+      )
+    );
+    pushSection(
+      "Goal links",
+      [],
+      (goals.goalLinks ?? []).map(
+        (l) => node(
+          "goalLink",
+          l.id,
+          l.id,
+          fields(
+            ["From", l.from],
+            ["To", l.to],
+            ["Type", l.type],
+            ["Confidence", l.confidence?.toString()]
+          )
+        )
+      )
+    );
   }
-  return slice;
+  const sc = doc.scenarios;
+  if (sc) {
+    const scNode = (kind) => (s) => node(
+      kind,
+      s.id,
+      s.title,
+      fields(["Actor", s.actorRef], ["Narrative", s.narrative])
+    );
+    pushSection("Scenarios", [], (sc.scenarios ?? []).map(scNode("scenario")));
+    pushSection("Misuse cases", [], (sc.misuseCases ?? []).map(scNode("misuseCase")));
+    pushSection("Edge cases", [], (sc.edgeCases ?? []).map(scNode("edgeCase")));
+  }
+  const criterionNode = (c) => node(
+    "criterion",
+    c.id,
+    c.id ?? "Acceptance criterion",
+    fields(["Given", c.given], ["When", c.when], ["Then", c.then])
+  );
+  const reqNode = (r) => node(
+    "req",
+    r.id,
+    r.title,
+    fields(
+      ["Type", r.type],
+      ["Status", r.status],
+      ["Priority", r.priority],
+      ["Owner", r.ownerRef],
+      ["Applies to", r.appliesTo],
+      ["Statement", r.statement],
+      ["Rationale", r.rationale],
+      ["Notes", r.notes]
+    ),
+    r.acceptance.map(criterionNode)
+  );
+  const reqNodes = [
+    ...doc.packages.map(
+      (p) => node(
+        "reqPackage",
+        p.id,
+        p.title,
+        fields(["Owner", p.ownerRef], ["Description", p.description]),
+        p.requirements.map(reqNode)
+      )
+    ),
+    ...doc.looseRequirements.map(reqNode)
+  ];
+  pushSection("Requirements", [], reqNodes);
+  const beh = doc.behavior;
+  if (beh) {
+    pushSection(
+      "Behavior",
+      [],
+      (beh.stateMachines ?? []).map(
+        (sm) => node(
+          "stateMachine",
+          sm.id,
+          sm.name,
+          fields(
+            ["Initial", sm.initial],
+            ["Entity", sm.entityRef],
+            ["Description", sm.description]
+          ),
+          [
+            ...sm.states.map(
+              (st) => node(
+                "state",
+                st.id,
+                st.name,
+                fields(
+                  ["Type", st.type],
+                  ["Description", st.description],
+                  ["On entry", st.onEntry],
+                  ["On exit", st.onExit],
+                  ["Invariant", st.invariant]
+                )
+              )
+            ),
+            ...(sm.transitions ?? []).map(
+              (tr) => node(
+                "transition",
+                tr.id,
+                `${tr.from} \u2192 ${tr.to}`,
+                fields(
+                  ["From", tr.from],
+                  ["To", tr.to],
+                  ["Event", tr.event],
+                  ["Trigger", tr.trigger],
+                  ["Guard", tr.guard],
+                  ["Action", tr.action],
+                  ["Description", tr.description]
+                )
+              )
+            )
+          ]
+        )
+      )
+    );
+  }
+  const ifaces = doc.interfaces;
+  if (ifaces) {
+    const apiNodes = (ifaces.apis ?? []).map(
+      (api) => node(
+        "api",
+        api.id,
+        api.name,
+        fields(
+          ["Protocol", api.protocol],
+          ["Auth", api.auth],
+          ["Description", api.description]
+        ),
+        (api.endpoints ?? []).map(
+          (ep) => node(
+            "endpoint",
+            ep.id,
+            `${ep.method} ${ep.path}`,
+            fields(
+              ["Summary", ep.summary],
+              ["Request", ep.request],
+              ["Response", ep.response],
+              ["Errors", ep.errors]
+            )
+          )
+        )
+      )
+    );
+    const eventNodes = (ifaces.events ?? []).map(
+      (ev) => node(
+        "event",
+        ev.id,
+        ev.name,
+        fields(["Description", ev.description], ["Payload", ev.payload])
+      )
+    );
+    pushSection("Interfaces", [], [...apiNodes, ...eventNodes]);
+  }
+  const ver = doc.verification;
+  if (ver) {
+    const suiteNodes = (ver.testSuites ?? []).map(
+      (ts) => node("testSuite", ts.id, ts.title, fields(["Description", ts.description]))
+    );
+    const caseNodes = (ver.testCases ?? []).map(
+      (tc) => node(
+        "testCase",
+        tc.id,
+        tc.title,
+        fields(
+          ["Type", tc.type],
+          ["Purpose", tc.purpose],
+          ["Steps", tc.steps],
+          ["Expected", tc.expected]
+        )
+      )
+    );
+    pushSection("Verification", [], [...suiteNodes, ...caseNodes]);
+  }
+  const edgeNodes = res.edges.map((re) => {
+    const e = re.edge;
+    return node(
+      "edge",
+      e.id,
+      e.id,
+      fields(
+        ["Type", e.type],
+        ["From", endpointLabel(re.from, titleById)],
+        ["To", endpointLabel(re.to, titleById)],
+        ["Confidence", e.confidence?.toString()],
+        ["Status", e.status],
+        ["Created by", e.createdBy],
+        ["Created at", e.createdAt],
+        ["Tags", e.tags?.join(" ")],
+        ["Notes", e.notes]
+      )
+    );
+  });
+  pushSection("Trace", [], edgeNodes);
+  const gov = doc.governance;
+  if (gov) {
+    const issueNodes = (gov.issues ?? []).map(
+      (i) => node(
+        "issue",
+        i.id,
+        i.statement,
+        fields(["Status", i.status], ["Owner", i.owner], ["Notes", i.notes])
+      )
+    );
+    const approvalNodes = (gov.approvals ?? []).map(
+      (a) => node(
+        "approval",
+        a.id,
+        a.role,
+        fields(["Status", a.status], ["Description", a.description])
+      )
+    );
+    pushSection("Governance", [], [...issueNodes, ...approvalNodes]);
+  }
+  const outline = {
+    docId: doc.docId,
+    version: doc.version,
+    status: doc.status,
+    title: meta.title,
+    system: meta.system,
+    sections
+  };
+  if (meta.summary !== void 0) outline.summary = meta.summary;
+  return outline;
 }
-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})` : ""}`
+function escapeCell(value) {
+  return value.replace(/\|/g, "\\|").replace(/\n/g, " ");
+}
+function fieldValue(fields2, label) {
+  return fields2.find((f) => f.label === label)?.value ?? "";
+}
+function renderTraceTable(nodes) {
+  const lines = [
+    "| ID | Type | From | To | Status | Confidence |",
+    "| --- | --- | --- | --- | --- | --- |"
   ];
-  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()}`, "");
+  for (const n of nodes) {
+    const cells = [
+      n.id ?? "",
+      fieldValue(n.fields, "Type"),
+      fieldValue(n.fields, "From"),
+      fieldValue(n.fields, "To"),
+      fieldValue(n.fields, "Status"),
+      fieldValue(n.fields, "Confidence")
+    ].map(escapeCell);
+    lines.push(`| ${cells.join(" | ")} |`);
   }
-  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(" ")}`);
+  return lines;
+}
+function renderNode(node, depth, lines) {
+  const heading = "#".repeat(Math.min(depth, 6));
+  const idSuffix = node.id !== void 0 ? ` \`${node.id}\`` : "";
+  lines.push(`${heading} ${node.title}${idSuffix}`);
+  lines.push("");
+  for (const f of node.fields) {
+    lines.push(`- **${f.label}:** ${f.value}`);
+  }
+  if (node.refs && node.refs.length > 0) {
+    for (const r of node.refs) {
+      const title = r.targetTitle !== void 0 ? ` (${r.targetTitle})` : "";
+      const flag = r.resolved ? "" : " [unresolved]";
+      lines.push(`- _${r.relation}_ \u2192 \`${r.targetId}\`${title}${flag}`);
     }
+  }
+  if (node.fields.length > 0 || node.refs && node.refs.length > 0) {
     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}\`)`);
-    }
+  for (const child2 of node.children ?? []) {
+    renderNode(child2, depth + 1, lines);
+  }
+}
+function outlineToMarkdown(outline, opts = {}) {
+  const includeMetadata = opts.includeMetadata ?? true;
+  const traceAsTable = opts.traceAsTable ?? true;
+  const lines = [];
+  lines.push(`# ${outline.title}`);
+  lines.push("");
+  if (includeMetadata) {
+    lines.push(
+      `- **System:** ${outline.system}`,
+      `- **Document:** ${outline.docId} (v${outline.version}, ${outline.status})`
+    );
     lines.push("");
   }
-  return `${lines.join("\n").trimEnd()}
+  if (outline.summary !== void 0) {
+    lines.push(outline.summary, "");
+  }
+  for (const section of outline.sections) {
+    lines.push(`## ${section.title}`);
+    lines.push("");
+    for (const f of section.fields) {
+      lines.push(`- **${f.label}:** ${f.value}`);
+    }
+    if (section.fields.length > 0) lines.push("");
+    const children = section.children ?? [];
+    const isTrace = traceAsTable && children.length > 0 && children.every((c) => c.kind === "edge");
+    if (isTrace) {
+      lines.push(...renderTraceTable(children));
+      lines.push("");
+    } else {
+      for (const child2 of children) renderNode(child2, 3, lines);
+    }
+  }
+  while (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
+  return `${lines.join("\n")}
 `;
 }
-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])}
-`;
+function pruneById(node, ids) {
+  if (node.id !== void 0 && ids.has(node.id)) return node;
+  if (node.children) {
+    const kept = node.children.map((c) => pruneById(c, ids)).filter((c) => c !== void 0);
+    if (kept.length > 0) return { ...node, children: kept };
+  }
+  return void 0;
+}
+function projectOutline(outline, filter = {}) {
+  let sections = outline.sections;
+  if (filter.sections && filter.sections.length > 0) {
+    const want = new Set(filter.sections.map((s) => s.toLowerCase()));
+    sections = sections.filter((s) => want.has(s.title.toLowerCase()));
+  }
+  if (filter.ids && filter.ids.length > 0) {
+    const ids = new Set(filter.ids);
+    sections = sections.map((s) => pruneById(s, ids)).filter((s) => s !== void 0);
+  }
+  return { ...outline, sections };
+}
+var STATUS_VALUES = ["draft", "review", "approved", "deprecated"];
+function escapeRegExp3(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function setStatus(xml, request) {
+  if (!STATUS_VALUES.includes(request.status)) {
+    return {
+      ok: false,
+      error: `invalid status "${request.status}" (${STATUS_VALUES.join(" | ")})`
+    };
+  }
+  const parsed = parse(xml);
+  if (!parsed.ok) {
+    return { ok: false, error: `document does not parse: ${parsed.error.message}` };
+  }
+  const ref = declaredIdIndex(parsed.document).get(request.artifactId);
+  if (ref === void 0) {
+    return {
+      ok: false,
+      error: `artifact "${request.artifactId}" is not declared in the document`
+    };
+  }
+  const openTag = new RegExp(
+    `<${escapeRegExp3(ref.kind)}\\b[^>]*\\bid="${escapeRegExp3(request.artifactId)}"[^>]*>`
+  );
+  const match = openTag.exec(xml);
+  if (match === null) {
+    return {
+      ok: false,
+      error: `could not locate the <${ref.kind}> element for "${request.artifactId}" in the document text`
+    };
+  }
+  const tag = match[0];
+  const statusAttr = /\sstatus="([^"]*)"/;
+  const existing = statusAttr.exec(tag);
+  let newTag;
+  let previousStatus;
+  if (existing) {
+    previousStatus = existing[1];
+    if (previousStatus === request.status) return { ok: true, xml, previousStatus };
+    newTag = tag.replace(statusAttr, () => ` status="${request.status}"`);
+  } else {
+    const idAttr = `id="${request.artifactId}"`;
+    newTag = tag.replace(idAttr, () => `${idAttr} status="${request.status}"`);
+  }
+  const updated = xml.slice(0, match.index) + newTag + xml.slice(match.index + tag.length);
+  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 previousStatus !== void 0 ? { ok: true, xml: updated, previousStatus } : { ok: true, xml: updated };
 }
 var UPWARD_TARGET_KINDS = /* @__PURE__ */ new Set([
   "goal",
@@ -3865,6 +4303,235 @@ function computeCoverage(doc) {
 function finding(source, rule, message) {
   return { source, severity: "warning", rule, message };
 }
+function pathOf(uri) {
+  const hash = uri.indexOf("#");
+  return hash >= 0 ? uri.slice(0, hash) : uri;
+}
+function approvalGate(doc, opts = {}) {
+  const cov = computeCoverage(doc);
+  const changed = opts.changedPaths?.filter((p) => p.length > 0);
+  const findings = [];
+  for (const premature of cov.prematureImplementations) {
+    const edge = doc.trace.find((e) => e.id === premature.edgeId);
+    let uri;
+    if (edge) {
+      const external = edge.from.kind !== "local" ? edge.from : edge.to.kind !== "local" ? edge.to : void 0;
+      uri = external?.uri;
+    }
+    if (changed && changed.length > 0) {
+      if (uri === void 0) continue;
+      const p = pathOf(uri);
+      const hit = changed.some((c) => p === c || p.endsWith(c) || c.endsWith(p));
+      if (!hit) continue;
+    }
+    findings.push(
+      uri !== void 0 ? { edgeId: premature.edgeId, requirementId: premature.requirementId, uri } : { edgeId: premature.edgeId, requirementId: premature.requirementId }
+    );
+  }
+  findings.sort((a, b) => a.edgeId.localeCompare(b.edgeId));
+  return { blocked: findings.length > 0, findings };
+}
+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])}
+`;
+}
 function refFromEndpoint(ep, titleById) {
   const loc = ep.locator;
   if (loc.kind === "local") {
@@ -4092,17 +4759,6 @@ function detectDrift(doc, options = {}) {
   }
   return { links, drifted, diagnostics };
 }
-
-// src/report.ts
-function formatDiagnostic(d) {
-  const loc = d.line !== void 0 ? `:${d.line}${d.column !== void 0 ? `:${d.column}` : ""}` : "";
-  const rule = d.rule !== void 0 ? ` [${d.rule}]` : "";
-  return `  ${d.severity}${loc} (${d.source})${rule}: ${d.message}`;
-}
-function printDiagnostics(diags) {
-  for (const d of diags) process.stdout.write(`${formatDiagnostic(d)}
-`);
-}
 var EXIT = {
   OK: 0,
   /** The document is not well-formed, schema-invalid, or fails integrity. */
@@ -4181,6 +4837,46 @@ function readSpec(args) {
   return { path, xml: readFileSync(path, "utf8") };
 }
 
+// src/commands/approve.ts
+async function runApprove(rest) {
+  const args = parseArgs(rest);
+  const id = args.positionals[0];
+  if (id === void 0) {
+    throw new UsageError("usage: rqml approve <id> [--status approved] [--spec <path>]");
+  }
+  const { path, xml } = readSpec(specArgs(args));
+  const status = flagString(args, "status") ?? "approved";
+  const result = setStatus(xml, { artifactId: id, status });
+  if (!result.ok) {
+    process.stderr.write(`\u2717 ${result.error}
+`);
+    return EXIT.VALIDATION;
+  }
+  writeFileSync(path, result.xml);
+  if (args.json) {
+    const out = { ok: true, id, status, previousStatus: result.previousStatus ?? null };
+    process.stdout.write(`${JSON.stringify(out, null, 2)}
+`);
+  } else {
+    process.stdout.write(
+      `\u2713 ${id}: ${result.previousStatus ?? "(unset)"} \u2192 ${status} in ${path}
+`
+    );
+  }
+  return EXIT.OK;
+}
+
+// src/report.ts
+function formatDiagnostic(d) {
+  const loc = d.line !== void 0 ? `:${d.line}${d.column !== void 0 ? `:${d.column}` : ""}` : "";
+  const rule = d.rule !== void 0 ? ` [${d.rule}]` : "";
+  return `  ${d.severity}${loc} (${d.source})${rule}: ${d.message}`;
+}
+function printDiagnostics(diags) {
+  for (const d of diags) process.stdout.write(`${formatDiagnostic(d)}
+`);
+}
+
 // src/commands/check.ts
 function coverageBlocks(strictness) {
   return strictness === "strict" || strictness === "certified";
@@ -4240,6 +4936,39 @@ async function runCheck(rest) {
   return EXIT.OK;
 }
 
+// src/commands/gate.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 runGate(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 changed = list(flagString(args, "changed")) ?? (args.positionals.length > 0 ? args.positionals : void 0);
+  const verdict = approvalGate(parsed.document, changed ? { changedPaths: changed } : {});
+  if (args.json) {
+    process.stdout.write(`${JSON.stringify(verdict, null, 2)}
+`);
+  } else if (verdict.findings.length === 0) {
+    process.stdout.write("\u2713 no implementation linked to a non-approved requirement\n");
+  } else {
+    for (const f of verdict.findings) {
+      process.stdout.write(
+        `\u2717 ${f.uri ?? f.edgeId} implements ${f.requirementId}, which is not approved
+`
+      );
+    }
+  }
+  return verdict.blocked ? EXIT.CHECK : EXIT.OK;
+}
+
 // src/commands/impact.ts
 async function runImpact(rest) {
   const args = parseArgs(rest);
@@ -4287,7 +5016,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/ 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 matrix                # traceability matrix: status, goals, code, tests, coverage gaps\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_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 overview              # readable projection of the spec (--section/--id to scope)\nrqml matrix                # traceability matrix: status, goals, code, tests, coverage gaps\nrqml link <REQ-ID> <path>  # record an implements edge + drift baseline (--type verifiedBy for tests)\nrqml approve <REQ-ID>      # transition a requirement\'s status (default approved)\nrqml gate                  # block implementation of non-approved requirements\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
@@ -4441,7 +5170,7 @@ function runRefresh(args, edgeId) {
 }
 
 // src/commands/matrix.ts
-function list(value) {
+function list2(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;
@@ -4455,9 +5184,9 @@ async function runMatrix(rest) {
 `);
     return EXIT.VALIDATION;
   }
-  const status = list(flagString(args, "status"));
-  const type = list(flagString(args, "type"));
-  const warning = list(flagString(args, "warning"));
+  const status = list2(flagString(args, "status"));
+  const type = list2(flagString(args, "type"));
+  const warning = list2(flagString(args, "warning"));
   const filter = {};
   if (status) filter.status = status;
   if (type) filter.type = type;
@@ -4471,6 +5200,34 @@ async function runMatrix(rest) {
   return EXIT.OK;
 }
 
+// src/commands/overview.ts
+function list3(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 runOverview(rest) {
+  const args = parseArgs(rest);
+  const { path, xml } = readSpec(args);
+  const parsed = parse(xml);
+  if (!parsed.ok) {
+    process.stderr.write(`\u2717 ${path}: ${parsed.error.message}
+`);
+    return EXIT.VALIDATION;
+  }
+  const filter = {};
+  const sections = list3(flagString(args, "section"));
+  const ids = list3(flagString(args, "id"));
+  if (sections) filter.sections = sections;
+  if (ids) filter.ids = ids;
+  const outline = projectOutline(buildOutline(parsed.document), filter);
+  process.stdout.write(
+    args.json ? `${JSON.stringify(outline, null, 2)}
+` : outlineToMarkdown(outline)
+  );
+  return EXIT.OK;
+}
+
 // src/commands/show.ts
 async function runShow(rest) {
   const args = parseArgs(rest);
@@ -4602,13 +5359,18 @@ Commands:
                      (--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
+  overview [path]    Readable spec projection (whole, or --section/--id scoped)
   impact <id>        What is affected, transitively, if this artifact changes
   matrix [path]      Traceability matrix: status, goals, code, tests, warnings
+  approve <id>       Transition a requirement's status (--status, default approved)
+  gate [paths...]    Block implementation of non-approved requirements (exit 2)
   skeleton <kind>    Print a schema-valid snippet (req|edge|testCase|stateMachine)
 
 Options:
-  --json                 Emit machine-readable JSON (status, check, validate, link, show, impact, matrix)
-  --status/--type/--warning  Filter matrix rows (comma-separated, e.g. --warning unverified)
+  --json                 Emit machine-readable JSON (reporting commands)
+  --section, --id        Scope overview (comma-separated section titles or element ids)
+  --status, --type, --warning  Filter matrix rows; for approve, --status sets the target (default approved)
+  --changed <paths>      Scope gate to changed paths (or pass paths as positionals)
   --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)
@@ -4642,6 +5404,12 @@ async function main(argv) {
       return runImpact(rest);
     case "matrix":
       return runMatrix(rest);
+    case "overview":
+      return runOverview(rest);
+    case "approve":
+      return runApprove(rest);
+    case "gate":
+      return runGate(rest);
     case "skeleton":
       return runSkeleton(rest);
     case "-v":