Principles, Requirements, Governance & Change
The Preliminary phase's principles and tailoring, the requirements catalog that sits at the centre of the wheel with traceability to components and gates, the risk register, and Phases G and H expressed as what the platform itself enforces.
Preliminary · Architecture principlesSix absolute principles, four supporting — each with rationale and implications
absolute cannot be waived by configuration or by a reviewer · supporting may be tailored per domain with a recorded decision.
P01 · Subgraph, never the schema absolute
StatementGeneration agents receive a retrieved, cited subgraph (≤30 tables by default), never the full schema.
RationaleSchema size must not change the cost or precision of a use case; models pick wrong identifiers from large candidate sets.
ImplicationsSemantic catalog is a prerequisite; groundedness gate rejects uncited tables; subgraph budget enforced by the supervisor.
P02 · Contracts, not generated code absolute
StatementAgents emit schema slices and UI specs; resolvers are compiled, screens are rendered. Code generation exists only as a reviewed exception into a registry.
RationaleA thousand generated codebases cannot be secured or audited; contracts can be verified deterministically.
ImplicationsDSL and compiler are platform assets; escape-hatch rate is a tracked metric; no agent has a code-execution tool.
P03 · Authorization declared once, compiled in absolute
StatementClassified fields carry a policy on the schema; entitlements are composed into the SQL from validated claims before execution. Post-filtering is prohibited.
RationaleA control every workflow must remember is not a control; recall collapses under post-filtering for narrow-permission users.
ImplicationsPolicy catalog as data; 100% coverage gate; compiler refuses roles it cannot scope; edge never holds business authorization.
P04 · Reads publish, writes propose absolute
StatementNo generated artifact writes to a system of record directly. Write actions create proposals; approval is enforced by the platform from the registration.
RationaleThe structural bound against prompt injection is the write path, not a classifier.
ImplicationsProposal service is mandatory; PUBLISH_WRITE unreachable without an approval event; autonomous-safe targets are a policy decision, not a composer decision.
P05 · The release unit is the whole tuple absolute
StatementCatalog version, slice, UI spec, policy version, model deployment, prompt template versions and component versions are released and pinned together.
RationaleA change to any element changes behaviour; a provider rolling a model is a release you did not perform.
ImplicationsModel versions pinned; drift triggers re-verification; reviewers approve a tuple, not a file.
P06 · A human approves first publish and every write absolute
StatementGates decide what can be measured; a person decides the rest, on evidence, for every first publish and every write path.
RationaleJudgment is the scarce resource; the architecture exists to spend it on approving contracts rather than writing them.
ImplicationsReview workspace is core, not optional; auto-publish applies only to read-only re-publishes and only by registration.
P07 · Generation never touches production data supporting
StatementAgents see catalog cards, masked profiles and synthetic sample data. Runtime is the only path to production rows.
ImplicationsSandbox environment; PII-aware profiling; environment rule = data rule.
P08 · Deterministic wherever possible supporting
StatementSupervisor, compiler and gates are deterministic; the model contributes proposals and prose, never decisions.
ImplicationsTyped events only; same input → same SQL; gate results are not overridable by model output.
P09 · Refuse rather than guess supporting
StatementAmbiguity in requests or schema is returned to a person; retries are capped; dead ends park.
ImplicationsClarification loops in intake; ambiguity events from the Scout; glossary learns from resolutions.
P10 · Everything traceable to its sources supporting
StatementEvery table cites a card; every screen names its release unit; every query is logged with its predicate set.
ImplicationsTrace store is a first-class component; any bad screen is replayable into a golden case.
Tailoring decisions (Preliminary)
- Phases A–D produce diagrams and catalogs for a product; no enterprise-wide landscape is attempted.
- Phases G and H are realised by the platform's own gates and drift handling rather than a separate governance board — the platform is the compliance mechanism.
- Requirements Management uses one catalog with IDs traced to components and gates; no separate requirements tool.
- Building blocks: ABBs are the capabilities (B1); SBBs are the components (C5) and technology choices (D4).
- Iteration: the ADM is run once per transition architecture (TA-0 … TA-4), re-entering at Phase E each time.
Requirements Management · Requirements catalogFunctional and non-functional requirements with traceability to components and gates
| ID | Requirement | Type | Realised by | Verified by | Priority |
|---|---|---|---|---|---|
| FR-01 | A prose request becomes a typed use-case spec, or a clarifying question, or a refusal | Functional | Intake service · archetype library | Spec schema validation · M1 exit | Must |
| FR-02 | Retrieval returns a subgraph ≤30 tables with join paths, each citing a catalog card | Functional | Catalog service · Scout | Groundedness gate · M0 precision/recall | Must |
| FR-03 | Composer emits a federation-compatible slice with policies on every classified field and persisted operations | Functional | Contract composer · policy service | Composition gate · policy coverage gate | Must |
| FR-04 | UI composer emits a valid UI spec bound only to persisted operations; unexpressible needs become custom-component requests | Functional | UI composer · DSL validator | Binding validity gate · a11y gate | Must |
| FR-05 | Write actions are proposals; approval enforced from the registration | Functional | Proposal service · supervisor | Absence test: no direct write path in CI | Must |
| FR-06 | Reviewer sees spec, subgraph rationale, SDL diff, policy and gate reports, and a live preview on sample data | Functional | Review workspace · artifact store | M4 exit walkthrough | Must |
| FR-07 | Catalog drift re-verifies affected use cases automatically and degrades on failure | Functional | Crawler · event workers · registry | M5 exit: renamed-column scenario | Must |
| FR-08 | Custom components reach the registry only through sandboxed build, scan, screenshot diff and human review | Functional | Sandbox runner · registry UI | M5 exit: escape-hatch scenario | Should |
| NFR-01 | Zero unscoped queries reachable at runtime; every operation compiles scoped for every actor role | Security | Query compiler · policy service | Entitlement-compile gate · CI absence test | Must |
| NFR-02 | 100% of classified fields carry a policy; protected fields nullable; deny-by-default | Security | Contract composer | Policy coverage gate | Must |
| NFR-03 | Only persisted operations are executable; query text is rejected at the edge/gateway | Security | Supergraph gateway · persisted store | M2 exit: unknown id rejected | Must |
| NFR-04 | Generation never reads production data; sandbox holds synthetic data only | Security / privacy | Environment design (D2) | Network policy review · PII scan gate | Must |
| NFR-05 | Any screen's SQL is reproducible from the trace, with its predicate set | Auditability | Trace store · compiler logging | M6: reproduction drill | Must |
| NFR-06 | Persisted operations run under a cost ceiling with actual arguments; N+1 batched | Performance | Query compiler · cache | Cost & complexity gate | Must |
| NFR-07 | Response cache cannot serve across entitlement fingerprints and busts on catalog generation change | Security / correctness | Response cache keying | Golden tests: narrow-permission user cases | Must |
| NFR-08 | Per-run budgets (steps, tokens, wall-clock, cost) fail closed | Cost | Supervisor · LLM gateway | M1 exit: budget exhaustion parks | Must |
| NFR-09 | Machine time per use case in minutes; reviewer throughput ~10/hour (targets) | Performance / usability | Archetypes · review workspace | M6 metrics | Should |
| NFR-10 | Screens meet accessibility baseline (labels, contrast, keyboard order, table semantics) | Accessibility | Component registry · DSL lint | Accessibility gate | Should |
| NFR-11 | Model deployments pinned; upgrades are dated releases re-verified against golden sets | Operability | LLM gateway · release unit | Golden tests on model change | Must |
| NFR-12 | Every artifact and decision is versioned; nothing hard-deleted | Auditability | Registry · platform DB | CRUD matrix review (C4) | Must |
Risk registerTop risks, likelihood × impact, mitigation and owner
| ID | Risk | L × I | Mitigation (structural first) | Owner | Residual |
|---|---|---|---|---|---|
| R-01 | Retrieval selects a wrong join path; screen shows plausible wrong numbers | M × H | Query-log-mined paths ranked above inferred; golden tests per archetype incl. identifier queries; review preview on sample data | Platform eng | Low-medium |
| R-02 | Classification gaps let a sensitive column ship without a policy | M × H | Classification coverage is a prerequisite gate per domain; PII scan on sample results; deny-by-default for unknown fields | Data owners · Security | Low |
| R-03 | Prompt injection via catalog descriptions or request text steers a composer | M × M | Agents have no write or execution tools; typed outputs; gates are deterministic; write path unreachable without approval | Security | Low |
| R-04 | Escape-hatch usage climbs; governance load moves to code review | M × M | Escape-hatch rate tracked; DSL grows by adding components; registry reuse | Platform eng | Medium |
| R-05 | Reviewer throughput becomes the bottleneck | H × M | By design; evidence bundle optimised; auto-publish for read-only re-publishes by registration | Domain owners | Accepted |
| R-06 | Generated queries overload systems of record | M × H | Cost ceilings with real arguments; batching; entitlement-aware cache; read replicas | Platform eng · DBAs | Low |
| R-07 | Model provider changes behaviour silently | M × M | Pinned deployments; upgrade as a dated release; golden sets rerun | Platform eng | Low |
| R-08 | Supergraph composition slows or breaks at ~1,000 slices | L × M | Namespaced, small slices; incremental composition; retirement schedule | Platform eng | Low |
| R-09 | Ambiguous enterprise schemas stall intake with repeated questions | H × L | Glossary learns from resolutions; owner backlog of naming decisions surfaced as a report | Data owners | Accepted |
| R-10 | Reference-implementation numbers are read as production claims | M × M | Every artifact labelled "target / reference"; metrics published with caveats at M6 | Author | Low |
Phase G · Implementation governanceCompliance checkpoints are the platform's gates; the architecture contract is the registration
Compliance checkpoints (automated)
- Composition — no conflicts, no breaking change to live operations
- Policy coverage 100% — every classified field, nullable, deny-by-default
- Entitlement compile — every operation scoped for every actor role
- Cost & complexity — under ceiling with real arguments; batched
- Binding validity — every UI binding and action resolves
- Golden tests — archetype-derived, on sample data
- PII exposure scan — sample results vs. classification
- Accessibility lint — DSL-level
- Groundedness — every table and join cites a card
Failures route back at most twice, then park. Gates never auto-override.
Compliance checkpoints (human)
- First publish of any use case — domain owner
- Every write path — owner of the target system (e.g. Finance)
- Every custom component — platform engineering
- Every domain enablement — security (classification coverage) and data owner (descriptions reviewed)
Decisions are immutable and reference the release unit they approved.
The architecture contract = the registration
A use case's registration is the contract between the owning team and the platform: actors, allowed actions, autonomous-safe targets (never for regulated data), auto-publish rules for read-only re-publishes, review routing, budgets. The platform enforces it; the team cannot bypass it per screen.
Dispensations
Absolute principles P01–P06 admit no dispensation. Supporting principles may be tailored per domain with a recorded decision, an expiry, and a re-verification on expiry. Every dispensation is a row in the platform DB, not an email.
Phase H · Architecture change managementChange triggers, the automatic response, and when a human is called
| Trigger | Detected by | Automatic response | Human involvement | State |
|---|---|---|---|---|
| Schema drift (table/column added, renamed, dropped; FK change) | Crawler diff → new catalog version → event | Every use case whose subgraph touches the change is re-verified (gates only). Pass → re-pinned. Fail → degraded: banner, slice pinned to last passing version, owner paged | Owner fixes or re-runs generation; reviewer approves the new release unit | live / degraded |
| Policy change (classification or entitlement) | Policy version event | Affected slices re-checked for coverage and entitlement compile; failures degrade | Security signs the policy version; domain owners re-approve affected write paths | as above |
| Model deployment retirement / upgrade | LLM gateway deployment registry | Golden sets re-run on the candidate deployment; release units re-pinned only on pass | Platform engineering schedules the dated release | scheduled release |
| Prompt template or archetype change | Template registry version | Seeded use cases regenerated in sandbox and diffed; regressions block the template | Platform engineering reviews diffs | gated |
| DSL / runtime version | Runtime release | Runtime supports N-1 spec versions; specs migrated by a validated transform | Platform engineering; domain owners informed | compatibility window |
| Component version update | Registry event | Screens referencing the component re-verified (bindings, a11y, screenshot diff) | Reviewer approves visual change if diff exceeds threshold | gated |
| Use-case retirement | Usage telemetry below threshold for N periods | Proposed for retirement; slice removed from supergraph on approval; release unit archived | Owner confirms | retired |
| New domain enablement | Request | Classification coverage report; owner-review queue for descriptions | Security + data owner sign; ADM re-entered at Phase E for the domain | enabled |
The Architecture Development Method is re-entered at Phase E for every transition architecture and for every new domain; Phases A–D are revisited only when an absolute principle would change — which is a new architecture, not a change.