Mandates

A mandate is something a holder must or may do: open the building, count the stock, spend up to a limit, decide who gets a key. The holder is the file the mandate is written in, or a mandate file points at it. Mandates are one of the entity types of DWSD format 1.1 and have no DSL syntax of their own: they are written in Markdown files, and the package reads them from there. This page says what the package reads, what it draws where, what the editor checks, and what stays open.

The format defines what a mandate is and how to write one: the Mandates section of the conventions and the mandate type page. This page does not restate them.

What the package reads

Four optional headings in the body of an individual, a role, a unit (a work system included) or an AI agent. Each heading is matched as written, in any letter case, at heading level 2:

Heading	Read as
`## Accountabilities`	what the holder must do
`## Decision Rights`	what the holder may decide or do
`## Key Responsibilities`	what a work system must deliver
`## Mandates`	either, the general form

A file without any of the four headings has no mandates, and that is complete: nothing requires them.

Three shapes under a heading. Each shape gives rows:

A list. Every list item (-, *, +, 1.) is one row. The item text is the row’s name.
Prose. The first paragraph is one row. It is cut at 280 characters and ends with … when it is cut or when more prose follows.
A table with the columns Name and Mandate of. Every table row is one row. The Mandate of cell is optional.

Headings and tables inside a code fence are not read. A level-1 or level-2 heading (indented by up to three spaces) ends a section; the text under it is not read as mandates unless that heading is one of the four. A sub-heading (level 3), a block quote, a thematic break (---, ***, ___) and a second paragraph are skipped, and a thematic break also ends a list. A heading may appear again later in the body; its rows continue the count. At most 200 rows are read under one heading. The frontmatter is never read as rows.

A table has a pipe at the start of every line, and its delimiter row (|---|---|) follows the header row directly; a table without leading pipes is not read.

## Decision Rights

| Name                                               | Mandate of                              |
|----------------------------------------------------|-----------------------------------------|
| Decide who else holds a key                        |                                         |
| Pull the next batch when the shelf runs low        | [[Shop Board]]#Shop/col:Reorder::before |
| [[Market Street Opening Hours]]                    |                                         |

