@rqml/schema 0.1.0

package/examples/warehouse_robots.rqml

@@ -0,0 +1,158 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<rqml xmlns="https://rqml.org/schema/2.1.0"
+      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+      xsi:schemaLocation="https://rqml.org/schema/2.1.0 https://rqml.org/schema/rqml-2.1.0.xsd"
+      version="2.1.0" docId="ROBOT-001" status="draft">
+  <meta>
+    <title>Autonomous Warehouse Robots</title>
+    <system>FleetControl</system>
+    <summary>Fleet coordination, task assignment, and safety controls for warehouse AMRs.</summary>
+    <authors>
+      <author>
+        <name>Alex Morgan</name>
+        <role>Systems</role>
+      </author>
+    </authors>
+  </meta>
+
+  <catalogs>
+    <risks>
+      <risk id="RISK-COLLISION" severity="critical">
+        <statement>Collision between robots or with humans.</statement>
+        <mitigation>Real-time obstacle detection and braking.</mitigation>
+      </risk>
+    </risks>
+    <decisions>
+      <decision id="DEC-PLANNER" status="approved">
+        <context>Path planning approach</context>
+        <decision>Use A* with dynamic replanning</decision>
+      </decision>
+    </decisions>
+  </catalogs>
+
+  <domain>
+    <entities>
+      <entity id="ENT-ROBOT" name="Robot">
+        <attr id="ATTR-ID" name="robotId" type="uuid" required="true"/>
+        <attr id="ATTR-STATE" name="state" type="token" required="true"/>
+      </entity>
+      <entity id="ENT-TASK" name="Task">
+        <attr id="ATTR-TASK-ID" name="taskId" type="uuid" required="true"/>
+        <attr id="ATTR-PRIORITY" name="priority" type="token" required="false"/>
+      </entity>
+      <entity id="ENT-ZONE" name="Zone">
+        <attr id="ATTR-NAME" name="name" type="string" required="true"/>
+      </entity>
+    </entities>
+  </domain>
+
+  <goals>
+    <goal id="GOAL-THROUGHPUT" title="High throughput" priority="must">
+      <statement>Maximize picks per hour without sacrificing safety.</statement>
+    </goal>
+    <qgoal id="QGOAL-SAFETY" title="Safety" priority="must">
+      <statement>Zero collisions during operations.</statement>
+    </qgoal>
+  </goals>
+
+  <scenarios>
+    <scenario id="SCN-PICK" title="Pick and deliver">
+      <narrative>A robot receives a pick task and delivers items to a pack station.</narrative>
+    </scenario>
+    <edgeCase id="SCN-OBST" title="Obstacle in path">
+      <narrative>A robot encounters an unexpected obstacle mid-route.</narrative>
+    </edgeCase>
+  </scenarios>
+
+  <requirements>
+    <reqPackage id="PKG-FLEET" title="Fleet control">
+      <req id="REQ-ASSIGN" type="FR" title="Assign tasks" priority="must">
+        <statement>The system SHALL assign tasks to available robots based on proximity and load.</statement>
+        <acceptance>
+          <criterion id="CRIT-ASSIGN-1">
+            <when>A new task is created</when>
+            <then>It is assigned to an available robot within 2 seconds.</then>
+          </criterion>
+        </acceptance>
+      </req>
+      <req id="REQ-AVOID" type="SR" title="Collision avoidance" priority="must">
+        <statement>Robots SHALL detect obstacles and brake to avoid collision.</statement>
+        <acceptance>
+          <criterion id="CRIT-AVOID-1">
+            <when>An obstacle enters the safety radius</when>
+            <then>The robot decelerates and stops before impact.</then>
+          </criterion>
+        </acceptance>
+      </req>
+      <req id="REQ-LOG" type="DR" title="Telemetry logging" priority="should">
+        <statement>Robots SHALL log position, velocity, and battery every second.</statement>
+      </req>
+      <req id="REQ-RECOVERY" type="OR" title="Recovery" priority="should">
+        <statement>The system SHALL reassign tasks from offline robots within 5 seconds.</statement>
+      </req>
+    </reqPackage>
+  </requirements>
+
+  <interfaces>
+    <api id="API-CONTROL" name="Control API" protocol="https" auth="mTLS">
+      <endpoint id="EP-ASSIGN" method="POST" path="/tasks">
+        <summary>Create and assign a task.</summary>
+        <response>taskId, assignedRobotId</response>
+      </endpoint>
+      <endpoint id="EP-HEARTBEAT" method="POST" path="/robots/{id}/heartbeat">
+        <summary>Report robot telemetry.</summary>
+        <request>position, velocity, battery</request>
+        <response>200 ack</response>
+      </endpoint>
+    </api>
+    <event id="EVT-OBST" name="ObstacleDetected">
+      <description>Emitted when a robot detects an obstacle.</description>
+      <payload>robotId, position, timestamp</payload>
+    </event>
+  </interfaces>
+
+  <verification>
+    <testCase id="TC-ASSIGN" type="integration" title="Task assigned quickly">
+      <expected>Assignment occurs within 2 seconds</expected>
+    </testCase>
+    <testCase id="TC-AVOID" type="inspection" title="Obstacle avoidance">
+      <steps>Inject obstacle at 2m ahead during motion</steps>
+      <expected>Robot brakes and stops before impact</expected>
+    </testCase>
+  </verification>
+
+  <trace>
+    <edge id="TR-ASSIGN" type="satisfies">
+      <from><locator><local id="REQ-ASSIGN"/></locator></from>
+      <to><locator><local id="GOAL-THROUGHPUT"/></locator></to>
+    </edge>
+    <edge id="TR-ASSIGN-SCN" type="satisfies">
+      <from><locator><local id="REQ-ASSIGN"/></locator></from>
+      <to><locator><local id="SCN-PICK"/></locator></to>
+    </edge>
+    <edge id="TR-ASSIGN-ENT" type="dependsOn">
+      <from><locator><local id="REQ-ASSIGN"/></locator></from>
+      <to><locator><local id="ENT-TASK"/></locator></to>
+    </edge>
+    <edge id="TR-AVOID" type="satisfies">
+      <from><locator><local id="REQ-AVOID"/></locator></from>
+      <to><locator><local id="QGOAL-SAFETY"/></locator></to>
+    </edge>
+    <edge id="TR-AVOID-SCN" type="satisfies">
+      <from><locator><local id="REQ-AVOID"/></locator></from>
+      <to><locator><local id="SCN-OBST"/></locator></to>
+    </edge>
+    <edge id="TR-RISK" type="mitigates">
+      <from><locator><local id="REQ-AVOID"/></locator></from>
+      <to><locator><local id="RISK-COLLISION"/></locator></to>
+    </edge>
+    <edge id="TR-ASSIGN-TEST" type="verifiedBy">
+      <from><locator><local id="REQ-ASSIGN"/></locator></from>
+      <to><locator><local id="TC-ASSIGN"/></locator></to>
+    </edge>
+    <edge id="TR-AVOID-TEST" type="verifiedBy">
+      <from><locator><local id="REQ-AVOID"/></locator></from>
+      <to><locator><local id="TC-AVOID"/></locator></to>
+    </edge>
+  </trace>
+</rqml>

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@rqml/schema",
+  "version": "0.1.0",
+  "description": "Canonical RQML XSD schemas (the single source of truth), example documents, and the AGENTS.md template, with a typed version resolver. Schema text is inlined for offline, bundler-friendly consumption.",
+  "type": "module",
+  "license": "Apache-2.0",
+  "author": "Gardar Gudgeirsson",
+  "keywords": [
+    "rqml",
+    "schema",
+    "xsd",
+    "requirements"
+  ],
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "versions",
+    "examples",
+    "templates"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./versions/*": "./versions/*",
+    "./examples/*": "./examples/*",
+    "./templates/*": "./templates/*",
+    "./package.json": "./package.json"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "dev": "vitest"
+  }
+}

package/templates/AGENTS.md

@@ -0,0 +1,109 @@
+# RQML Agent Guidelines
+
+## Strictness: `standard`
+
+| Level | Description |
+|-------|-------------|
+| `relaxed` | Prototyping. Spec is advisory. Quick iteration allowed. |
+| `standard` | Production default. Spec-first for features. Core traces. |
+| `strict` | Full traceability. All behavior specified. No ghost features. |
+| `certified` | Regulated/safety-critical. Audit-grade traces with metadata. |
+
+---
+
+This project uses **RQML** as the single source of truth for system intent. Familiarize yourself with the documentation at https://rqml.org/docs/user-guide/
+
+**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.
+
+**Schema file:**
+The 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.
+
+---
+
+## Core Principle: Spec-First Development
+
+```
+[Elicit] → [Specify] → [Implement] → [Verify] → [Trace]
+    ↑____________________←______________________|
+```
+
+Code follows specification, not the reverse. If code and spec diverge, the spec is authoritative—update the code or negotiate a spec change with the developer.
+
+---
+
+## Workflow
+
+### 1. Elicit
+Ask clarifying questions until you understand the goal, scope, acceptance criteria, and constraints. Don't assume—capture assumptions as `<notes>` or `<issue>` elements.
+
+### 2. Specify
+**Never implement unspecified behavior.** Update the `.rqml` file before coding:
+- Add a `<req>` with statement and acceptance criteria
+- Set appropriate `type`, `priority`, and `status="draft"`
+- Get developer confirmation before proceeding
+
+### 3. Implement
+Reference requirement IDs in code comments. If you discover missing requirements, stop and add them to the spec first.
+
+### 4. Verify
+Add tests that reference requirement IDs. Update `<trace>` section with verification links.
+
+---
+
+## When Code and Spec Diverge
+
+1. **Spec gap** (code has behavior not in spec): Propose adding the requirement, mark as `status="review"`
+2. **Code bug** (code doesn't match spec): Fix the code
+3. **Spec bug** (spec is wrong): Propose correction, wait for developer confirmation
+
+**Never silently change the spec to match code.**
+
+---
+
+## Strictness Reference
+
+| Aspect | relaxed | standard | strict | certified |
+|--------|---------|----------|--------|-----------|
+| Elicitation | Major features | Testable reqs | Edge cases | Formal |
+| Spec-first | Recommended | Required | Required | Approved first |
+| Code traces | Optional | New features | All changes | With metadata |
+| Test traces | Optional | New reqs | All reqs | Full matrix |
+| Ghost features | Allowed | Blocked | Blocked | Blocked |
+
+---
+
+## Change Summary Template
+
+For PRs and commits:
+
+```
+## RQML Trace Summary
+
+**Requirements:** REQ-xxx (added/modified/implemented)
+**Implementation:** `path/to/file` — what changed
+**Verification:** `path/to/test` — what it verifies
+**Open items:** gaps, assumptions, follow-ups
+```
+
+---
+
+## Schema Validation
+
+The `.rqml` file must remain valid XML conforming to the version of RQML referenced in the version attribute in the spec document.
+
+**To validate:** Try xmllint first (pre-installed on macOS/Linux):
+```bash
+xmllint --schema https://rqml.org/schema/rqml-2.1.0.xsd <rqml-file-name> --noout
+```
+
+If xmllint is unavailable, use Python with lxml:
+```bash
+pip install lxml
+python -c "from lxml import etree; s=etree.XMLSchema(etree.parse('https://rqml.org/schema/rqml-2.1.0.xsd')); print('Valid' if s.validate(etree.parse('<rqml-file-name>')) else s.error_log)"
+```
+
+**IDE validation:** If the `.rqml` file includes `xsi:schemaLocation`, XML-aware editors (VS Code with XML extension, IntelliJ) validate automatically.
+
+The schema comments contain detailed guidance on document structure, ID conventions, and requirement quality criteria.
+
+**If unsure:** Ask the developer before making structural changes to the spec.