# informed-decision — Initial exploration

Working notes from the founding conversation (9 September 2026).  
Use this file plus the sibling artefacts as the project starting point.

Companion files:

| File | What it is |
|---|---|
| `decision-memo.schema.json` | JSON Schema draft 2020-12, object model v0.2 |
| `decision-memo-schema.md` | Human commentary on the schema and invariants |
| `decision-memo.example.json` | ADR accept example (L2) |
| `decision-memo.login.example.json` | Login banner example (L0) with binding vs awareness |
| `state-transitions.md` | Verb × status × step-kind tables |
| `canonicalize.md` | `view_hash` / `awareness_hash` algorithm |
| `canonicalize.py` | Reference canonicalizer |
| `vectors/` | Binding and awareness fixtures plus expected hashes |

---

## 1. Intent

Build **informed-decision**: a user interface for executive (and everyday) decisions modelled as a *sign-and-return book*.

Use cases named in the brief:

- logging into a system
- authorizing an action that needs elevated privileges
- formally accepting an ADR
- approving a management decision you are responsible for
- signing a business contract
- at greatest depth: multi-party sign-off of complex international instruments

Required verbs on the book:

- present necessary context
- add comments
- contact the requester
- return the memo for improvement
- forward or escalate
- accept electronically on the user’s identity
- document what happened with auditability
- establish cryptographic proof (sign the decision, stamp relevant files)

Spectrum:

- **Simplest:** commentary on a login mask — which system, which identity, which privileges.
- **Deepest:** complex decision memos with multiple documents, highlight pointers to critical sections, multi-party sign-off.

The German administrative metaphor is the right one: *Umlaufmappe*, *Zeichnungsleiste*, *Mitzeichnung*, *Schlusszeichnung*, *Kenntnisnahme*, *Rücksprache*, *Bitte um Berücksichtigung*.

---

## 2. Unifying insight

A sign-and-return book is not a document folder. It is a **portable decision object** that travels with:

- a question that must be answered
- the context a reasonable decision-maker needs
- a requested act (login, elevate, approve, accept, sign, escalate)
- a record of what happened
- a cryptographic binding between *identity*, *what was shown*, and *what was bound*

Existing product categories split that object:

| Category | Strength | Gap |
|---|---|---|
| PAM / JIT access | time-bound elevation, justification | almost no work-object context |
| E-sign / CLM | ceremony, sealed PDFs, routing | weak “why this is on your desk” |
| ADR tools | context / decision / consequences | “accepted” is a Git status, not an identity act |
| Board portals | packs, votes, elite audience | too heavy for daily operational acts |
| Digital *Umlaufmappe* (SAP, enaio, M-Files) | circulation + protocol | weak proof of *informedness*; not login-scale |
| Decision intelligence | recommendation and policy | not the binding act |

White space: one object model, one evidence model, one UX grammar, from a 10-second login to a treaty.

The differentiator is not another workflow engine. It is:

1. **Informedness as a measurable property** (what was presented, highlighted, opened, attested).
2. **A disposition vocabulary richer than approve/reject.**
3. **Cryptographic binding of presentation to act** (dynamic linking), not only of file to identity.
4. **Scale invariance.**

Research notes that belong in the backlog:

- eIDAS / eIDAS 2.0 / EUDI Wallet: QES becomes a mass wallet capability around 2026–27; identity should be imported, not invented.
- Dynamic linking: the human-readable content actually presented must be bound into the signature.
- Accountability UI (identifiability, evaluation, social presence) reduces abuse of access — relevant to the login end of the spectrum.
- Agents may draft memos; they must not be able to complete the binding act on the principal’s surface.

---

## 3. Vision and mission drafts

**Working vision**

People should never have to bind an identity to an action they could not reasonably understand. Informed-decision is the book in which that understanding is presented, contested, returned, escalated, and sealed.

Alternates kept:

- Every binding act is an informed act: the person who decides sees what matters, can send the question back, and leaves cryptographic proof of what they bound themselves to.
- Replace the circulating folder, the login banner, and the signature page with one governed surface.
- Make European identity useful at the moment of judgment: wallet-grade identity, qualified signatures, and an evidence pack that still answers *who decided what, having seen what*.

**Working mission**