A name that is a single [[file]] link points at a mandate file (below). The file is the source: the row’s Mandate of stays empty. This works in a list item and in a table. [[mandates/Budget]] (with the folder) and [[Budget#Scope]] (with a heading) name the same file as [[Budget]].
Mandate of holds the place where the mandate hangs, as a locator in the form interaction-of and agreement-of take (see the locator grammar). It must be absolute: it starts with [[ or @. A relative cell inherits nothing, because a holder is not a board. A row with a relative cell draws nothing, and the editor warns about it.
An alias inside a table cell. A table splits a cell at the pipe, so write the alias pipe escaped there: [[Name\|alias]] (GFM and Obsidian need the escape too). In a list the plain alias [[Name|alias]] works.

A mandate file is a document with type: mandate. It carries three keys the package reads:

Key	Holds
`for-domain`	the holder when it is a role, a unit or a work system, and points up. A role reaches every keeper of that role. A person is not named here; the person’s own file names the mandate in a row.
`delegator`	who handed the mandate over, a domain or a person. Metadata, not an edge in any view.
`mandate-of`	where the mandate hangs: a locator, a list of locators, or a bare `[[entity]]`. It takes the same value forms as `interaction-of`.

A mandate file is also found by the holders whose rows name it. Several holders are fine.

What the views show

A mandate is drawn where a locator points. Rows without a Mandate of locator, list items and prose are read but not drawn.

Board and flight route. One mandate chip (a key glyph, Terracotta) in its own bucket at the position the locator names, labeled with the holder, not with the mandate text. Several holders at one place share the bucket and list their names; past the width budget it reads Mandates (3). A holder with several mandates at one place is named once on the chip; the drawer lists each mandate. The drawer lists each holder with the mandate text beside a key glyph. On a flight route the same mandate is a marker on the stage, with the Terracotta stroke #C9956B.
Org chart. A role’s mandates show as a key marker on the box of each keeper of the role. The drawer row says via and the role’s name.
Units and topology. A mandate whose for-domain names a work system shows as a key marker on the work system’s topology node and on its unit box. A mandate that hangs at a bare unit or work system (mandate-of: "[[Market Street]]") shows its holders on that box. Two kinds of row can share a box: a mandate the box holds (a for-domain file, or a role’s mandate reaching a keeper) is a row named after the file; a mandate shown at the box is a row named after its holder with the mandate text beside the key glyph. A file the box both holds and shows is listed once, as the holder row. The target may be written with a folder ([[units/Market Street]]); it shows on the box named Market Street.
Marker order. On a box the key marker sits after the role marker and before the individual and unit markers. A box shows at most four marker types; the unit marker is cut first.
The filter layer. The preview’s filter menu has a Mandates layer after Roles. Hiding it hides the chip, the marker and the drawer rows. A filter state saved before the layer existed loads with mandates visible.

The Terracotta color is the same hue as the border of a note, and the layer is a layer of its own. Both are defaults in the current preview, not settled design.

A unit’s box shows the documents that name it in for-domain, with or without the work-system hat. A unit box, plain or with the hat, shows the agreements, drivers, proposals, decision records, roles and mandates whose for-domain names it (dwsd-markdown 37770c8). A mandate file whose for-domain names a plain unit is valid, and that unit’s box draws it.

A unit’s mandates

A unit holds a mandate through a mandate file with for-domain: "[[Unit]]", or through a row in the unit’s own file. A person who is a direct member of the unit (member-of) is reached through the unit: the host question “what are this person’s mandates?” returns that mandate with the route via unit and the unit’s name.

How a unit uses its mandate inside is a matter of the unit’s own agreements. When the unit records that in an agreement (the agreement’s for-domain or agreement-of names the unit), the lookup returns the agreement as a pointer next to the mandate. When no agreement is recorded, the lookup returns no pointer, and a reader says so rather than assuming how the unit decides.

Using a mandate inside a unit also has consequences for what the unit can take on, and how much of it. The format does not say yet how a unit’s commitments toward others are modeled, and the package draws nothing for them.

What the editor checks

The VS Code extension checks mandates against the index: the files VS Code has open, an organization folder or a whole workspace. A finding that says a name is “not in the index” means no file of that set has that name. Each finding shows on the line that writes the mandate. A warning appears as a Warning, a note as Information, in the editor and in the Problems panel.

Code	Severity	What is off
`mandate.name-unresolved`	warning	A row names `[[file]]` and no such document is in the index.
`mandate.name-not-a-mandate`	warning	A row names a document whose type is not `mandate`.
`mandate.copy-cell`	note	A row names a mandate file and also fills its `Mandate of` cell. The cell is a copy; the file’s own `mandate-of` says where the mandate hangs.
`mandate.relative-locator`	warning	A `Mandate of` cell is not absolute. It must start with `[[` or `@`.
`mandate.delegator-unresolved`	warning	The `delegator` of a mandate file is not in the index.
`mandate.for-domain-person`	warning	The `for-domain` of a mandate file names a person. A person holds a mandate through a row in their own file.
`mandate.no-holder`	note	No row names the mandate file and it has no `for-domain`, so nobody holds it.

What is no finding: a missing heading, a person holding a mandate directly, several holders of one mandate, a plain unit in a mandate’s for-domain, and a unit whose commitments toward others are not modeled.

The board and route locators in Mandate of and mandate-of are checked like every other locator: one that points to a board or position that does not exist gets the same warning as an unresolved agreement-of.

dwsd-dsl check reports none of these. The command reads files one by one and has no workspace index, so it cannot tell whether a name resolves. It does not list them under skipped either, because it reads no entity frontmatter at all; see the check. Checking a whole folder of Markdown files from the outside is the job of the org-validate skill of the dwsd-md plugin.

Like what you see? → Start — build your own org folder in ~2 min

# Mandates

A **mandate** is something a holder must or may do: open the building, count the stock, spend up to a
limit, decide who gets a key. The holder is the file the mandate is written in, or a mandate file
points at it. Mandates are one of the entity types of DWSD format 1.1 and have **no DSL syntax of their
own**: they are written in Markdown files, and the package reads them from there. This page says what
the package reads, what it draws where, what the editor checks, and what stays open.

The format defines what a mandate is and how to write one: the
[Mandates section of the conventions](https://github.com/worksystems-design/dwsd-markdown/blob/main/conventions.md#mandates--what-a-holder-must-or-may-do)
and the [`mandate` type page](https://github.com/worksystems-design/dwsd-markdown/blob/main/types/mandate.md).
This page does not restate them.

## What the package reads

**Four optional headings** in the body of an individual, a role, a unit (a work system included) or an
AI agent. Each heading is matched as written, in any letter case, at heading level 2:

| Heading | Read as |
|---------|---------|
| `## Accountabilities` | what the holder **must** do |
| `## Decision Rights` | what the holder **may** decide or do |
| `## Key Responsibilities` | what a work system **must** deliver |
| `## Mandates` | either, the general form |

A file without any of the four headings has no mandates, and that is complete: nothing requires them.

**Three shapes under a heading.** Each shape gives rows:

- **A list.** Every list item (`-`, `*`, `+`, `1.`) is one row. The item text is the row's name.
- **Prose.** The first paragraph is one row. It is cut at 280 characters and ends with `…` when it is
  cut or when more prose follows.
- **A table** with the columns `Name` and `Mandate of`. Every table row is one row. The `Mandate of`
  cell is optional.

Headings and tables inside a code fence are not read. A **level-1 or level-2 heading** (indented by up
to three spaces) ends a section; the text under it is not read as mandates unless that heading is one
of the four. A sub-heading (level 3), a block quote, a thematic break (`---`, `***`, `___`) and a second
paragraph are skipped, and a thematic break also ends a list. A heading may appear again later in the
body; its rows continue the count. At most 200 rows are read under one heading. The frontmatter is
never read as rows.

A **table** has a pipe at the start of every line, and its delimiter row (`|---|---|`) follows the
header row directly; a table without leading pipes is not read.

```markdown
## Decision Rights

| Name                                               | Mandate of                              |
|----------------------------------------------------|-----------------------------------------|
| Decide who else holds a key                        |                                         |
| Pull the next batch when the shelf runs low        | [[Shop Board]]#Shop/col:Reorder::before |
| [[Market Street Opening Hours]]                    |                                         |
```

- **A name that is a single `[[file]]` link** points at a mandate file (below). The file is the source:
  the row's `Mandate of` stays empty. This works in a list item and in a table. `[[mandates/Budget]]`
  (with the folder) and `[[Budget#Scope]]` (with a heading) name the same file as `[[Budget]]`.
- **`Mandate of`** holds the place where the mandate hangs, as a locator in the form `interaction-of`
  and `agreement-of` take (see the [locator grammar](./locator-grammar.md)). It must be **absolute**:
  it starts with `[[` or `@`. A relative cell inherits nothing, because a holder is not a board. A row
  with a relative cell draws nothing, and the editor warns about it.
- **An alias inside a table cell.** A table splits a cell at the pipe, so write the alias pipe escaped
  there: `[[Name\|alias]]` (GFM and Obsidian need the escape too). In a list the plain alias
  `[[Name|alias]]` works.

**A mandate file** is a document with `type: mandate`. It carries three keys the package reads:

| Key | Holds |
|-----|-------|
| `for-domain` | the holder when it is a role, a unit or a work system, and points up. A role reaches every keeper of that role. A person is not named here; the person's own file names the mandate in a row. |
| `delegator` | who handed the mandate over, a domain or a person. Metadata, not an edge in any view. |
| `mandate-of` | where the mandate hangs: a locator, a list of locators, or a bare `[[entity]]`. It takes the same value forms as `interaction-of`. |

A mandate file is also found by the holders whose rows name it. Several holders are fine.

## What the views show

A mandate is drawn where a locator points. Rows without a `Mandate of` locator, list items and prose
are read but not drawn.

- **Board and flight route.** One **mandate chip** (a key glyph, Terracotta) in its own bucket at the
  position the locator names, labeled with the **holder**, not with the mandate text. Several holders
  at one place share the bucket and list their names; past the width budget it reads `Mandates (3)`.
  A holder with several mandates at one place is named once on the chip; the drawer lists each mandate.
  The drawer lists each holder with the mandate text beside a key glyph. On a flight route the same
  mandate is a marker on the stage, with the Terracotta stroke `#C9956B`.
- **Org chart.** A role's mandates show as a key marker on the box of **each keeper of the role**.
  The drawer row says *via* and the role's name.
- **Units and topology.** A mandate whose `for-domain` names a **work system** shows as a key marker
  on the work system's topology node and on its unit box. A mandate that hangs at a bare unit or work
  system (`mandate-of: "[[Market Street]]"`) shows its holders on that box. Two kinds of row can share a
  box: a mandate the box **holds** (a `for-domain` file, or a role's mandate reaching a keeper) is a row
  named after the file; a mandate **shown** at the box is a row named after its holder with the
  mandate text beside the key glyph. A file the box both holds and shows is listed once, as the holder row. The target may be written
  with a folder (`[[units/Market Street]]`); it shows on the box named `Market Street`.
- **Marker order.** On a box the key marker sits after the role marker and before the individual and
  unit markers. A box shows at most four marker types; the unit marker is cut first.
- **The filter layer.** The preview's filter menu has a **Mandates** layer after Roles. Hiding it hides
  the chip, the marker and the drawer rows. A filter state saved before the layer existed loads with
  mandates visible.

The Terracotta color is the same hue as the border of a note, and the layer is a layer of its own.
Both are defaults in the current preview, not settled design.

**A unit's box shows the documents that name it in `for-domain`, with or without the `work-system`
hat.** A unit box, plain or with the hat, shows the agreements, drivers, proposals, decision records, roles
and mandates whose `for-domain` names it (dwsd-markdown `37770c8`). A mandate file whose `for-domain` names
a plain unit is valid, and that unit's box draws it.

## A unit's mandates

A unit holds a mandate through a mandate file with `for-domain: "[[Unit]]"`, or through a row in the
unit's own file. A person who is a direct member of the unit (`member-of`) is reached through the unit: the host
question "what are this person's mandates?" returns that mandate with the route **via unit** and the
unit's name.

How a unit uses its mandate inside is a matter of the unit's own agreements. When the unit records that
in an agreement (the agreement's `for-domain` or `agreement-of` names the unit), the lookup returns the
agreement as a pointer next to the mandate. When no agreement is recorded, the lookup returns no
pointer, and a reader says so rather than assuming how the unit decides.

Using a mandate inside a unit also has consequences for what the unit can take on, and how much of it.
The format does not say yet how a unit's commitments toward others are modeled, and the package draws
nothing for them.

## What the editor checks

The VS Code extension checks mandates against the index: the files VS Code has open, an organization
folder or a whole workspace. A finding that says a name is "not in the index" means no file of that set has
that name. Each finding shows on the line that writes the mandate. A warning appears as a Warning, a
note as Information, in the editor and in the Problems panel.

| Code | Severity | What is off |
|------|----------|-------------|
| `mandate.name-unresolved` | warning | A row names `[[file]]` and no such document is in the index. |
| `mandate.name-not-a-mandate` | warning | A row names a document whose type is not `mandate`. |
| `mandate.copy-cell` | note | A row names a mandate file and also fills its `Mandate of` cell. The cell is a copy; the file's own `mandate-of` says where the mandate hangs. |
| `mandate.relative-locator` | warning | A `Mandate of` cell is not absolute. It must start with `[[` or `@`. |
| `mandate.delegator-unresolved` | warning | The `delegator` of a mandate file is not in the index. |
| `mandate.for-domain-person` | warning | The `for-domain` of a mandate file names a person. A person holds a mandate through a row in their own file. |
| `mandate.no-holder` | note | No row names the mandate file and it has no `for-domain`, so nobody holds it. |

What is **no** finding: a missing heading, a person holding a mandate directly, several holders of one
mandate, a plain unit in a mandate's `for-domain`, and a unit whose commitments toward others are not
modeled.

The board and route locators in `Mandate of` and `mandate-of` are checked like every other locator:
one that points to a board or position that does not exist gets the same warning as an unresolved
`agreement-of`.

**`dwsd-dsl check` reports none of these.** The command reads files one by one and has no workspace
index, so it cannot tell whether a name resolves. It does not list them under `skipped` either, because
it reads no entity frontmatter at all; see [the check](./check.md). Checking a whole folder of
Markdown files from the outside is the job of the `org-validate` skill of the dwsd-md plugin.