Establish INTENT, Stage 1 GOAL, and founding workplan
Claim ownership of the browser-facing approver UI that approval-engine deliberately does not contain. approval-engine's INTENT names an approvals inbox under Non-Goals, and docs/keycape-service-registrations.md records that the human approver client's client_id and callback URI "must come from its owner once it exists" — leaving key-cape's KEY-WP-0013-T02 blocked on an unassigned component. - INTENT.md: Decision Memo concept, the binding/awareness split and the two hashes, ownership and non-ownership against the named estate repositories, and a provisional PEP-shaped layer placement flagged for a gate-house ruling rather than asserted. - GOAL.md: Stage 1 is the L3 approval approver surface — the narrowest real consumer with a live blocking dependency — plus the written answer to who owns the approver UI. - workplans/INFD-WP-0001: founding documents, the gate-house layer/ownership ruling, the four specs (PRD, UseCaseCatalog, ArchitectureBlueprint, EvidenceModel), schema and canonicalizer promotion out of history/ with the isolation vectors under test, the key-cape client registration, and a walking skeleton that includes return and discuss. history/ is preserved unmodified as provenance. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01V3W1dQG7GFFM9d94jFx7iR Assistant: claude-code Assistant-Model: opus Assistant-Process: 1565372@bnt-lap001 Assistant-Session: 16bb2f25-b34c-49ef-8e94-5fec3567a568
This commit is contained in:
parent
771ddb9ced
commit
ee2cca579c
16 changed files with 3218 additions and 1 deletions
245
INTENT.md
Normal file
245
INTENT.md
Normal file
|
|
@ -0,0 +1,245 @@
|
|||
---
|
||||
project: informed-decision
|
||||
product: Informed Decision
|
||||
status: draft
|
||||
intent_version: 0.1.0
|
||||
date: "2026-09-09"
|
||||
domain: infotech
|
||||
topic_slug: netkingdom
|
||||
layer: surface
|
||||
role: pep-shaped # PROVISIONAL — see "Layer Placement", INFD-WP-0001-T02
|
||||
standard: net-kingdom/canon/standards/security-layer-model_v0.7.md
|
||||
companion: net-kingdom/SECURITY-COMPANION.md
|
||||
---
|
||||
|
||||
# INTENT
|
||||
|
||||
> This file captures why this repository exists and the kind of system it is
|
||||
> meant to become. It is aspirational and stable, not a description of current
|
||||
> implementation. Implemented boundary belongs in `SCOPE.md`; the current stage
|
||||
> belongs in `GOAL.md`; current work belongs in `workplans/`.
|
||||
|
||||
## Purpose
|
||||
|
||||
> **informed-decision owns the surface on which a human is shown a decision and
|
||||
> binds their identity to it — and owns the evidence that the presentation
|
||||
> actually happened.**
|
||||
|
||||
It answers one question, totally and decidably:
|
||||
|
||||
> **What was this person shown, in what role, at the moment they bound
|
||||
> themselves to this act — and can that be proven afterwards?**
|
||||
|
||||
Nothing else. It does not decide whether the act is permitted (`access-engine`),
|
||||
does not own the approval object (`approval-engine`), does not author the
|
||||
doctrine that requires an approval (`gate-house`), does not authenticate the
|
||||
person (`key-cape`), and does not archive the trail (`audit-core`).
|
||||
|
||||
## Why This Exists
|
||||
|
||||
Every layer of the NetKingdom estate has an owner except the one a human
|
||||
actually touches.
|
||||
|
||||
`approval-engine`'s `INTENT.md` names it under Non-Goals, twice and
|
||||
deliberately: *"Not a workflow or ticketing system"*, *"Not an approvals inbox
|
||||
or notification surface."* That exclusion is correct — an engine that renders
|
||||
its own object is self-dealing — but it leaves a hole, and the hole is now
|
||||
load-bearing:
|
||||
|
||||
- `approval-engine` is a bearer-token resource server with no Ingress, no
|
||||
redirect endpoint and no browser client
|
||||
(`deploy/approval-engine.yaml`: Namespace + ClusterIP + StatefulSet).
|
||||
- `key-cape` (`KEY-WP-0013-T02`) asked approval-engine for the human approver
|
||||
client's `client_id` and callback URI on 2026-09-08.
|
||||
- approval-engine correctly refused to invent them, recording in
|
||||
`docs/keycape-service-registrations.md`: *"The human approver flow therefore
|
||||
belongs to whichever browser-facing approver UI presents `approval:approve`
|
||||
tokens to this engine. That component is not in this repo."*
|
||||
|
||||
So the approver UI is not merely missing. It is a **named, unassigned
|
||||
dependency** that currently blocks an OIDC client registration in another
|
||||
repository. **This repository claims it.**
|
||||
|
||||
The claim is not opportunistic. The founding exploration
|
||||
(`history/20260909-initial-exploration/`) arrived at the same object from the
|
||||
opposite direction — the German *Umlaufmappe* / *Zeichnungsbuch*, a portable
|
||||
decision object that carries a question, the context needed to answer it, the
|
||||
requested act, and a cryptographic binding between *identity*, *what was shown*,
|
||||
and *what was bound*. That is exactly the artifact the estate is missing, and it
|
||||
generalizes past approvals without ever becoming a decision point.
|
||||
|
||||
## The Concept — the Decision Memo
|
||||
|
||||
A **Decision Memo** is a portable object presented to one human who holds a
|
||||
mandate. It carries:
|
||||
|
||||
- a **question** that must be answered, and a **requested act**;
|
||||
- the **brief and consequences** a reasonable decision-maker needs;
|
||||
- a **packet** of hashed documents and **highlights** pointing into it;
|
||||
- a **binding slice** — the identity and scope being committed, which is signed;
|
||||
- an **awareness slice** — orientation (proposed role, other roles, other
|
||||
tenants, last session), which is shown and hashed but **not** signed;
|
||||
- a **route** (`Zeichnungsleiste`), a **thread**, and a record of every
|
||||
**presentation** and **disposition**;
|
||||
- an append-only **evidence** chain.
|
||||
|
||||
Two hashes are computed over every presentation:
|
||||
|
||||
| Hash | Over | Signed? |
|
||||
| --- | --- | --- |
|
||||
| `view_hash` | the binding document | yes, from organizational level up |
|
||||
| `awareness_hash` | the awareness document | no, unless a field was promoted |
|
||||
|
||||
`view_hash` is the mechanism. It is what turns *"the file was signed"* into
|
||||
*"this person, in this role, was shown this view, and bound this act."*
|
||||
|
||||
## Scale Invariance Is the Thesis
|
||||
|
||||
One object model, one evidence model, one UX grammar, from a ten-second login
|
||||
to a multi-party instrument:
|
||||
|
||||
| Level | Act | Typical binding |
|
||||
| --- | --- | --- |
|
||||
| L0 | Informed login / session | acknowledgment / organizational |
|
||||
| L1 | Privileged authorization (JIT elevation) | 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) |
|
||||
|
||||
If L0 and L3 share the schema, the transitions, and the two hashes, the thesis
|
||||
holds. If they fork, it does not — and the estate has bought a bespoke approvals
|
||||
inbox instead of a decision surface.
|
||||
|
||||
**The approval approver UI is L3.** It is the first stage precisely because it
|
||||
is a real consumer with a real blocking dependency, not a demo.
|
||||
|
||||
## The Disposition Vocabulary
|
||||
|
||||
The differentiator is not another workflow engine. It is that *approve/reject*
|
||||
is the wrong vocabulary for judgment. The verbs are:
|
||||
|
||||
`comment` · `discuss` (Rücksprache) · `return` for improvement (Rückgabe) ·
|
||||
`forward` · `escalate` · `acknowledge` (Kenntnisnahme) · `accept`
|
||||
(Mitzeichnung / Schlusszeichnung) · `decline` · `withdraw` · `configure`
|
||||
|
||||
`accept` on a Kenntnisnahme step is **illegal on purpose**. **Return is success,
|
||||
not failure** — a memo sent back for improvement is the surface working.
|
||||
|
||||
## What informed-decision Owns
|
||||
|
||||
- the **Decision Memo** object, its versions, and its lifecycle;
|
||||
- the **presentation record** — what was rendered, to whom, when, in which
|
||||
locale and UI release;
|
||||
- **canonicalization** of the binding and awareness documents, and the
|
||||
computation of `view_hash` / `awareness_hash`;
|
||||
- **highlight acknowledgment** — required highlights acked before a bind is
|
||||
permitted;
|
||||
- the **disposition vocabulary** and its legality tables;
|
||||
- the **evidence bundle** as an export — the reconstructable answer to *who
|
||||
decided what, having seen what*;
|
||||
- the **browser-facing OIDC client** for human principals, including the
|
||||
`client_id` and callback URI that `key-cape` is waiting for;
|
||||
- the **pre-sign / post-sign split**: identity and bind-scope are committed;
|
||||
hats, last-used role, and other-tenant orientation are awareness unless
|
||||
explicitly promoted.
|
||||
|
||||
## What informed-decision Does Not Own
|
||||
|
||||
- **the decision** — `access-engine`, always and only (statute §6). This
|
||||
repository renders a question and records an answer; it never evaluates
|
||||
whether an actor may do a thing;
|
||||
- **the approval object** — `approval-engine`. This surface calls that engine's
|
||||
mutations with an `approval:approve`-scoped token; it never holds approval
|
||||
current-state and never answers "is this approval valid";
|
||||
- **approval doctrine** — which acts need approval, how many approvers, which
|
||||
separations of duty — `gate-house`;
|
||||
- **identity and authentication** — `key-cape`. Identity is *imported*
|
||||
(OIDC, passkeys, eID, EUDI Wallet, QTSP), never invented here;
|
||||
- **the evidence archive** — `audit-core`. This repository emits and exports;
|
||||
the trail is held there;
|
||||
- **credentials materialized after a decision** — `secrets-engine`;
|
||||
- **notification transport** — a memo may be announced by other means; the
|
||||
dialogue stays on the object.
|
||||
|
||||
## Design Principles
|
||||
|
||||
1. **One object, many depths.** Login and instrument share a schema.
|
||||
2. **Presentation is part of the signed payload.** Dynamic linking, not a
|
||||
signature over a file nobody read.
|
||||
3. **Competence before convenience.** Routing follows mandate.
|
||||
4. **Return is success.**
|
||||
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 — and the UI must make unmistakable that the *whole*
|
||||
instrument is bound, not only the highlights.
|
||||
9. **Identity is imported.**
|
||||
10. **Humans bind, agents draft.** An agent may assemble a memo. It may never
|
||||
complete the binding act on the principal's surface.
|
||||
11. **Awareness is not consent.** Defaulting a role to last-used is required
|
||||
for situational awareness and forbidden from silently entering `view_hash`.
|
||||
12. **Informedness without surveillance.** Evidence is the hash of the
|
||||
presented view plus explicit highlight acknowledgment — never keystroke
|
||||
analytics, dwell timers, or attention theater.
|
||||
|
||||
## Layer Placement — Provisional
|
||||
|
||||
Under security layer model v0.7 this repository is **not** an Engine. It is
|
||||
browser-facing and it causes a protected side effect on the far side of a
|
||||
decision, which is the shape statute §6.4 and companion §5 call **PEP-shaped**.
|
||||
`approval-engine`'s own INTENT names this expectation: *"Callers that do are
|
||||
PEP-shaped and owe companion §5 / statute §6.4."*
|
||||
|
||||
This is declared **provisional** because the catalog row does not exist yet and
|
||||
inventing one is the drift §17 exists to prevent. `INFD-WP-0001-T02` takes the
|
||||
question to `gate-house` and writes `layer.yaml` from the answer, not from this
|
||||
paragraph. The framing this repository will argue: informed-decision is a
|
||||
**presentation and binding surface** — a PEP for the acts it fronts, and a PIP
|
||||
for exactly one fact, *what was presented*, which it supplies as a claim and
|
||||
never evaluates.
|
||||
|
||||
## What Would Make This Repository Wrong
|
||||
|
||||
- **It starts deciding.** Any surface that answers "may this actor do X" rather
|
||||
than "here is the question, and here is what you were shown" is the failure
|
||||
statute §6 names.
|
||||
- **It becomes an approvals inbox and nothing else.** If the object that ships
|
||||
cannot also carry an L0 login banner and an L2 ADR accept, the scale-invariance
|
||||
thesis is dead and the estate bought a queue.
|
||||
- **It forks the schema per level.** Three levels, three object models, one
|
||||
broken promise.
|
||||
- **Awareness leaks into the signature.** If a last-used role or a tenant
|
||||
orientation hint enters `view_hash`, the surface signs something the person
|
||||
did not commit to.
|
||||
- **Highlights shrink the legal object.** If acking three highlights is
|
||||
presented as binding only those three sections, the UI has produced a lie.
|
||||
- **An agent binds.** If any automation can complete a disposition on a
|
||||
principal's behalf, the identity half is fiction.
|
||||
- **It reimplements `approval-engine`.** Caching approval validity, inferring
|
||||
consumption from a decision record, or holding approval current-state here
|
||||
breaks `GH-DEC-2026-003` and the atomicity contract.
|
||||
- **It invents identity.** A local password, a local session token that is not
|
||||
derived from `key-cape`, or a self-issued assurance level.
|
||||
- **Nobody uses it.** If `approval-engine` never receives an `approval:approve`
|
||||
token from this component's client, the surface is decorative and the gap it
|
||||
claimed to close is still open.
|
||||
|
||||
## Success Criteria
|
||||
|
||||
1. `key-cape` holds a registered browser client whose `client_id` and callback
|
||||
URI this repository owns and published, and `KEY-WP-0013-T02` is unblocked.
|
||||
2. A human approver completes an approval entry against `approval-engine`
|
||||
entirely through this surface, with an access token carrying
|
||||
`aud=approval-engine`, `principal_type: human`, and scope `approval:approve`.
|
||||
3. The approval entry is reconstructable from a `view_hash` — the estate can
|
||||
show what the approver was looking at.
|
||||
4. Required highlights cannot be bypassed: a bind attempt without acks fails.
|
||||
5. `return`, `discuss`, and `escalate` are exercisable on a real approval and
|
||||
are not modelled as `decline`.
|
||||
6. The same schema renders an L0 login banner and an L2 ADR accept, with the
|
||||
binding/awareness split intact and the isolation vectors green.
|
||||
7. An evidence bundle exports and verifies offline against
|
||||
`audit-core`'s record of the same transitions.
|
||||
8. No endpoint in this repository answers an authorization question.
|
||||
Loading…
Add table
Add a link
Reference in a new issue