Sync Repo-docs-INSTITUTIONAL-GOVERNANCE-TARGET-ARCHITECTURE from project files

2026-08-01 10:30:36 +02:00
parent 844cf430f6
commit 1eb36f9028
@@ -1,4 +1,4 @@
<!-- codex-wiki-sync:c77a5cc3bd33ec0ad256741f --> <!-- codex-wiki-sync:b69ec174cdf58e1ed7d06d7f -->
> Mirrored from `/mnt/DATA/git/govoplan/docs/INSTITUTIONAL_GOVERNANCE_TARGET_ARCHITECTURE.md`. > Mirrored from `/mnt/DATA/git/govoplan/docs/INSTITUTIONAL_GOVERNANCE_TARGET_ARCHITECTURE.md`.
> Origin: `repository`. > Origin: `repository`.
@@ -65,50 +65,56 @@ accepted as the current baseline and must not be reopened as greenfield work.
| Separate headless workflow runtime and editor | Implemented as `govoplan-workflow-engine` and optional `govoplan-workflow`. Module-owned workflow baselines are versioned and reconciled without replacing local overrides. | | Separate headless workflow runtime and editor | Implemented as `govoplan-workflow-engine` and optional `govoplan-workflow`. Module-owned workflow baselines are versioned and reconciled without replacing local overrides. |
| Provider-neutral external references | Implemented in Core with stable external identity and cumulative integration maturity from discovery through replacement. | | Provider-neutral external references | Implemented in Core with stable external identity and cumulative integration maturity from discovery through replacement. |
| Governed asynchronous effects | Implemented foundations include the action/effect contract, transactional platform event outbox, module outboxes, idempotency, outcome-unknown states, reconciliation, and worker health. Coverage still varies by provider. | | Governed asynchronous effects | Implemented foundations include the action/effect contract, transactional platform event outbox, module outboxes, idempotency, outcome-unknown states, reconciliation, and worker health. Coverage still varies by provider. |
| Acting identity, function assignment, and ownership recovery | Implemented foundations span Identity, Organizations, IDM, Access, generic ownership transfer/recovery, and audit provenance. Mandate and jurisdiction context remain missing. | | Acting identity, function assignment, mandate, and ownership recovery | Implemented foundations span Identity, Organizations, IDM, Access, Mandates, generic ownership transfer/recovery, and audit provenance. Effective competence now resolves through a tenant-bound Mandate capability. |
| Governed data foundations | Connectors, Datasources, Dataflow, Reporting, and Search now exist. Datasources already provides live/cached/static modes, staging, immutable materializations, and publication contracts. | | Governed data foundations | Connectors, Datasources, Dataflow, Reporting, and Search now exist. Datasources already provides live/cached/static modes, staging, immutable materializations, and publication contracts. |
| Task-focused projections and configured documentation | Views, view-surface declarations, configurable dashboards, and manifest-driven user/admin documentation exist. Rollout and content depth remain incremental. | | Task-focused projections and configured documentation | Views, view-surface declarations, configurable dashboards, and manifest-driven user/admin documentation exist. Rollout and content depth remain incremental. |
| Encryption as an optional capability | `govoplan-encryption` now defines key-vault, content-protection, recovery, and disable-preflight boundaries. It is not a reason to move domain ownership into Core. | | Encryption as an optional capability | `govoplan-encryption` now defines key-vault, content-protection, recovery, and disable-preflight boundaries. It is not a reason to move domain ownership into Core. |
| Search without mandatory OpenSearch | PostgreSQL-backed, permission-aware search and module provider contracts exist; OpenSearch remains an optional adapter. | | Search without mandatory OpenSearch | PostgreSQL-backed, permission-aware search and module provider contracts exist; OpenSearch remains an optional adapter. |
| Scale-out and recovery architecture | Stateless API/worker, shared database/object storage, event delivery, deployment, and recovery contracts are documented and partly exercised. Production profiles and drills remain active work. | | Scale-out and recovery architecture | Stateless API/worker, shared database/object storage, event delivery, deployment, and recovery contracts are documented and partly exercised. Production profiles and drills remain active work. |
The important remaining work is primarily **institutional semantics, consistent The institutional semantics, provider declaration gate, and first product
provider declarations, and product packaging**, not another runtime rewrite. compositions described here are now implemented. Subsequent work is
**product depth and stronger maturity evidence**, not another runtime rewrite
or an unimplemented architecture boundary.
## Implementation status (2026-08-01) ## Implementation status (2026-08-01)
The first implementation tranche establishes the cross-module contracts and a The architecture contract is implemented as a bounded, executable vertical
bounded proof without prematurely creating new semantic repositories: slice. The portfolio declarations and provider governance gates apply to the
whole workspace, while the four semantic domains whose repository thresholds
were proven now have independent persistent owners:
| Area | Implemented state | Remaining rollout | | Area | Implemented state | Remaining rollout |
| --- | --- | --- | | --- | --- | --- |
| Module portfolio metadata | Core validates versioned architecture layer/kind, maturity evidence, known limits, ownership boundaries, authority modes, reference packages, target-tested providers, and migration/upgrade/recovery/security/operations documentation. | Adoption is staged. The workspace check reports coverage and can enforce complete adoption with `--require-architecture` after every module has truthful evidence. | | Module portfolio metadata | Core validates versioned architecture layer/kind, maturity evidence, known limits, ownership boundaries, authority modes, reference packages, target-tested providers, and migration/upgrade/recovery/security/operations documentation. | Complete for all 60 source manifests. Focused and release checks enforce `--require-architecture`; a new module cannot enter the workspace without truthful declaration and repository-local evidence. |
| External providers | Core validates provider objects/field groups, operations, integration maturity, source authority, bounded reads, freshness/health, idempotency, conflicts, outcome-unknown handling, evidence, correction, reconciliation, outage, classification, purpose, retention, and secret handling. Connectors proves read-only external mirrors; Calendar proves writable governed synchronization and supplies tenant-aware CalDAV binding state. | Remaining providers must declare the contract and sanitized runtime state when their behavior and evidence can be stated accurately. | | External providers | Core validates provider objects/field groups, operations, integration maturity, source authority, bounded reads, freshness/health, idempotency, conflicts, outcome-unknown handling, evidence, correction, reconciliation, outage, classification, purpose, retention, and secret handling. Addresses/CardDAV, Files remote storage, Mail SMTP/IMAP, Calendar CalDAV/ICS/Graph/EWS, and Connectors tabular/sanctions providers declare the contract and tenant-bounded secret-free runtime state. | Registry validation rejects any declared external provider without a sanitized state provider. Future adapters must cross the same gate before activation. |
| Institutional context | Core provides versioned temporal, actor/representation, institution/unit/function/task/mandate/jurisdiction/service/case/party/work-item/workflow/approval/decision/record, legal-basis, evidence, information-governance, external-source, presentation, and geographic references. Events, automation actions, audit records, and the transactional Audit outbox preserve the envelope. | Owning modules must progressively require the relevant subset for consequential operations. | | Institutional context | Core provides versioned temporal, actor/representation, institution/unit/function/task/mandate/jurisdiction/service/case/party/work-item/workflow/approval/decision/record, legal-basis, evidence, information-governance, external-source, presentation, and geographic references. Events, automation actions, audit records, and the transactional Audit outbox preserve the envelope. | Owning modules must progressively require the relevant subset for consequential operations. |
| Semantic provider contracts | Provider-neutral DTOs and protocols now cover Mandate resolution, versioned Service definitions, procedure Parties/representation, and formal Decisions. Mandate resolution is deterministic across effective time, unit, function, jurisdiction, task, authority, subject, and conflicts; immutable Mandate and Decision lifecycle helpers enforce OCC and allowed transitions. | Persistent provider lifecycles remain subject to issues #30-#33 and their repository thresholds. | | Semantic provider contracts | Provider-neutral DTOs and protocols cover Mandate resolution, versioned Service definitions, procedure Parties/representation, and formal Decisions. `govoplan-mandates`, `govoplan-services`, `govoplan-parties`, and `govoplan-decisions` now persist immutable revisions behind those contracts with tenant isolation, bounded reads, replay safety, OCC, migrations, uninstall guards, permissions, APIs, capability documentation, and recovery documentation. | The owners are deliberately headless. Procedure-specific UI remains with consuming modules. |
| Formal-outcome proof | Committee has a capability-based decision path that resolves effective mandate authority, jurisdiction, approval, legal basis, evidence, reasoning, responsible human/service actor, automation assurance, and operative result into a reconstructable formal Decision without importing optional module tables. Decision corrections, revocations, supersession, and stale updates now have a shared immutable revision rule. | A second consuming domain and persistent provider are still required before extracting a Decisions module. | | Formal-outcome proof | Committee resolves effective Mandate authority and records a reconstructable formal Decision through `decisions.registry` when installed, while retaining an optional local projection when it is absent. Decision corrections, revocations, supersession, protected reads, and stale updates use the shared immutable revision rules. | Committee meeting/agendum/vote persistence remains Committee product depth, not a missing Decisions architecture primitive. |
| Service-to-case proof | Portal projects optional provider-owned Service definitions into available, explainably unavailable, or undiscoverable entries. Cases consumes the same exact Service version into a governed intake plan retaining case/form/workflow/result, responsibility, Mandate, jurisdiction, legal basis, evidence, and deadline references. A meta composition test proves both consumers without cross-module table access. Restrictive derivation preserves parent provenance and prevents tenant/package specializations from widening effective time, audience, channels, publication, prerequisites, evidence, legal bases, or bindings. | A persistent definition provider remains threshold-based; Portal is still a headless projection without a service-directory WebUI. | | Service-to-case proof | Services owns the persistent exact definitions consumed by Portal discovery and Cases intake. Publication and availability remain separate, restrictive derivation cannot widen parent constraints, and the provider hides draft/retired definitions from general discovery. | Portal and Cases remain headless vertical slices; their later WebUI/persistence depth does not alter Service ownership. |
| Procedure-party proof | Cases resolves effective procedure parties from the optional `parties.resolver` capability and falls back to a bounded local projection containing no representation lifecycle. Downstream delivery receives only permitted channels and immutable contact-snapshot/evidence references; expired or revoked representation authority is excluded. | Provider-side access/correction depth and a second procedure consumer remain before a Parties repository crosses its threshold. | | Procedure-party proof | Parties persists effective procedure roles, frozen contact snapshots, and representation powers. Existing powers cannot disappear or be silently rewritten; explicit OCC-guarded revocation is required. Cases resolves the provider capability and excludes expired/revoked authority from downstream delivery. | Procedure modules still decide which contextual fields and actions to present. |
| Integrated institutional journey | An executable meta fixture carries one exact Service version through Portal discovery, Case intake, procedure-party representation and frozen delivery authority, effective Mandate resolution, approval, formal Committee Decision, confirmed Postbox effect, Audit record, remedy/review, and protected evidence reconstruction. | The fixture is a contract proof, not a claim that all corresponding persistence and WebUI surfaces are reference-ready. | | Integrated institutional journey | The executable `product.service-to-decision` fixture uses real SQL-backed Services, Parties, Mandates, and Decisions providers. It carries one exact Service version through Portal discovery, Case intake, representation and frozen delivery authority, effective Mandate resolution, approval context, a persisted formal Committee Decision, confirmed Postbox effect, Audit/record evidence, remedy/review, and protected reconstruction. | This is architecture and composition evidence. Target accessibility, privacy, operator, delivery-provider, and recovery-drill evidence is still required before the package may claim `reference_ready`. |
| Governed data catalogue | Datasources stores typed governance metadata, exposes bounded tenant-scoped filters and update APIs/UI, carries governance through staging, and snapshots it into immutable materializations. | Rich dependency/impact traversal and policy-specific field visibility can grow on the catalogue contract without moving connector or transformation ownership. | | Governed data catalogue | Datasources stores typed governance metadata, exposes bounded tenant-scoped filters and update APIs/UI, carries governance through staging, and snapshots it into immutable materializations. | Rich dependency/impact traversal and policy-specific field visibility can grow on the catalogue contract without moving connector or transformation ownership. |
| Product/package governance | Signed configuration packages distinguish reference, product, sector, deployment, and integration classes; preserve parent/evidence provenance; prevent derived packages from loosening constraints; and preflight provider authority, maturity, exact binding, health, freshness, and recovery expectations. Executable product manifests now exist for governed communication and governed data/assurance and are checked in the module matrix. | Both artifacts deliberately remain product-class until target, accessibility, privacy, security, operations, and recovery evidence justifies reference readiness. | | Product/package governance | Signed configuration packages distinguish reference, product, sector, deployment, and integration classes; preserve parent/evidence provenance; prevent derived packages from loosening constraints; and preflight provider authority, maturity, exact binding, health, freshness, and recovery expectations. Executable product manifests now exist for governed communication and governed data/assurance and are checked in the module matrix. | Both artifacts deliberately remain product-class until target, accessibility, privacy, security, operations, and recovery evidence justifies reference readiness. |
| Projection and release | Platform metadata, signed module catalogs, release synthesis, Ops, and role-aware Docs retain and display architecture/provider declarations. Module-owned state providers add bounded configured/active, authority, health, freshness, conflict, recovery, and observation state; ordinary-user Docs omits binding detail. Static checks validate evidence paths, and the WebUI build verifies consuming types. | Runtime-state adoption and broader portfolio presentation follow truthful provider declaration rollout. | | Projection and release | Platform metadata, signed module catalogs, release synthesis, Ops, and role-aware Docs retain and display architecture/provider declarations. Module-owned state providers add bounded configured/active, authority, health, freshness, conflict, recovery, and observation state; ordinary-user Docs omits binding detail. Static checks validate evidence paths, and the WebUI build verifies consuming types. | Runtime-state adoption and broader portfolio presentation follow truthful provider declaration rollout. |
The tranche deliberately does not create shared institutional tables in Core, The implementation deliberately keeps shared reference contracts in Core and
claim unsupported maturity, or turn candidate module issues into empty domain tables in their owners. It does not claim unsupported release maturity:
repositories. Gitea remains authoritative for the incomplete lifecycles. the four extracted owners and package remain `vertical_slice`/`product` until
target evidence supports a stronger claim. Gitea remains authoritative for
feature depth beyond this architecture contract.
## Target capability layers ## Target capability layers
The layers describe ownership and dependency direction. They are not navigation The layers describe ownership and dependency direction. They are not navigation
groups and do not imply that every installation exposes every module. groups and do not imply that every installation exposes every module.
| Layer | Responsibility | Current and candidate owners | | Layer | Responsibility | Current owners and declared directions |
| --- | --- | --- | | --- | --- | --- |
| 0. Runtime and meta | Composition, release, migrations, shared contracts, operations, deployment | Core, meta repository, Admin, Ops | | 0. Runtime and meta | Composition, release, migrations, shared contracts, operations, deployment | Core, meta repository, Admin, Ops |
| 1. Institutional foundation | Institution, tenant, identity, organization, function, authority, access, trust | Tenancy, Identity, Organizations, IDM, Access, Identity Trust, Encryption; candidate Mandates | | 1. Institutional foundation | Institution, tenant, identity, organization, function, authority, access, trust | Tenancy, Identity, Organizations, IDM, Access, Identity Trust, Encryption, Mandates |
| 2. Governance and accountability | Policy, audit, risk, control, explainability, configured projection | Policy, Audit, Risk Compliance, Docs, Views, Search; candidate Decisions | | 2. Governance and accountability | Policy, audit, risk, control, explainability, configured projection | Policy, Audit, Risk Compliance, Docs, Views, Search, Decisions |
| 3. Human work and procedure | Intake, cases, tasks, approvals, process execution and editing | Forms, Forms Runtime, Cases, Tasks, Approvals, Workflow Engine, Workflow, Tickets; candidates Services and Parties | | 3. Human work and procedure | Intake, cases, tasks, approvals, process execution and editing | Services, Forms, Forms Runtime, Cases, Parties, Tasks, Approvals, Workflow Engine, Workflow, Tickets |
| 4. Communication and participation | Delivery, participation, scheduling, channels, consultation | Portal, Postbox, Notifications, Mail, Campaign, Calendar, Scheduling, Poll, Appointments, Booking, Consultation, Committee, Addresses, Distribution Lists | | 4. Communication and participation | Delivery, participation, scheduling, channels, consultation | Portal, Postbox, Notifications, Mail, Campaign, Calendar, Scheduling, Poll, Appointments, Booking, Consultation, Committee, Addresses, Distribution Lists |
| 5. Content, records, and evidence | Managed content, templates, records, knowledge, disclosure | Files, Templates, DMS, Records, Wiki, Transparency, Certificates | | 5. Content, records, and evidence | Managed content, templates, records, knowledge, disclosure | Files, Templates, DMS, Records, Wiki, Transparency, Certificates |
| 6. Data, reporting, and integration | Source access, staging, transformation, search, analytics, protocols | Connectors, Datasources, Dataflow, Reporting, Dashboard, REST, SOAP, XOE/V, XTA/OSCI, FIT-Connect, XRechnung, ERP adapters | | 6. Data, reporting, and integration | Source access, staging, transformation, search, analytics, protocols | Connectors, Datasources, Dataflow, Reporting, Dashboard, REST, SOAP, XOE/V, XTA/OSCI, FIT-Connect, XRechnung, ERP adapters |
@@ -128,20 +134,22 @@ combines them.
| Identity and account | Who is the person or machine, and through which account do they act? | Identity and Access | | Identity and account | Who is the person or machine, and through which account do they act? | Identity and Access |
| Function assignment | Who holds or represents a function, for which interval and source? | IDM | | Function assignment | Who holds or represents a function, for which interval and source? | IDM |
| Role and permission | What application behavior may the acting principal perform? | Access, constrained by Policy | | Role and permission | What application behavior may the acting principal perform? | Access, constrained by Policy |
| Mandate and jurisdiction | Why is an institution, unit, or function competent to act on this subject, territory, population, or interval? | Candidate Mandates capability | | Mandate and jurisdiction | Why is an institution, unit, or function competent to act on this subject, territory, population, or interval? | Mandates |
| Service | What governed promise can an institution offer, to whom, under which prerequisites, evidence, channel, deadline, and responsibility? | Candidate Services capability; Portal presents it | | Service | What governed promise can an institution offer, to whom, under which prerequisites, evidence, channel, deadline, and responsibility? | Services; Portal presents it |
| Case | Which concrete administrative matter is being handled? | Cases | | Case | Which concrete administrative matter is being handled? | Cases |
| Party | In what procedural capacity does a person or organization participate, and who may represent or receive for it? | Candidate Parties capability; Identity/Organizations remain the subject owners | | Party | In what procedural capacity does a person or organization participate, and who may represent or receive for it? | Parties; Identity/Organizations remain the subject owners |
| Work item | What must a responsible actor do next? | Tasks and domain modules | | Work item | What must a responsible actor do next? | Tasks and domain modules |
| Workflow | How is work coordinated, including waits, human hand-offs, and governed actions? | Workflow Engine; Workflow is the optional editor | | Workflow | How is work coordinated, including waits, human hand-offs, and governed actions? | Workflow Engine; Workflow is the optional editor |
| Approval | Has a proposed action passed a configured review or separation-of-duties gate? | Approvals | | Approval | Has a proposed action passed a configured review or separation-of-duties gate? | Approvals |
| Decision | What formal institutional outcome was reached, by which competent authority, on which facts, rules, evidence, reasoning, and review path? | Candidate Decisions capability | | Decision | What formal institutional outcome was reached, by which competent authority, on which facts, rules, evidence, reasoning, and review path? | Decisions |
| Evidence and record | What proves the input, state, action, effect, correction, and retained institutional memory? | Domain owner, Files/DMS/Records, and Audit | | Evidence and record | What proves the input, state, action, effect, correction, and retained institutional memory? | Domain owner, Files/DMS/Records, and Audit |
### Candidate semantic modules ### Extracted semantic modules
Four horizontal concepts are not cleanly owned today. They are repository Four horizontal concepts passed the repository proof threshold. Their Core
candidates, not immediate repository mandates. DTOs and provider protocols remain neutral; their persistent data, lifecycle,
security, APIs, migrations, and recovery behavior now live in independent
repositories.
#### Mandates #### Mandates
@@ -150,11 +158,11 @@ decision/signature authority, legal or organizational basis, and effective
history. Organizations continues to own structures and functions; IDM owns history. Organizations continues to own structures and functions; IDM owns
incumbency; Access owns permissions; Policy owns constraints. incumbency; Access owns permissions; Policy owns constraints.
The first proof should answer: *Was this function competent to act for this `govoplan-mandates` answers: *Was this function competent to act for this case
case at the relevant time, and on what basis?* Start with a Core-neutral DTO and at the relevant time, and on what basis?* Its resolver evaluates effective
provider contract used by one Case/Decision journey. Create time, task, authority, unit, function, jurisdiction, subject, conflicts, legal
`govoplan-mandates` when the model has independent persistence, lifecycle, basis, and evidence deterministically. Missing or ambiguous authority fails
security, and more than one consumer. closed.
#### Services #### Services
@@ -164,10 +172,10 @@ jurisdiction, forms, case/workflow/result bindings, remedies, service levels,
and publication status. Portal presents and starts services but should not own and publication status. Portal presents and starts services but should not own
their institutional definition. their institutional definition.
The existing Portal service-directory concept remains the first presentation `govoplan-services` now owns those exact versioned definitions. Portal is the
surface. Extract `govoplan-services` when service definitions are consumed by first presentation consumer and Cases freezes the selected revision into its
Portal plus at least one of Cases, Forms, Workflow, Reporting, or external intake context. Availability is an independent capability so publication does
publication independently of Portal. not imply that all runtime prerequisites are satisfied.
#### Parties #### Parties
@@ -178,10 +186,10 @@ matter. Identity answers who the subject is; Organizations answers which
institutional unit it is; Addresses owns contact points; Parties answers how institutional unit it is; Addresses owns contact points; Parties answers how
the subject participates here. the subject participates here.
Cases currently sketches local party rows. That is a compatibility seed, not a `govoplan-parties` owns the shared effective-dated lifecycle. Cases retains a
reason to copy representation semantics into every domain. Define a shared bounded compatibility projection only when the module is absent; that fallback
reference contract first and extract `govoplan-parties` when a second procedure contains no representation lifecycle and cannot silently become a second
needs the same effective-dated representation lifecycle. authority source.
#### Decisions #### Decisions
@@ -192,10 +200,10 @@ and links to observed effects. Approvals own review gates; Poll owns response
collection; Committee owns deliberation, meetings, and votes; Workflow owns collection; Committee owns deliberation, meetings, and votes; Workflow owns
coordination. coordination.
Committee and Cases may retain temporary decision references, but the first `govoplan-decisions` owns the persistent lifecycle and protected reconstruction
regulated journey should use one shared Decision DTO and evidence contract. surface. Committee supplies deliberation context and records through the
Create `govoplan-decisions` when the lifecycle is persisted and reused outside provider capability. Consumers retain exact Decision references without
one domain. gaining table access.
## Source authority and integration maturity ## Source authority and integration maturity
@@ -227,7 +235,7 @@ tenant deliberately configures it as `external_mirror`.
### Provider declaration ### Provider declaration
Every provider that reads or causes external effects should eventually declare: Every provider that reads or causes external effects must declare:
- owned object and field groups; - owned object and field groups;
- supported source-authority modes and integration maturity; - supported source-authority modes and integration maturity;
@@ -238,11 +246,11 @@ Every provider that reads or causes external effects should eventually declare:
- degraded and outage behavior; - degraded and outage behavior;
- classification, purpose, retention, and secret-handling requirements. - classification, purpose, retention, and secret-handling requirements.
Current external-reference, action/effect, connector lifecycle, capability, The common provider declaration composes the external-reference, action/effect,
operational-check, and documentation contracts provide most of the primitives. connector-lifecycle, capability, operational-check, and documentation
The required change is a common declaration that composes them and can be contracts. Core, release tooling, Ops, Docs, and configuration-package
validated by Core, release tooling, Ops, Docs, and configuration-package preflight validate it; Registry refuses to activate a declared external
preflight. provider without bounded, sanitized runtime state.
## Cross-cutting contracts ## Cross-cutting contracts
@@ -278,8 +286,8 @@ families.
### Datasources becomes the governed data and register catalogue ### Datasources becomes the governed data and register catalogue
Keep the implemented live/cached/static, staging, immutable materialization, The implemented live/cached/static, staging, immutable materialization, and
and publication model. Add typed governance metadata for owner/steward, publication model includes typed governance metadata for owner/steward,
authoritative source and authority mode, legal basis and purpose, semantic authoritative source and authority mode, legal basis and purpose, semantic
definition, quality and freshness policy, classification, transfer agreement, definition, quality and freshness policy, classification, transfer agreement,
correction process, affected services/processes, and dependent flows, correction process, affected services/processes, and dependent flows,
@@ -340,8 +348,7 @@ work together for a bounded outcome. A sector package specializes vocabulary,
forms, rules, process baselines, controls, reports, and integration profiles forms, rules, process baselines, controls, reports, and integration profiles
without forking the platform. without forking the platform.
The existing signed configuration-package mechanism is the implementation The signed configuration-package mechanism distinguishes:
base. It should distinguish:
- **reference package:** tested composition proving a journey and its recovery - **reference package:** tested composition proving a journey and its recovery
behavior; behavior;
@@ -360,7 +367,7 @@ configuration and evidence. They do not gain access to module-owned tables.
## Module portfolio metadata ## Module portfolio metadata
Repository category is not capability maturity. The runtime manifest, release Repository category is not capability maturity. The runtime manifest, release
catalog, Docs projection, and meta repository inventory should converge on a catalog, Docs projection, and meta repository inventory use one
machine-readable declaration with at least: machine-readable declaration with at least:
- architecture layer and module kind; - architecture layer and module kind;
@@ -382,70 +389,84 @@ release reason, more than one consumer or a proven reference process, and tests
that justify the boundary. Otherwise use a shared DTO, provider capability, that justify the boundary. Otherwise use a shared DTO, provider capability,
submodule, configuration fragment, package, or profile. submodule, configuration fragment, package, or profile.
## Migration sequence ## Implemented migration sequence
### 0. Align the portfolio and contracts ### 0. Align the portfolio and contracts - complete
- Publish this reconciliation and correct stale roadmap/module statements. - This reconciliation is canonical in the meta repository and mirrored to the
- Add machine-readable portfolio/source-authority metadata with validation and Gitea wiki.
evidence-based maturity claims. - All 60 source manifests carry validated evidence-based architecture metadata.
- Compose the existing external-reference, action/effect, operational-health, - External-reference, action/effect, operational-health, ownership, policy,
ownership, policy, audit, and documentation primitives into one provider audit, and documentation primitives compose into one enforced provider
declaration. declaration and sanitized runtime-state contract.
- Add common institutional-context, legal-basis, evidence, and geo reference - Institutional context, legal basis, evidence, presentation, external source,
DTOs only where current contracts do not already cover them. information governance, temporal revision, and geo references are shared
Core DTOs rather than shared domain tables.
### 1. Prove responsibility and formal outcome ### 1. Prove responsibility and formal outcome - complete
- Define Mandate and Decision contracts. - Mandate and Decision contracts, deterministic resolution, lifecycle
- Use them in one bounded Case or Committee path with effective-time authority, transitions, persistence providers, APIs, permissions, migrations, recovery,
approval, reasoning, evidence, observed effect, correction, and review. and tests are implemented.
- Create separate repositories only when persistence and reuse pass the - Committee and the SQL-backed institutional fixture prove effective-time
repository threshold. authority, approval context, reasoning, evidence, observed effect,
correction/revision rules, protected reconstruction, and review references.
- The independent Mandates and Decisions repositories were created only after
persistence and reuse passed the repository threshold.
### 2. Separate service and party semantics ### 2. Separate service and party semantics - complete
- Keep Portal as the service presentation surface while extracting a reusable, - Portal remains the presentation surface while Services owns reusable,
versioned service-definition contract. versioned definitions and explainable availability.
- Replace duplicated case/procedure participant fields with a common Party - Parties owns procedure roles, contact snapshots, and append-only
reference and representation contract. representation/revocation authority; Cases consumes the common resolver.
- Prove both through one general administrative service package. - `product.service-to-decision` proves both through a portable administrative
service composition.
### 3. Complete governed data and assurance ### 3. Complete governed data and assurance - architecture complete
- Extend the Datasources catalogue with typed governance and dependency links. - Datasources carries typed governance through staging and immutable
- Complete Reporting semantic models and institutional indicator provenance. materializations, with bounded catalogue filters and dependency references.
- Generalize the Risk Compliance assurance graph after the sanctions vertical - Reporting owns semantic presentation/provenance contracts without taking
is accepted. source or transformation ownership; feature depth remains on its module
- Extend Projects from execution tracking into portfolio/outcome governance as backlog.
a consuming domain, not as a second policy or reporting engine. - Risk Compliance persists the horizontal obligation/risk/control/evidence/
finding/measure graph and projects sanctions runs idempotently.
- Projects declares portfolio/outcome ownership as a consuming domain without
becoming a second policy or reporting engine.
### 4. Package repeatable public-sector outcomes ### 4. Package repeatable public-sector outcomes - complete at product maturity
- Finish the active Campaign/Postbox/data/BI/document reference program. - Governed communication, governed data/assurance, and service-to-decision are
- Package governance foundation, governed communication, function-bound portable product package manifests with repository-local evidence.
collaboration, service-to-decision, procurement/contracts, and governed BI. - Package preflight enforces module, capability, provider authority, health,
- Add sector packages only after a reference package has target-environment, freshness, and recovery expectations without cross-module table access.
recovery, accessibility, privacy, and operator evidence. - Sector and `reference_ready` claims remain gated on target-environment,
recovery, accessibility, privacy, security, and operator evidence. This is a
maturity gate, not missing architecture implementation.
## Delivery tracking ## Delivery tracking
The cross-repository epic is The completed cross-repository architecture epic is
[GovOPlaN #29](https://git.add-ideas.de/GovOPlaN/govoplan/issues/29). [GovOPlaN #29](https://git.add-ideas.de/GovOPlaN/govoplan/issues/29).
Its new work packages are: Its implementation work packages and resulting owners are:
- [Core #279](https://git.add-ideas.de/GovOPlaN/govoplan-core/issues/279): - [Core #279](https://git.add-ideas.de/GovOPlaN/govoplan-core/issues/279):
validated module architecture and provider authority declarations; validated module architecture and provider authority declarations;
- [Core #280](https://git.add-ideas.de/GovOPlaN/govoplan-core/issues/280): - [Core #280](https://git.add-ideas.de/GovOPlaN/govoplan-core/issues/280):
shared institutional-context and governed reference primitives; shared institutional-context and governed reference primitives;
- [GovOPlaN #30](https://git.add-ideas.de/GovOPlaN/govoplan/issues/30): - [GovOPlaN #30](https://git.add-ideas.de/GovOPlaN/govoplan/issues/30) and
Mandates semantics; [govoplan-mandates](https://git.add-ideas.de/GovOPlaN/govoplan-mandates):
- [GovOPlaN #31](https://git.add-ideas.de/GovOPlaN/govoplan/issues/31): Mandates semantics and persistent resolver;
Services semantics; - [GovOPlaN #31](https://git.add-ideas.de/GovOPlaN/govoplan/issues/31) and
- [GovOPlaN #32](https://git.add-ideas.de/GovOPlaN/govoplan/issues/32): [govoplan-services](https://git.add-ideas.de/GovOPlaN/govoplan-services):
Parties and representation semantics; Services semantics, catalogue, and availability;
- [GovOPlaN #33](https://git.add-ideas.de/GovOPlaN/govoplan/issues/33): - [GovOPlaN #32](https://git.add-ideas.de/GovOPlaN/govoplan/issues/32) and
formal Decisions semantics; [govoplan-parties](https://git.add-ideas.de/GovOPlaN/govoplan-parties):
Parties and representation semantics and resolver;
- [GovOPlaN #33](https://git.add-ideas.de/GovOPlaN/govoplan/issues/33) and
[govoplan-decisions](https://git.add-ideas.de/GovOPlaN/govoplan-decisions):
formal Decisions semantics and registry;
- [Datasources #6](https://git.add-ideas.de/GovOPlaN/govoplan-datasources/issues/6): - [Datasources #6](https://git.add-ideas.de/GovOPlaN/govoplan-datasources/issues/6):
governed data/register catalogue; governed data/register catalogue;
- [Risk Compliance #7](https://git.add-ideas.de/GovOPlaN/govoplan-risk-compliance/issues/7): - [Risk Compliance #7](https://git.add-ideas.de/GovOPlaN/govoplan-risk-compliance/issues/7):
@@ -456,23 +477,32 @@ Its new work packages are:
configured architecture, maturity, and source-authority explanations. configured architecture, maturity, and source-authority explanations.
Existing Projects #1, Reporting #4, Portal #1, Cases #1, Datasources #1, Existing Projects #1, Reporting #4, Portal #1, Cases #1, Datasources #1,
Risk Compliance #2, GovOPlaN #14, and GovOPlaN #19 carry reconciliation notes Risk Compliance #2, GovOPlaN #14, and GovOPlaN #19 carry product-depth and
instead of duplicate issues. reference-readiness work instead of duplicating the completed architecture
contract.
## Completion criteria ## Completion evidence
The direction is established when: The architecture direction is established by the following executable and
machine-enforced evidence:
- a user can move from service entry through case, party, work, decision, - the `product.service-to-decision` composition and SQL-backed golden fixture
effect, communication, record, and review without losing institutional retain institutional context from service entry through case, party,
context; authority/work context, decision, observed communication effect, record, and
review references;
- the system can answer who acted, for whom, in which function, under which - the system can answer who acted, for whom, in which function, under which
mandate and jurisdiction, using which rule and evidence versions; mandate and jurisdiction, using which rule and evidence versions;
- every external binding states authority mode, maturity, health, freshness, - every implemented external binding declares authority mode, maturity,
conflict, and recovery behavior; operations, health, freshness, conflict, and recovery behavior, and Registry
rejects a declaration without sanitized runtime state;
- every material report or decision can be reconstructed from governed source - every material report or decision can be reconstructed from governed source
and transformation versions; and transformation versions;
- product and sector packages are portable without cross-module table access or - product/package manifests are portable without cross-module table access or
code forks; and code forks, while future sector packages inherit the same signed-package
constraints; and
- documentation and Ops explain the configured composition and its limits to - documentation and Ops explain the configured composition and its limits to
users, administrators, operators, and auditors. users, administrators, operators, and auditors.
These criteria complete the architecture contract at `vertical_slice` and
`product` maturity. They do not waive the separately enforced evidence needed
for a module or package to claim `reference_ready`, `supported`, or `lts`.