Single-page docs. Schemas, endpoints, design rules, and the EU AI Act mapping that the framework is built around.
Proposal schema
What an agent system POSTs to /api/proposals. The shape is identical across TX-1, SS-1, and Swarm Lite; system-specific payloads live inside proposed_action as opaque key/value pairs.
proposed_action_descriptionplain-language version for the UI
manifest_context.versionmanifest version at generation time
alternativesarray of { label, rejection_reason }
risk_flagsstring[] — manifest risk-factor IDs
context_itemsarray of { label, type, sensitive? } — drives Zone C
implications{ if_approved, if_dismissed }
DecisionRecord schema
The immutable artifact produced on every confirmed decision. Three layers plus governance metadata. The integrity hash is SHA-256 over the sealed fields (reasoning + action + governance), sorted-keys JSON.
record_idstring · prefix DR-
proposal_idback-reference to the originating Proposal
POST /api/proposalsSubmit a new Proposal from a source system. Returns { proposal_id, status }.
GET /api/proposalsList awaiting proposals. ?status=all for everything.
GET /api/proposals/{id}Single proposal.
POST /api/decisionsCommit a decision. Returns the freshly-built DecisionRecord with integrity_hash.
GET /api/recordsList all decision records, newest first.
GET /api/records/{id}Single record.
POST /api/admin/resetDemo-only.
Integration boundary
A source agent system POSTs a Proposal when it surfaces a decision that needs human approval. On commit, the sidecar POSTs a DecisionCallback back to the source system's registered callback URL. action_to_execute equals the original proposed_action for an Approve, differs for an Override, and is null for a Dismiss.
The same boundary applies to SS-1 and Swarm Lite.
EU AI Act mapping
Article 12 — LoggingDecisionRecord with record_created_at, retention_until, and an immutable integrity_hash. Stored for the retention period; reproducible from the schema alone.
Article 13 — Transparencybrief_as_presented contains the full agent reasoning + confidence + alternatives. The approver saw this; the regulator sees the same bytes.
Article 14 — Human oversightThe gate mechanic prevents rubber-stamping on consequential decisions. Rationale is captured for every Override and Dismiss. The decided_by tier is recorded.
Article 71 — Serious incident reportingHooks for outcome confirmation exist (outcome_layer). A serious-incident reporting integration is Phase 4.
Design-system rules
These rules are enforced in code, not just in the design. They come from the project's ADRs and CLAUDE.md.
Approve / Override / Dismiss are visually equal (ADR-006). No action is larger or more colourful than the others.
Decision type drives the top-of-card accent before any text is read. Routine = subtle hairline. Consequential = amber. Escalation = red.
Approve is gated on Zone-C open for CONSEQUENTIAL proposals.
Confidence lives in Zone D (reasoning), never in the header.
brief_as_presented is captured verbatim and sealed in SHA-256.
No Tailwind. Pure CSS using var(--cds-*).
No rounded corners on data surfaces. Carbon Tag/Button defaults are fine.
IBM Plex Sans (body) + IBM Plex Mono (IDs/code). Never JetBrains Mono — that's the TX-1/SS-1 terminal aesthetic.
Manifest schema (Phase 4)
The shared manifest is the rules document all three agent systems reason against. Markdown-under-git, versioned per commit. Proposals carry the manifest version they were made against. Manifest updates are themselves proposals — the Manifest Diff View renders the before/after for approver review.
Schema is in 03_MANIFEST_SCHEMA.md. Phase 4 brings the manifest editor and version-timeline views into the app.
