informed-decision/GOAL.md

repo	category	stage	stage_status	started
informed-decision	product	1	active	2026-09-09

Flavor note. This is a durable product repository, not a prj- project repository. Per project-repository-flavor_v0.1.md, durable products use INTENT.md and an ordinary category; the prj- flavor is for bounded cross-repo coordination efforts and is not used here. GOAL.md is retained as the stage statement: INTENT.md is stable and aspirational, this file is what the current stage must achieve and is replaced when the stage turns over.

Goal — informed-decision, Stage 1

Outcome

The approver UI has an owner, and it is this repository.

Stage 1 is complete when a human approver can be shown a approval-engine approval request on a surface this repository owns, understand it, act on it with a vocabulary richer than approve/reject, and leave behind a reconstructable record of what they were shown when they bound themselves — and when key-cape holds the browser-client registration it has been waiting for since 2026-09-08.

Two things are being settled at once, and they are the same thing:

1. The ownership question. approval-engine disowns the inbox by design and named the gap in docs/keycape-service-registrations.md. Nobody picked it up. Stage 1 picks it up, in writing, with a catalog placement agreed by gate-house rather than asserted.
2. The capability. A browser-facing approver surface that presents approval:approve tokens to approval-engine and records the presentation.

Why this is the first stage

The founding exploration reaches L5 — multi-party international instruments. Stage 1 deliberately does not. It takes the narrowest real consumer with a live blocking dependency, because a decision surface with no consumer is a design document, and this estate already has enough of those.

The approval approver flow is L3 on the depth spectrum. It is the right first cut because it is the only level currently costing another repository progress.

What Stage 1 delivers

• INTENT.md, GOAL.md, SCOPE.md, and a layer.yaml derived from a gate-house answer.
• The four specs: docs/specs/ProductRequirementsDocument.md, docs/specs/UseCaseCatalog.md, docs/specs/ArchitectureBlueprint.md, docs/specs/EvidenceModel.md.
• The Decision Memo schema promoted out of history/ into schemas/, with the canonicalizer and the isolation vectors under test in CI.
• A published OIDC browser-client contract — client_id and callback URI — handed to key-cape, closing KEY-WP-0013-T02.
• A working L3 approver surface against a deployed approval-engine.

What Stage 1 explicitly does not deliver

• L4/L5, QES, QTSP integration, or qualified archival retention.
• Multi-party parallel sign-off (Mitzeichnung across several parties at once).
• The mandate graph. Stage 1 routes to a named approver; it does not maintain a living map of who may bind what. Without that map, escalate is only forwarding — this is a known and accepted Stage 1 limitation, recorded here so it is not discovered later as a defect.
• EUDI Wallet / eID identity import. Identity comes from key-cape only.
• A general workflow engine, a notification transport, or a ticketing system.

Invariants

These hold for Stage 1 and for every stage after it.

• access-engine remains the only policy decision point. This repository renders questions and records answers. No endpoint here answers "may this actor do X". A disposition recorded on a memo is evidence of a human act, not an authorization verdict.
• approval-engine remains the sole owner of approval state. This surface calls its mutations and reads its introspection claim. It never caches validity, never infers consumption, and never holds approval current-state. GH-DEC-2026-003 ordering is honoured: decision, then consume, then act.
• approved is never rendered as permission to act. It is a state of an object. Presenting it as "you may now do the thing" is a policy decision point in the browser.
• Entitlement to view is access-engine's. A 200 from approval-engine is not permission to see the approval; that engine never answers "may this actor do X". This surface obtains a decision before rendering and never substitutes local judgment for it.
• Identity is imported. Every principal on this surface is authenticated by key-cape. No local credential, no self-issued assurance level. Human principals carry principal_type: human and are refused approval:consume by the engine — this surface must never attempt it.
• The binding/awareness split survives contact with the first consumer. view_hash covers only what the person committed to. Proposed roles, other-tenant orientation and last-session summaries are hashed separately and are not signed unless explicitly promoted into awareness_promoted.
• One question per memo. An approval that bundles three unrelated acts is three memos.
• Humans bind, agents draft. An agent may assemble a memo and may not complete a disposition.
• The schema does not fork. Any Stage 1 field added for approvals must be expressible for an L0 login banner, or it does not go in the shared object.

The question Stage 1 must answer in writing

Who owns the approver UI?

The answer this repository proposes, to be ratified rather than assumed:

• informed-decision owns it — the surface, the presentation record, the browser client, and the evidence of informedness.
• It is PEP-shaped, not an Engine: it is browser-facing and causes a protected side effect on the far side of a decision, so it owes companion §5 and statute §6.4.
• It supplies exactly one PIP-like fact — what was presented — as a claim carrying view_hash, issuer and freshness, and it never evaluates that fact.
• The catalog row does not exist yet. INFD-WP-0001-T02 asks gate-house and writes layer.yaml from the ruling. If gate-house places this component elsewhere, INTENT.md and this file change to match — the ruling wins.

Definition of done

1. gate-house has ruled on the layer placement and layer.yaml reflects it.
2. key-cape has the client_id and callback URI, and KEY-WP-0013-T02 is unblocked with the answer traceable to this repository.
3. The four specs exist, are reviewed against the current approval-engine, access-engine, key-cape and audit-core contracts, and name their external gates.
4. view_hash / awareness_hash are computed by code in this repository, and the four isolation vectors from the exploration are green in CI.
5. One approval is approved end to end by a human through this surface against a deployed approval-engine, and the resulting approval entry is reconstructable from a stored presentation.
6. return and discuss are demonstrated on a real approval and are distinguishable from decline in the record.

Stage 2 and beyond — direction only, not commitment

L0 informed login/elevation in front of key-cape, then L2 ADR accept against the estate's own decision records. Those two prove scale invariance downward and sideways. L4 contract paths and any QES work wait for a named buyer and a retention answer, both open questions in the founding exploration.