simulink-requirements

# MATLAB Requirements Toolbox — Requirements & Traceability

This skill covers everything in the `slreq` API: creating and reading requirements,
managing traceability links, checking verification coverage, allocating requirements
to architecture components, and auditing link health.

For architecture phases (System Composer models, functional decomposition,
functional→physical allocation) see the `mbse-architecture` skill.

See `references/api-quickref.md` in this skill folder for a compact one-page API reference.

---

## The Two File Types

| Extension | Class | Role |
|---|---|---|
| `.slreqx` | `slreq.ReqSet` | Stores requirements (text, hierarchy) |
| `.slmx` | `slreq.LinkSet` | Stores traceability links **outgoing from a source artifact** |

### When a `.slmx` file is created

slreq writes a `.slmx` file **only when its companion artifact is the source of at least one link.** The LinkSet is keyed on the source artifact, not the destination.

- `MyReqs~slreqx.slmx` appears only if some link's source is a requirement in `MyReqs.slreqx` (e.g., `slreq.createLink(srcReq, destReq)` where `srcReq` lives in `MyReqs`)
- `MyModel~mdl.slmx` appears only if some link's source is a model element in `MyModel.slx` (typical: `slreq.createLink(component, req)` with Type `Implement` — the component is the source)

An artifact that is only ever a link *destination* never gets a paired `.slmx`. In a typical MBSE project:

| Artifact | Gets a `.slmx`? | Why |
|---|---|---|
| `StakeholderNeeds.slreqx` | Yes | SNs are the source of Derive links to SRs |
| `SystemRequirements.slreqx` | **Usually no** | SRs are destinations of Derive / Implement / Verify links; no file unless SR-to-SR Refine links or links to external docs are added |
| `TestCases.slreqx` | Yes | TC requirements are the source of Verify links to SRs |
| Architecture `.slx` models | Yes | Components are the source of Implement links to SRs |

### Reporting rules for build scripts

Because `.slmx` files are conditional, **never claim a `.slmx` was produced based on the API calls you made — always verify with `isfile` before reporting.** A script that creates only SN→SR Derive links will produce `StakeholderNeeds~slreqx.slmx` but **not** `SystemRequirements~slreqx.slmx`, even though both `.slreqx` files exist.

Idempotent cleanup and project registration for `.slmx` files must both guard with `isfile`:

```matlab
if isfile(snLinks), delete(snLinks); end   % cleanup — safe whether or not it exists
```

The `registerWithProject` helper already does this — it skips files that don't exist on disk — so passing a non-existent `.slmx` path is a no-op, not an error.

---

# Requirements (Phases 1–2)

---

## Two-Level Structure

| Level | ID scheme | Character |
|---|---|---|
| Stakeholder Needs | `SN-SYS-001` | Operational, informal — what the user/operator needs |
| System Requirements | `SR-SYS-001` | Formal, testable — what the system shall do |

Each SR traces back to one or more SNs via a `Derive` link.

---

## Well-Formed Shall-Statements

- One obligation per requirement ("shall", not "should" or "will")
- Measurable and testable — include numeric criteria where possible
- Avoid `<` and `>` in Description fields — the Requirements Editor treats them
  as HTML. Use "not exceeding", "at least", "greater than", etc.

**Good:** `The system shall respond with latency not exceeding 100 ms.`
**Avoid:** `The system shall respond with latency < 100 ms.`

---

## Creating Requirement Sets

```matlab
slreq.clear();
if isfile('MyReqs.slreqx'), delete('MyReqs.slreqx'); end
rs = slreq.new('MyReqs.slreqx');        % NOT slreq.createReqSet (does not exist)

req = rs.add();
req.Id          = 'SR-SYS-001';
req.Summary     = 'Short title';
req.Description = 'The system shall ...';
req.Rationale   = 'Why this requirement exists.';

rs.save();
```

### Find a requirement by ID

```matlab
req = rs.find('Id', 'SR-SYS-001');
```

---

## Valid Link Types

| Type | Meaning | Direction |
|---|---|---|
| `"Derive"` | Parent decomposes into derived child | SN (source) → SR (destination) |
| `"Implement"` | Architecture element (or model block) implements requirement | Component/Block (source) → SR (destination) |
| `"Verify"` | Test case verifies requirement | TC (source) → SR (destination) |
| `"Refine"` | Requirement refined into a more specific requirement (same artifact kind, more detail). Not used for SR → architecture in this workflow. | SR (source) → SR (destination) |
| `"Relate"` | Informal relationship | Bidirectional |

---

## Creating Links

```matlab
% Req-to-req derivation: parent (e.g. SN) decomposes into derived child (e.g. SR)
lnk = slreq.createLink(parentReq, childReq);
lnk.Type = 'Derive';

% Model block to req (model must be open in Simulink)
lnk = slreq.createLink(blockHandle, req);
lnk.Type = 'Implement';

% Test case requirement to SR
lnk = slreq.createLink(tc, sr);
lnk.Type = 'Verify';

slreq.saveAll();   % always call after creating cross-artifact links
```

### Side effect: `{modelName}~mdl.slmx` link store

The first time you create a link whose **source** is an element of a Simulink/System Composer
model (component, subsystem, or block), slreq writes a `{modelName}~mdl.slmx` file next to the
`.slx`. This is the normal case for Implement links in this workflow — `slreq.createLink(component, req)`
has the component as source, so the link lives in the model's LinkSet, not the requirement set's.

A model that only ever *receives* links (no element of it is used as a link source) does not
get a `~mdl.slmx`. In MBSE practice this is rare: architecture models almost always have Implement
links where they are the source.

After creating links whose source is in a model, register both the `.slx` and the `.slmx` with the
project, guarding `.slmx` registration with `isfile` since the file may not yet exist:

```matlab
addFile(proj, fullfile(archDir, 'MyModel.slx'));
slmx = fullfile(archDir, 'MyModel~mdl.slmx');
if isfile(slmx), addFile(proj, slmx); e