AISA v2.0 / Technical documentation / Components — Development module
Components — Development module
F verified factP decided planC open challenge
Purpose
For the Development module (id source), Development Module says what the module does and Stage Planning says where a change goes. This page says what has to be built: every component, its kind, what it consumes and produces, how it is proved done, and who can build it without waiting for anyone else. It is the phase-1 deliverable for this module and the work breakdown for phase 2 (Delivery § 1, Delivery § 1.4).
The six component kinds are defined once, in Components — Configuration § 0.
What makes this module's breakdown different. Configuration splits by stage and Support by symptom domain. Development splits by source — one implementer agent per repository or per database side, because the repositories differ in language, build system and failure modes, and because the customer's lineage is not the main branch. The module is built against the idea of a source, never against one estate: a source is a configuration row naming its repositories, its database side, its branch model and start flows, its seam catalogue, its build and test gates and its deploy mechanism (D58).
1. The map
flowchart TB C["Typed case contracts"]:::store A["Published agent profiles"]:::work S["Executable skills"]:::work G["Auditor, gates and grants"]:::decision X["Connector execution"]:::work P["Proof and delivery"]:::proof M["Experience and evaluation"]:::learn C -->|"validated input"| A A -->|"invoke"| S S -->|"effect proposal"| G G -->|"authorised operation"| X X -->|"recorded result"| P P -.->|"learn after result"| M M -.->|"published revision"| A classDef work fill:#eef4ff,stroke:#6889ba,color:#17365b,stroke-width:1.3px classDef decision fill:#fff4df,stroke:#b78c36,color:#65470d,stroke-width:1.5px classDef proof fill:#e9f5ef,stroke:#689b81,color:#224e39,stroke-width:1.3px classDef learn fill:#f1edf9,stroke:#9580b9,color:#534172,stroke-width:1.3px classDef store fill:#f5f7fa,stroke:#98a6b7,color:#34445a,stroke-width:1.2px classDef owner fill:#24486b,stroke:#24486b,color:#ffffff,stroke-width:1.4px click C href "../contracts.html" "Inputs, selected plan, obligations and signed result contracts are built first." click A href "source-module.html" "planner; repository implementers; test runner, reviewer and deployer" click S href "../50-agents/agents-memory.html" "Deterministic procedures and assertions; no target permission is inherited from a skill." click G href "../gating.html" "Every applicable requirement is bound to the current proposal." click X href "../contracts/Connectors.Abstractions.cs.html" "Registered read operations and separately granted effects use their own recovery form." click P href "../case-protocol.html" "Verify the complete requested target and any external dependencies." click M href "../50-agents/agents-memory.html" "Record outcome; evaluate proposed knowledge or skill changes before reuse."
Development component responsibilities. The tables below enumerate each profile, skill and connector; this map shows their contracts and handoffs.
2. Contracts
| Component | What it fixes | Done test |
|---|---|---|
| The brief | what the human approves before any code: the reproduction or the evidence standing in for it, the chosen seam with the three rejected alternatives, the blast radius, the branch set across every repository and the database side, the test plan per lineage, the deployment and revert path (Stage Planning § PL-4) | a brief that cannot name the branch set is not ready — it means the case does not yet know which code it is fixing. Draft brief.schema.json (D139) |
| The branch set | which code this case is fixing: a branch per repository plus the database model and stored code on that environment's database, each object with its PLSQL-SIG-1 signature (Stage Planning § 3c) |
the set resolves to real branches, and the divergence is measured on demand, never quoted stale. Draft branch-set.schema.json |
| The cross-repository contract | for a change spanning two repositories: the shape both sides agree on, and the deploy order | named in the brief before either side is written (Development Module § 1). Draft cross-repo-shape.schema.json |
| The handover packet | request → response → completion for Hd in both directions (Agents § 5, D142) | the receiving root plans from the packet alone. Draft handover-packet.schema.json |
3. Agents
P The graph — who spawns whom, which sub-agents are isolated, and where the write path runs. The table under it carries every profile in full; the platform-wide profiles these draw on are Agents § 1.
flowchart TB R["Development root"]:::owner P["Planning and specialist tasks"]:::work K["Own index and
selected domain knowledge"]:::learn T["Typed plan and result papers"]:::store V["Independent review"]:::proof G["Required decisions"]:::decision E["Execution coordinator"]:::work R -->|"assign bounded task"| P K -.->|"context"| P P -->|"propose and report"| T T -->|"independent evidence"| V V -.->|"verdict"| R T -->|"reviewable packet"| G G -->|"permit"| E classDef work fill:#eef4ff,stroke:#6889ba,color:#17365b,stroke-width:1.3px classDef decision fill:#fff4df,stroke:#b78c36,color:#65470d,stroke-width:1.5px classDef proof fill:#e9f5ef,stroke:#689b81,color:#224e39,stroke-width:1.3px classDef learn fill:#f1edf9,stroke:#9580b9,color:#534172,stroke-width:1.3px classDef store fill:#f5f7fa,stroke:#98a6b7,color:#34445a,stroke-width:1.2px classDef owner fill:#24486b,stroke:#24486b,color:#ffffff,stroke-width:1.4px click R href "source-module.html" "The root owns the bounded objective and confirms child plans." click P href "source-module.html" "planner; repository implementers; test runner, reviewer and deployer" click K href "../50-agents/agents-memory.html" "Read compatible knowledge; consult its owner for judgement; write only in owned domains." click T href "../case-protocol.html" "Task text, evidence, scope and completed assertions remain durable." click V href "../50-agents/agents.html" "The verifier or reviewer receives scoped evidence without the author's transcript." click G href "../gating.html" "Root presents unresolved scope and permission decisions; it cannot invent authority." click E href "../50-agents/agent-runtime.html" "The deterministic handler applies only a current permitted packet."
Task ownership and review: a profile is reusable across cases. Each task has its own parent, inputs, evidence and restricted tool catalogue; the root remains responsible for the result.
| Agent | Owns, and its hardest judgement | In → Out | Memory (boots from → writes) | Tools (env scope) | Denied | Escalates | Eval set |
|---|---|---|---|---|---|---|---|
source.root |
the case, the brief gate, the script gate, the deploy gate, the reversal gate; incoming handovers from the Support root and from Configuration (D143) — whether this is a defect, a small extension, or work that belongs to the estate's program process | operator or Hd handover → case; brief → H2; corrections → H3; scripts → H4; deploy → H5; reversal → H7 | source/ |
none directly | write executors | the human | merged changes → the same gate sequence |
source.planner |
S1: reproduction, branch set, placement, test plan, revert path — the seam. It is the expensive decision, it lasts for years, and it is always human-approved (Gating § 1) | defect / extension → reproduction or evidence, branch set across repos + DB, placement (seam + three rejected + blast radius), test plan, revert path → the brief | source/ + repo nodes → none |
gitlab (read), oracle (read on the start env), kibana, experience index | writes | root | past changes → the seam actually chosen, and the blast radius actually seen |
source.implementer.<source> — here source.implementer.serdica-backend |
S3 for one service of that source: commits on the case branch, tests — when an unknown contract needs the owning agent rather than a third attempt | brief → commits on the case branch, test evidence; unknown DTO contract → consult after two attempts | source/serdica-backend/<service> (summarizer creates it if missing) → that node |
gitlab worktree (write in worktree only), dotnet build/test runner | pushes to protected branches, deploy | root | merged changes in that service |
source.implementer.serdica-ui |
S3 for the front end — the same, plus what a screen change means for the operator | as above for the UI | source/serdica-ui → that node |
gitlab worktree, nx build/test, browser (read) | as above | root | merged UI changes |
source.implementer.db-plsql |
S3 for the database side: extract, three-way merge against the live body, an apply script with a signature precondition — that a second author edits these objects directly and commits nothing | brief → extract, three-way merge against the live body, apply script with precondition, block-hash audit | source/db-plsql → that node |
oracle plsql snapshot + signature (read), write packet for the executor, caller sweep | apply without signature precondition; schema-wide recompile | root | applied changes with their signature evidence |
source.camunda_developer |
process file authoring and the migration statement — what happens to running instances when the definition changes | process brief → BPMN / generated task file change + migration or teardown statement | source/serdica-backend/core → proposal to the backend owner |
Camunda REST read; worktree generator scripts | deploy; start/terminate/migrate without a gate | root | process changes with runtime proof |
source.db_extractor |
PL/SQL snapshot + signature — a read-only extractor, separate from the stored-code implementer | object + environment → source snapshot, digest, status and dependency/caller evidence | source/db-plsql → none |
oracle read per environment | write, apply, recompile | root | stored-code changes with matching signatures |
source.reviewer isolated |
the verdict on the diff — placement, diff shape, coverage — from the diff and the brief, with no author context | diff + tests + brief → Verdict (placement, diff shape, coverage) |
source/ → none |
gitlab (read), build/test runner | author context | root | merged changes with their review verdicts |
source.deployer |
S6–S9: the script set per named target, the port to the main line, the deploy request, the runtime verification, the revert path — the blast radius of a library change — every consuming service image on that environment | approved set → target scripts + port prepared + revert path; after the target gate → deploy request and runtime verification (which commit serves; stub detection) | source/ → none |
gitlab (port commits, case-branch push for MR, MR), oracle (DDL packet to the executor), the deployment agent’s pipeline trigger on the estate’s serdica-infrastructure job (D130 — Ablera DevOps keeps the rights and the compose units), runtime verification reads |
deploying without H5 on customer-facing targets; QA deploy without H4 + the write auditor (D114) | root; H7 | deployed changes → the same script set and the same consumer list |
source.implementer.intentgpt |
stage S3 | as above | source/intentgpt (built on first case) → that node |
gitlab (if the repo is reachable) | as above | root; DeadEnd if the repo is unreachable |
— |
P Implementer agents are per source, and the set is configuration. For the first customer's estate that is a backend repository with a child node per service, a front-end repository, a separate behaviour repository, and the environment databases' stored code. Another customer declares its own sources and gets its own implementer profiles; the module does not change.
P A missing repository node is never a prerequisite. When an agent needs a node that does not exist, a summarizer sub-agent reads the service — its code, its guidance file, its build and test surface, its recent history — and creates the node before the work continues (Agents § 0.6).
4. Skills
| Skill | What it does | What it asserts |
|---|---|---|
| worktree + build + test runner | an isolated worktree per repository per case; the build, the unit tests, the front-end build and its tests | the build is the authority; a language-server diagnostic is not |
| PL/SQL snapshot + signature | one row per environment × object × digest, append-only, mirrored to a repository the platform owns alone | the signature decides whether the source changed; a timestamp cannot carry that decision, because a recompile bumps it whether or not a change is in it |
| PL/SQL apply with precondition | the capture → preflight → apply → verify → compensate loop | the signature recorded at extraction is a precondition of the write grant; if the other author saved in between, the apply is refused after authorised read preflight and before DDL; external-writer exclusion is also required and a three-way merge re-enters the gate |
| release audit | which commit actually serves on the target after a deploy | a valid database object can still be a stub; stack lines and versions are the evidence |
| port between layouts | a fix carried between two source layouts: feasibility check, path rewrite, layout files excluded, the pipeline file regenerated | the port is a commit of its own naming the source commit; "no counterpart" is an allowed recorded outcome |
P Six standing prohibitions, each with its guard and each a recorded incident (Stage Planning § 3b): never replace from a stale extract (the signature precondition); never promote a specification without its body (both objects in one script set); never run a schema-wide recompile (it erases the change signal); never change a specification with remote dependents without a plan for the far side (the cross-database dependency check as a plan step with an assertion); never delete a routine without sweeping its callers; never overwrite a snapshot in place (the store is append-only).
5. Connector operations
| Connector | Operations | Effect class |
|---|---|---|
gitlab |
read; worktree; commit inside the worktree; push the case branch (never a protected branch) to open the merge request; merge under H4; read the infrastructure repository to enumerate a deploy set | controlled Git write; protected branches are never pushed directly |
oracle |
stored-code snapshot and signature; DDL packet with a signature precondition; the dependency sweep; the caller sweep | the write executor applies DDL under the HW-ddl gate with the identity of the current D65 stage (D104) |
ssh / host |
read-only commands on an allow-list; a privileged command as a gated write | an operations action such as a restart is a write with its own gate |
kibana |
the runtime verification reads | read |
6. Memory domains
| Domain | Owning profile | Holds |
|---|---|---|
source/ |
source.root; planner reads/proposes | the seam catalogue per source, the placement criteria, the port procedure, the branch and environment map |
source/<repository> |
the repository implementer | the service index, build truths, the path map per layout, the packaging model |
source/<repository>/<service> |
the same | per-service knowledge, created on the first case that works it |
source/db-plsql |
the stored-code implementer | the extract-and-apply workflow, the release audit, the exit seams, the per-environment model |
P Divergence numbers live in memory with their measuring query, never as a quoted figure, because they change (Development Details DG-3).
7. What can be built in parallel
| Wave | Components | Notes |
|---|---|---|
| 1 | the brief contract; the planner with the seam catalogue; the worktree and test runner | the planner is the module's core judgement and its eval set is the past changes |
| 2 — one track per source | each implementer agent with its repository domain | disjoint repositories, disjoint domains |
| 2 — beside them | the reviewer; the snapshot and signature skill | the reviewer needs only diffs and briefs; the snapshot skill is independent of every agent |
| 3 | the deployer, the port skill, the release audit | they consume what wave 2 produced |
8. What this module does not build
- New modules or new product capability. Its scope is defects and small extensions; module-scale work follows the estate's program process (Non-Goals N-8).
- The deploy itself. The platform prepares the packet; the deployment agent resolves the environment's pipeline job by rule and triggers it after the gate (D130), and the write executor applies DDL under
HW-ddl(Development DG-8, D104). - Changes to the incumbent system's code. Those remain change requests to the customer (Non-Goals N-1, N-10).
Challenges
- P Attribution for the stored-code side is not solved: the source view carries no author column, and the audit trail returned a complete identity for one actor and none for another on the same schema the same day. Artefacts therefore state what changed and when, and name an actor only where an audit row supports it (Stage Planning § 3b).
- C A source that is not in the workspace has unmapped seams; its node is built on the first case that touches it.