Give every organization a reusable Decision Memo: assemble the minimum necessary context, route it to the person who actually holds the mandate, let them comment, discuss, return or escalate, and — when they accept — bind identity, presentation, and outcome into a verifiable evidence bundle.

**Promise**

Not “the file was signed.”  
“This person, in this role, was shown this view, and bound this act.”

---

## 4. Design principles

1. One object, many depths. Login and treaty share a schema.
2. Presentation is part of the signed payload.
3. Competence before convenience. Routing follows mandate.
4. Return is success, not failure.
5. Dialogue stays on the object. Side-channel email is an anti-pattern.
6. Binding level is explicit. Kenntnisnahme ≠ Mitzeichnung ≠ QES.
7. Evidence is an export, not a screenshot.
8. Least privilege of attention. Highlights first; full packet available; no dark patterns.
9. Identity is imported (SSO, passkeys, eID, EUDI Wallet, QTSP).
10. Humans bind. Agents draft.

Later addition that is now first-class:

11. **Pre-sign and post-sign information are different objects.** Identity and bind-scope are committed. Hats, last-used role, and other-tenant orientation are awareness unless promoted.

---

## 5. Depth spectrum

| Level | Act | Typical binding |
|---|---|---|
| L0 | Informed login / session | acknowledgment / organizational |
| L1 | Privileged authorization (JIT) | organizational |
| L2 | Formal ADR / decision-record accept | organizational / AES |
| L3 | Management approval | organizational / AES |
| L4 | Contract / instrument | AES / QES |
| L5 | Multi-party international instrument | QES per party (horizon, not v1) |

v1 should prove the thesis on A+B+C sharing one object: informed login/elevation, formal ADR, one real contract type.

---

## 6. Decision Memo object (v0.2)

```
DecisionMemo
├── requester / subject / parties[] + mandate
├── question + requested_act + binding_level
├── brief + consequences
├── identity_context.binding      PRE-SIGN identity + scope   → view_hash
├── identity_context.awareness    hats, last-used, tenants    → awareness_hash
├── session                       POST-SIGN live hat
├── packet[]                      hashed files
├── highlights[]                  pointers into packet
├── route.steps[]                 Laufweg / Zeichnungsleiste
├── thread[]
├── presentations[]
├── dispositions[]
├── relations[]
└── evidence                      append-only hash chain
```

Lifecycle:

```
draft → submitted → circulating | awaiting_actor | in_discussion
                  ↘ returned —new version→ submitted
                  ↘ completed (outcome set)
                  ↘ withdrawn | expired
completed —new memo→ superseded

L0/L1 extra: completed login/elevate → session.active → configure hats → session.ended
```

Core invariants (I1–I13) live in `decision-memo-schema.md`. The ones that must not be bargained away:

- One question per memo.
- Binding acts reference a presentation of the same version.
- AES/QES dynamically links `view_hash`.
- Required highlights must be acked before bind.
- Agents may draft, not bind.
- Return always carries structured reasons.
- Highlights never shrink the legal object.
- `binding` is signed; `awareness` is not, unless `promote` copied named fields into `awareness_promoted`.
- Hats are not scopes. `requires_new_bind` or `hat.elevates` means a new memo (or promote + new version).

---

## 7. Pre-sign vs post-sign (login / multi-tenant)

The login case forced a split that applies everywhere.

**Pre-sign / binding slice** (editable, signed)

- which identity you log in as (ordinary vs break-glass)
- which scope/tenant/system you enter
- privileges granted *at the gate*
- monitoring and consent terms

**Awareness slice** (shown on the same surface, hashed separately, not signed)

- proposed hat after login (`last_used` | `system_default` | `policy` | `explicit`)
- other hats available inside that bound scope
- other tenants you support (orientation)
- last session summary

**Post-sign / session**

- `configure(hat)` if `elevates=false`
- switching to a tenant with `requires_new_bind=true` opens a child memo
- an elevating hat (`Payroll Admin`) cannot be configured; it must be promoted into binding or issued as its own elevation memo

Banner sketch:

```
PRE-SIGN (bound)
  Identity   [ Bernd Worsch              ▾ ]
  Scope      [ ACME Corp / Payroll-Prod  ▾ ]

AWARENESS (not signed)
  After login you will wear Finance Controller
      source: last used, Tue 18:12 CEST
  Other hats: Auditor · Payroll Admin (needs new bind)
  Other tenants: Beta GmbH (needs new bind)
```

