Requirements

The Studio is specified by requirements that describe what it does today. Each one is tied to the code that produces the behaviour and to the test that checks it.

What the requirements are

The requirements live in the repository, in a bundle managed by the okfreq tool. They come at two levels. A StRS (stakeholder requirement) is a use case: something a writer, reviewer or maintainer can do and see in VS Code. A SwRS (software requirement) is one observable behaviour of the extension, written with its scenarios: given a situation, when something happens, then this is the outcome. A rule that many behaviours share is written once and cited by the others. Together they specify what the Studio does today, never what we would like it to do.

Why we keep them

• The documented behaviour stays equal to the code, because each requirement is checked against the source and the tests.
• Bugs become visible: a behaviour that looks wrong is written down as it behaves, under a "Known issue", and its fix is planned separately.
• We know which test checks which behaviour, and which behaviour has no test.
• A change can be reviewed against a contract: the requirement, the code and the test change together.

How it works

A use case (StRS) is refined into behaviours (SwRS). Each behaviour is anchored in two places by a one-line comment holding its identifier: @implements_req where the code produces it, and @tests_req in the test that checks it.

A real example

This requirement is read from the report and the repository as they stand. Its statement and a scenario, then the two comments that tie it to the code and to the test.

// @implements_req SwRS-MDOKFSTUDIO-GFM-021
/**
 * Gives the task-list marker at 1-based `line`, zero-based `column` (its opening bracket) the
 * state `checked`: a one-character edit between the brackets.
 */
export function planCheckboxToggle(text: string, line: number, column: number, checked: boolean): CheckboxTogglePlan {
  const lines = sourceLines(text);

// @tests_req SwRS-MDOKFSTUDIO-GFM-021
test("a checkbox toggle changes the one character between the brackets", () => {
  const text = "# Tasks\r\n\r\n- [ ] one\r\n- [x] two\r\n";
  const toggle = planCheckboxToggle(text, 3, 2, true);
  assert.deepEqual(toggle, { edit: { start: 14, end: 15, text: "x" } });
  assert.equal(applied(text, toggle), "# Tasks\r\n\r\n- [x] one\r\n- [x] two\r\n");
  assert.equal(applied(text, planCheckboxToggle(text, 4, 2, false)), "# Tasks\r\n\r\n- [ ] one\r\n- [ ] two\r\n");

What keeps it in sync

The requirement checks run in CI with the other static checks (just check runs just requirements-lint): okfreq validate checks the requirement files and their links, okfreq lint --check checks the generated navigation, and okfreq update-coverage --check fails when a marker is missing, unknown or out of date. A change that moves marked code or tests moves the markers in the same commit.

The figures

Counts come from the okfreq generate-report JSON and cover active requirements only (16 approved, 12 draft, 472 proposed); retired ones are counted below. Report generated 2026-10-29T16:37:08.325514+00:00.

Per scope

Retired requirements

Kept for their identifiers, never counted above and exempt from markers.

Browse the requirements

Browsing the requirements from this site, from a use case to its behaviours and their tests, with a page per requirement and a search, is planned and not available yet. Until then the requirements are readable in the repository, under requirements/tiers/.