AISA v2.0 / Technical documentation / Requirements Register (appendix)
Requirements Register (appendix)
F verified factP decided planC open challenge
The consolidated requirement register, grouped by area. Each requirement is elaborated — with reasoning and evidence — in the linked document; this register is the lookup, not the narrative. There is no acceptance-check column and the register does not carry one: the acceptance checks live in Metrics (every target with its basis, D111) and in the per-component done tests of Delivery § 1.4. Namespaces: G-nn, P-nn, C-nn, S-nn and D-n here are requirement ids; G-1 … G-19 cited from Case Studies are that page's gap ids, and P-nn / C-nn cited from Product Configurator are its pattern and contradiction ids — different registers, cite the page with the id. Sources: the planning conversations of 28–31.08.2026, the reviews of 31.08.2026, and the Product Configurator § SRC.
Sources
The authority for these requirements, in order of precedence:
| Source | Contributes |
|---|---|
| The planning conversations of 28 and 31 August 2026 and the reviews of 31.08.2026 and 01.09.2026 | every requirement below; where a later statement contradicts an earlier one, the later governs |
| Product Configurator § SRC → Product Configurator § P | the twenty patterns marked proven rather than planned |
| Baseline | measured AISA v1 facts — volumes, effectiveness, failure record |
serdica-backend master and codex/health-ai-csharp-architecture, inspected 31.08.2026 |
the reuse map, the estate's service and branch topology |
memory/, knowledge/system.md |
domain facts; each cited at the point it is used |
| Support contract (BG, authoritative) and procedures (EN, unofficial translation) | contract classification, severities, SLA |
| The investigations of 02.09.2026 — Measurements § RE, Measurements § DB (QA, STAGING, PROD; read-only), Challenge Rounds § GA, the three case-study sets, Challenge Rounds § CS | the F corrections of that day and the P proposals awaiting decision |
| The review of 02.09.2026 — decisions on POL-only, the QA database, roles not users, no third-party harness, handles, approval as a permission | the corrections of that day; Agent Runtime § 9 carries the harness survey with its primary sources |
F Most DB-shaped statements cite the memory or knowledge article that carries them rather than a fresh query. Two exceptions carry live measurements taken 01.09.2026 and label them as such: the pricing-factor configuration model (Stage IPAL § PF-7–8b, Ablera dev) and the PL/SQL change cadence (Stage Planning § 3b, Bulstrad QA). P Everything else is re-verified against the running system before being relied on for build work.
General
| ID | Requirement | Elaborated in |
|---|---|---|
| G-1 | Web-accessible, concurrent, auditable platform inheriting AISA's memories and experience | Platform, Baseline |
| G-2 | Work runs as graphs of profiled agents: module roots → stage agents → profiled sub-agents; lateral consults allowed; doubt travels upward; only the root hands to the human | Agents Memory |
| G-3 | Write execution is configurable; the human always decides writes to protected targets and materially missing information | Home framework, Architecture CR-2 |
| G-4 | Child plans are confirmed by the immediate parent; a plan-only request is not implementation authority | Agent Runtime |
| G-5 | Sessions: stoppable, resumable, deletable; many viewers, exactly one controller | Agent Runtime |
| G-6 | Stage sets and vocabularies are defined per module and task shape — the framework is not mandatory rails | Home framework |
| G-7 | Verification is per stage; deployment scope is chosen per case; production execution and reversal are human gates | Configuration Module § 2–3, Non-Goals N-12 |
| G-8 | Agents control the business process; Camunda is a connected system and configuration target, never the agents' orchestrator | Non-Goals N-4 |
| G-9 | One shared memory: a tree of domains with an AGENTS.md index per node; agent == domain; writes only inside the own domain (the dreaming protocol) |
Agents Memory |
| G-10 | Documentation: ATA-Spec-100-style consolidated statements, plain relative links, every statement fact / plan / challenge; the goals chapter carries no diagrams (D150) — every chart lives in the architecture chapter | Home |
| G-11 | Content observed through a connector is data; authority comes from grants and gates, never from content | Trust and Data, Architecture CR-8 |
| G-12 | No agent turn spans an uncommitted write; every plan step declares its effect class | Failure and Recovery, CR-9 |
| G-13 | The build is two phases; phase 2 divides by discipline — connectors and skills are the widest seams, the agent tracks need domain knowledge and no code — and reaches a real case by module: wave 1 Configuration, wave 2 Development and Support together with the remaining platform infrastructure (D80, D82) | Delivery § 1–§ 1.4 |
| G-14 | Approval is a permission, not a second person: a gate is answered by whoever holds the role for it and its target; a holder approves their own case, a non-holder's gate becomes a task for holders | Trust and Data § 3, UI |
| G-15 | Every open challenge is listed in a generated register with class, owner and resolving event | Challenges Register |
| G-17 | Money is not a metric of this platform: no figure on any page is expressed in currency. Provider spend is a control, never evidence that the platform works. The measures are hours, bus factor, people involved, knowledge domains involved, elapsed time and vendor dependency removed (D52, D79) | Value and ROI, Metrics |
| G-16 | The goals chapter is complete against the twelve dimensions — actors, inputs, outputs, lifecycle, decisions, failures, boundaries, measures, data, economics, evolution, logic — and audited on record | Challenge Rounds § GA, PG-9…PG-22 |
Platform
| ID | Requirement | Elaborated in |
|---|---|---|
| P-1 | C# implementation in serdica-backend: src/Serdica/Ablera.Serdica.AI.Support (module layout mirroring Ablera.Serdica.AI), reusing the codex/health-ai-csharp-architecture assets |
Platform Details PG-1, Architecture § 1–2 |
| P-2 | Native agent loop with skills, tools, memory, sub-agents, model adapters — patterns adopted from surveyed harnesses; model replaceable without rewriting session records | PG-2, Architecture § 6, Agent Runtime |
| P-3 | Many read sessions + one control session per case | PG-3, Agent Runtime |
| P-4 | Reuse Serdica authentication (Authority), RabbitMQ transport, SRD_SYS EndPoints registration |
PG-4, Architecture § 3 |
| P-5 | UI: a dedicated serdica-ui administration section — live sessions incl. each sub-agent's stated reasoning and every memory operation; skills and memories manageable independently under permissions | PG-5, Architecture § 3 |
| P-6 | Audit log in a pre-determined, tool-parsable format; metrics computed by tools | PG-6, Metrics |
| P-7 | All external access through per-system connector agents | PG-8, Agents Memory § 1, § 4 |
| P-8 | Data boundary per module: Configuration handles no personal data (identifiers in intake are removed at the connector — operator-agnostic case, D57); Support runs only on GDPR-compliant EU-resident models | Platform Details PG-7, CG-9, SG-9 |
| P-9 | An agent profile is versioned data with declared model route, tool grants, memory domains, denied context, escalation policy, budget and eval set | Agents |
| P-10 | Prompts and skills are owned, versioned, tested before publication and revertible — the mechanism that lets several authors work concurrently | Agent Framework |
| P-11 | Grants scope environment × system × target × mode, are bound to the approved artefact, expire, and are refused at the connector before contact; gates are answered by a holder of the role for that target — approval is a permission, not a second person | Trust and Data § 2–3 |
| P-12 | The audit ledger is append-only and tamper-evident; corrections are linked records; the evidence graph is a projection over it | Architecture § 3.2 |
| P-13 | The runtime is an event-sourced turn loop: context assembled from the ledger, typed inter-agent messages carrying artefact references, approval as a paused run, checkpoints with pending gates, no turn spanning an uncommitted write; patterns adopted from surveyed harnesses with sources | Agent Runtime |
| P-14 | The platform is developed and first deployed on the Bulstrad QA environment; SRD_SUPPORT lives on db.serdicaqa.bulstrad.bg; the hosting, network reach, service accounts and operations model are written down |
Software Architecture, Architecture § 1 |
| P-15 | Nothing is linked from the unmerged health-AI branch: per project the verdict is name-only, copy-source, or nothing | Software Architecture |
| P-16 | The UI is two surfaces, both wireframed before build: the operator surface of eight workspaces around the case chat — Inbox, Cases, Decisions, Studio, Knowledge, Metrics, Control — and the client surface of four — my requests, one request, acceptance, and the self-service intake marked as the target state and not the first build (D91, D99, D119) | UI § 1, § 5 |
| P-17 | The software is specified component by component — one deployable, our libraries with their public surfaces, copied and linked libraries, plug-ins, data stores, dependency rules | Software Architecture |
| P-18 | The agent framework is specified as contracts an author relies on — declarations, guarantees, what it does not decide, the author's checklist | Agent Framework |
| P-19 | Every agent profile of every module is catalogued — boots from, writes, tools per environment, messages in and out, denied context, escalation, budgets | Agents |
| P-20 | Each module is a graph of profiled agents — root, stages, isolated sub-agents, executors, connectors — instantiated as task data; consults are evidence, handovers are gates | PG-24, Agents |
| P-21 | One memory tree, agent == domain, governed articles, experience index, migration accepted on a measured hit-rate against a held-out case set | PG-25, Agents Memory § 1–7 |
| P-22 | The UI is the only human surface: gates answered in the inbox, sessions watched in the view, skills and memory changed under permissions there | PG-26, UI |
| P-23 | Exactly two ways one module reaches another, not interchangeable: a consult asks for knowledge — an isolated read-only sub-agent inside the asking case, answering as evidence, never authority — and a handover (Hd) asks for a changed system, opening a sub-case behind prior human confirmation. The consult catalogue is configuration (D92) | Agents § 5, § 5b |
| P-24 | An arrival is routed by a platform profile, not by a module: platform.intake normalises, stamps the origin key, dedups, resolves the customer and checks the initiation right, names the case type and the duplicate verdict, and opens every client case on support.root — it never names the working module. Naming it is Support's S1 and the route at gate H2; the help-desk queue's Configuration default is an S1 classification hint (D143, narrowing D93). It always decides, one operator action re-routes, and routing is configuration |
Agents § 5b, § 5c, Support Module § 0 |
| P-25 | Initiation is a grant per customer × role × module governing starting only, with three outcomes — granted, may request, not granted — and every cell a plug-in value; a request carries its origin and the modules it involves on every client screen (D97, D98) | Trust and Data § 3b, Agents § 5c |
| P-26 | Gating is built, not only declared: a stage agent produces a closed-form packet and is denied the means to skip; a gate is a row, not a call; and a write shape earns auto-confirm through observed → shape-approved → policy-confirmed, returning to stage 1 on a revert, an auditor refusal, a red eval set, a template change or a withdrawn risk class (D72, D73, D90) | Gating § 1–§ 9 |
Configuration
| ID | Requirement | Elaborated in |
|---|---|---|
| C-1 | Any-connector intake, pre-checked (obvious misses asked early) and normalized into the whitelabel specification, every field cited | CG-1, Stage Normalization |
| C-2 | Each stage investigates what its target storage expects before writing; plans carry per-step assertions | CG-2, Configuration Module § 2 |
| C-3 | Comparable-product comparison is desirable, not a prerequisite | CG-2 |
| C-4 | Stages in two phases: S1 Normalization, then phase 1 Abacus, then 2A Serdica and 2B IPAL + Offer at the same time, closed by the joint proof (D75); every stage runs the same ten-phase protocol (gather → plan → confirm H2 → apply → test → iterate H3 → scripts → approve scripts H4 → approve execution H5 → deploy → verify) | CG-3, Configuration Module § 1–2 |
| C-5 | Skill-based testing: getRates (manufacture requests, assert produced tariffs), offer, and policy skills | CG-4 and the stage documents |
| C-6 | Pricing factors: POL sale stage only, no exceptions — the QT path is being obsoleted; agents never create QT rows, a quote-step dependency is a MISSING entry | CG-4, Stage IPAL |
| C-7 | Serdica wiring is SRD_SYS."Routes", SRD_SYS."EndPoints", core appsettings.json registration, numbering, print and LT_USER_ROLES (roles only). The BPMN process is not wiring — registering it against the product is IPAL configuration and belongs to S3; authoring one is Development work at Hd (D86) |
Stage Serdica, Stage IPAL |
| C-8 | The human gate set, defined once for the platform and instantiated per module: H1–H7 · Hd · the write gates HW-approve, HW-instance, HW-shared, HW-irreversible, HW-ddl (D104) · H5-SIM (D42, D107) · H5-send · publish (D10) · and the customer's acceptance, CG-11 (D72, D107, D116) | Gating § 1, CG-6 |
| C-9 | All stages outlined graphically, each marked as agent graph or human gate; the detailed diagrams live in the module | Configuration Module |
| C-10 | Verification per stage; deployment scoped (abacus only · abacus+ipal · full), with smoke tests on the target | CG-5, Configuration Module § 3 |
| C-11 | One written stage contract — what each stage consumes, produces, asserts and may not do — so five stage prompts can be authored concurrently | Configuration Module |
| C-12 | The whitelabel specification has a field catalogue with per-field provenance, a mandatory layer model, two-way reconciliation counts and unresolved[] as a deliverable |
Stage Normalization |
| C-13 | Sessions stoppable, resumable, deletable; many viewers, one controller (CG-7); reversal first-class with teardown per applied change, executed at H7 (CG-8); no personal data, with the scope defined (CG-9) | CG-7, CG-8, CG-9, Configuration Details |
| C-14 | Commercial position before H1; customer acceptance as a gate; STAGING gated like production; specification quality measured | CG-10…CG-13 |
| C-15 | The INSIS side of a dual-system product is not configuration work — one PL/SQL script per product, a named deliverable with an owner, changed as Development work at Hd. No S3b, no insis specification section, no INSIS teardown; the proof ladder ends at issued (D85) |
Stage IPAL § The INSIS side, Configuration Module § 7 |
| C-16 | A module is nothing more than its stages: every cross-cutting document is folded into the stage that owns it, and every stage page names its agents, its isolations, the memory domain it owns, its skills and its branch of the graph (D87) | the five configuration stages |
Support
| ID | Requirement | Elaborated in |
|---|---|---|
| S-1 | Any-connector intake (the ticket system, mailboxes, the help desk, in place on the client surface — any channel the plug-in names) into one case model | SG-1, Support Module |
| S-2 | Methodology-driven investigation — the v1 catalog inherited as mechanics | SG-2, Support Details |
| S-3 | Recurring/long-running work precipitates into skills, memories, experience entries | SG-3 |
| S-4 | Solution take by kind — skill / memory / configuration / source / combination — with module handovers under prior human confirmation | SG-4, Support Module § 1 |
| S-5 | Routing by request type and support level, like a support organization | SG-5, Support Module § 2 |
| S-6 | Past-experience index over resolved cases; building the well-outlined AISA v1 memory is a goal | SG-7, Agents Memory § 6 |
| S-7 | Memory migration is per domain and accepted on a measured triage hit-rate against a held-out case set, not on a file count | Agents Memory |
| S-8 | A skills catalogue names the executable skills the modules need, each justified by ticket evidence — occurrences, current effort, effort with the skill | Agents Memory and Skills |
| S-9 | The value case is written as a cost model that includes time, bus factor and context-switching, with the measurement that will replace each estimate | Value and ROI |
| S-10 | Gated customer-visible output and protected-target writes with held batches (SG-6); durable, transferable sessions (SG-8); EU-resident models only (SG-9) | SG-6, SG-8, SG-9 |
| S-11 | Tiered isolated verifier; always classify with a correction metric and a reclassification rule; cancel state; external-owner steps; memory-retraction review | SG-10…SG-14 |
| S-12 | Investigation is entered from the take: S1 hands the case to S3, which asks whether a ready solution exists; only a case with none enters S2. The stage numbers name the documents, not a running order; the isolated verifier sits inside S2 and is not a stage; S6 verification is the customer's symptom re-checked on the customer's surface (D83, D84) | Support Module § 1–§ 2, Stage Solution Take, Stage Investigation |
| S-13 | The desk is the root module: every client request classified, identified and routed at H2 — waiting with its trigger, clock treatment and age, a handover, or the working stages under the same root — and one voice to the customer | SG-15, Support Module § 0–2; D143, D147, D149 |
Source (ad-hoc development)
| ID | Requirement | Elaborated in |
|---|---|---|
| D-1 | Scope: bug fixes and small extensions over existing functionality — not new modules | DG-1, Source Module |
| D-2 | Start environment per case-type configuration (source.start_flows, D63) and per product line (D123): running products develop locally, start on bulstrad-staging → master + bulstrad-qa; new, unreleased products (the health line) start on bulstrad-qa → backport to master → the planned bulstrad-prod-2; bulstrad-prod deployment scripts |
DG-2 |
| D-3 | Environment = branch set across intentgpt, serdica-ui, serdica-backend + the DB model and PL/SQL on the environment's database; divergence state kept in memory | DG-3 |
| D-4 | Placement first: customer-specific plugin / microservice / PL/SQL exit; core only via a proposition; human brief (why, blast radius, test plan) before development | DG-4, Stage Planning |
| D-5 | Deployment, testing, and reversal are mandatory parts of every case | DG-5 |
| D-6 | Stages, one page each: planning → approval → implementation → test and corrections → deployment scripts → deploy and reversal. DG-7's merge request gates the exit of S5 (D84, D87) | Source Module § 1–§ 2 |
| D-7 | Repository-profiled agents booting from source/<repo> domains; repository knowledge in memory, not documents |
DG-6, Agents Memory § 4 |
| D-8 | A reviewed merge request before deployment scripts; deployment executed by the estate's mechanism from the platform's packet; placement, backport and revert measured | DG-7…DG-9 |