This repository contains the data and source artifacts for our CNL and Value Conflict Detection Tool introduced in the paper HM-Req: A Framework for Embedding Values within CPS Human Monitoring Requirements accepted for publication in RE'26.
Monitoring humans, for example, their movement or location, is essential for safe and efficient human-machine collaboration in Cyber-Physical Systems (CPS). This information allows CPS to ensure safety properties, adapt their behaviour dynamically, and coordinate with humans. To ensure that the design of a CPS respects ethical principles and the privacy of its stakeholders, system requirements, particularly those related to human monitoring, must reflect the human values of all involved stakeholders.
However, human values are often underrepresented in Software Engineering -- particularly during requirements elicitation and system design, crucial phases when introducing ethically critical functionality.
Stakeholder values are often implicit and conflicting, yet rarely systematically captured. Furthermore, unstructured natural language requirements introduce ambiguity and vagueness, complicating conflict resolution.
To address these problems, we propose HM-Req, a novel requirements elicitation framework including a Controlled Natural Language (CNL) for defining human monitoring requirements. These requirements are then augmented with human values from relevant stakeholders and integrated into a Value Dashboard to detect potential conflicts that require further discussion and resolution.
Validation results, applying the CNL to different datasets and conducting a survey and expert interview, confirm the CNL's ability to capture diverse human monitoring requirements and demonstrate HM-Req's usefulness for requirements elicitation activities.
Note: This rest of this file was generated using LLMs and reviewed manually.
- Python project (pyproject.toml) targeting Python >= 3.13
- Django 5 web application in webapp with a reqs app to upload, list, edit, and manage requirements and their stakeholder/value associations
- HM-Req Language: A Controlled Natural Language (CNL) for writing monitoring requirements using EARS-style pre-statements and constrained verb taxonomy
- Evaluation: Evaluation artifacts across three research questions (RQ1, RQ2, RQ3) with datasets, surveys, and interviews
- Analysis Tools: Jupyter notebooks for requirements clustering, grammar extraction, and value calculation
- Supporting Artifacts: Outputs in value_calculation, grammar-extraction, evaluation, and models directories
cd webappuv venv && source .venv/bin/activateuv syncpython manage.py migratepython manage.py runserver- Visit http://127.0.0.1:8000/reqs/
uv venv && source .venv/bin/activateuv syncjupyter lab
cd langium/reqnpm installnpm run build
To use the VS Code extension, you may install the VS Code extension manually from the pre-build file packages/extension/vscode-req-1.0.1.vsix
- README.md — this file
- pyproject.toml — project metadata and dependencies
- uv.lock — lockfile for uv (optional Python package/deps manager)
- data/
- PROMISE_exp/ — PROMISE_exp.arff and related data for experiments
- Dronology/ — Generated monitoring requirements and datasets
- datasets/ — Consolidated monitoring requirements datasets used for initial training and testing
- evaluation/
- rq1/ — Research Question 1 evaluation (datasets, training/testing sets, independent testing set, verbnet codes)
- rq2/ — Research Question 2 evaluation (Dronology evaluation)
- rq3/ — Research Question 3 evaluation (interviews, surveys)
- grammar-extraction/
- grammar-extraction-veizaga.ipynb — notebook
- output/
- langium/
- req/ — Langium-based HM-Req language artifacts
- value_calculation/
- output/
- weighted_normalized_distance_matrix.(json|pdf|xlsx)
- (un)weighted_normalized_distance_matrix.xlsx
- values.ipynb (preliminary analysis for our value conflict detection)
- output/
- webapp/ — Django project for HM-Req Dashboard
- manage.py — Django management entry point
- webapp/ — Django project settings/urls
- reqs/ — Django app with models, views, urls, migrations, admin
- Required Python: 3.13+
- Dependencies: see pyproject.toml:
- Using uv (recommended):
- Install uv: https://docs.astral.sh/uv/
- In project root:
- uv venv
- source .venv/bin/activate (Windows: .venv\Scripts\activate)
- uv sync
- Project settings: webapp/webapp/settings.py
- Apps: reqs (registered as reqs.apps.ReqsConfig)
- Database: SQLite (webapp/db.sqlite3 by default)
- URLs:
- Root includes: /reqs/ (webapp/webapp/urls.py)
- reqs app routes (webapp/reqs/urls.py):
- /reqs/ — index
- /reqs/upload-requirements/ — upload page
- /reqs/requirements/ — list all requirements
- /reqs/requirements/<req_id>/ — requirement detail
- /reqs/requirements/<req_id>/edit/ — edit requirement
- /reqs/upload-json/ — upload requirements via JSON
- /reqs/clear-database/ — clear all data
The project includes a Controlled Natural Language (CNL) called HM-Req for writing monitoring requirements using EARS-style pre-statements and a constrained verb taxonomy.
- File Extension:
.req
- VS Code Extension: Available in
langium/req/packages/extension/ - CLI Tool: Available in
langium/req/packages/cli/ - Example Files: Located in
langium/req/example-hmreq-files/ langium/req/packages/extension/out/— generated language server/extension JS artifacts (e.g., language/main.cjs)langium/req/packages/language/— core language definition and grammarlangium/req/packages/cli/— command-line interface for processing .req files