Defaulting the hat to last-used is required for situational awareness and forbidden from silently entering `view_hash`.

---

## 8. State transitions (summary)

Actors: requester, current-step assignee, any party, session subject, system, agent.

Overlay verbs always available in circulation: `comment`, `discuss`. Requester may `withdraw` before terminal. System `stamp`s evidence.

| Verb | Weak step (`inform`/`review`) | Co-sign | Bind step |
|---|---|---|---|
| return / forward / escalate | yes | yes | yes |
| acknowledge | completes step | completes step | overlay |
| accept | **illegal** | completes step | may complete memo |
| decline | illegal | completes step/memo | completes memo `declined` |
| configure | illegal until `session.active` | same | same |

`accept` on Kenntnisnahme is illegal on purpose.

After login/elevate bind:

- `configure(hat)` allowed only for non-elevating hats in `available_hats`
- other-tenant with `requires_new_bind` → `scope.rebind_required` + child memo
- binding verbs on a sealed version are illegal

Full tables, guards (`G_PRES`, `G_ACK`, `G_MAND`, `G_HAT`, …), and illegal combinations: `state-transitions.md`.

---

## 9. Canonicalization (summary)

Two hashes on every presentation.

| Hash | Input | Signed? |
|---|---|---|
| `view_hash` | binding document | yes, from organizational level up |
| `awareness_hash` | awareness document | no, unless promote ran |

Profile: JCS-inspired restricted JSON — UTF-8, sorted keys, no insignificant whitespace, integers only, unknown keys stripped, nulls dropped.

`view_hash` allow-list: `memo_id`, `memo_version`, `question`, `requested_act`, `binding_level`, `brief`, `locale`, `ui_release`, normalized `packet`, normalized `highlights`, `binding`, optional `awareness_promoted`.

`awareness_hash` allow-list: proposed hat + source, available hats/scopes, last session, situation note.

```
canonical = dumps(document)
hash      = SHA-256(UTF-8(canonical))
```

Reference: `canonicalize.py`. Spec: `canonicalize.md`.

Computed vectors (`vectors/expected.json`):

```
login view_hash       492d9d311bf44ec9de0d0abef28abac7d31df2781527e8fe276a3186ee1b06b8
login awareness_hash  2be7742970a01e7a879ae5040660659fb8c9a5c024e6c7fb338f3944a4fe05d1
ADR-0042 view_hash    1c89ec07c3cc9d16f85a1ba1be5169456b3c55d21161f64037787779ae91f202
```

Isolation that must stay green:

1. Shuffling object keys does not change hashes.
2. Editing awareness fields does not change `view_hash`.
3. Changing `binding.target` ACME → Beta does change `view_hash`.
4. Selecting a hat after login emits `session.hat_selected` and does not rewrite `view_hash`.

AES/QES signed attributes carry `memo_id`, `memo_version`, `disposition.verb`, `presentation.view_hash`. They do not carry `awareness_hash` unless promote ran.

---

## 10. Open questions (still open)

1. Beachhead buyer: German public-sector *Schriftgut*, platform-eng ADR+PAM, or mid-market contract?
2. Product vs protocol? Long game is both (Decision Memo + Evidence Bundle + Disposition verbs in front of IdP, Git, and e-sign).
3. How to evidence “informed” without surveillance theater — hash of presented view + explicit highlight ack, not keystroke analytics.
4. Mandate graph: without a living map of who may bind what, escalate is just forwarding.
5. Liability of highlights: legally the whole instrument is bound; the UI must make that unmistakable.
6. Retention / qualified archive for L4+.
7. Name: keep `informed-decision`; use *Umlaufmappe* / *Zeichnungsbuch* in DACH language.

---

## 11. Suggested next build slice

Do not start at L5. Ship a thin Decision Memo runtime that already has the split hashes:

1. Embeddable L0 login/elevation component in front of an IdP or PAM.
2. L2 ADR accept with comment / return / escalate / accept and AES-optional seal.
3. One single-jurisdiction contract path.

If those three share this schema, the transitions, and the two hashes, the vision is real. If they fork, it is not.