From ddea854779dad6cc61b343df918966770556ed9c Mon Sep 17 00:00:00 2001 From: Specter Intelligence Date: Thu, 16 Apr 2026 10:30:38 +0200 Subject: [PATCH 1/2] feat: Add OpenSpec change p3-governance-bodies from Specter --- .specter-prompt.txt | 12 +- .../p3-governance-bodies/.openspec.yaml | 2 + .../p3-governance-bodies/context-brief.md | 3429 +++++++++++++++++ 3 files changed, 3437 insertions(+), 6 deletions(-) create mode 100644 openspec/changes/p3-governance-bodies/.openspec.yaml create mode 100644 openspec/changes/p3-governance-bodies/context-brief.md diff --git a/.specter-prompt.txt b/.specter-prompt.txt index d9c1ba28..c4bd08c3 100644 --- a/.specter-prompt.txt +++ b/.specter-prompt.txt @@ -4,19 +4,19 @@ You are running HEADLESS. Do NOT use AskUserQuestion, interactive prompts, or sk Write files directly using the Write tool. ## Inputs -- Change: p2-minutes-and-decisions-core-t1 (title: Minutes and Decisions — Core T1) -- Context brief: openspec/changes/p2-minutes-and-decisions-core-t1/context-brief.md +- Change: p3-governance-bodies (title: Governance Bodies) +- Context brief: openspec/changes/p3-governance-bodies/context-brief.md - Data model ADR: openspec/architecture/adr-000-data-model.md ## Step 1: Read context Read these files COMPLETELY before writing anything: -- openspec/changes/p2-minutes-and-decisions-core-t1/context-brief.md (features, stories, stakeholders, journeys) +- openspec/changes/p3-governance-bodies/context-brief.md (features, stories, stakeholders, journeys) - openspec/architecture/adr-000-data-model.md (entity definitions) - All files in openspec/architecture/ (app ADRs) - All files in .claude/openspec/architecture/ (company ADRs, if present) ## Step 2: Get artifact templates -Run: `openspec instructions proposal --change p2-minutes-and-decisions-core-t1 --json` +Run: `openspec instructions proposal --change p3-governance-bodies --json` This returns the template and rules for the proposal artifact. Then do the same for: design, specs, tasks (in that order). @@ -35,8 +35,8 @@ For each artifact (proposal → design → specs → tasks): ## Step 4: Commit After all 4 artifacts are written: ```bash -git add openspec/changes/p2-minutes-and-decisions-core-t1/ -git commit -m 'feat: Add OpenSpec change p2-minutes-and-decisions-core-t1 from Specter' +git add openspec/changes/p3-governance-bodies/ +git commit -m 'feat: Add OpenSpec change p3-governance-bodies from Specter' ``` Do NOT push — the caller handles pushing. Do NOT create branches — stay on the current branch. diff --git a/openspec/changes/p3-governance-bodies/.openspec.yaml b/openspec/changes/p3-governance-bodies/.openspec.yaml new file mode 100644 index 00000000..3a54a172 --- /dev/null +++ b/openspec/changes/p3-governance-bodies/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-04-16 diff --git a/openspec/changes/p3-governance-bodies/context-brief.md b/openspec/changes/p3-governance-bodies/context-brief.md new file mode 100644 index 00000000..015e44a9 --- /dev/null +++ b/openspec/changes/p3-governance-bodies/context-brief.md @@ -0,0 +1,3429 @@ +# Context Brief: Governance Bodies + +**App:** Decidesk — Universal decision-making platform for governance bodies, associations, corporate boards, and operational meetings +**Spec:** p3-governance-bodies +**Platform:** Nextcloud + OpenRegister + +**Depends on:** p2-minutes-and-decisions, p2-motion-and-voting, p2-agenda-management, p2-meeting-management + +## Dependency Specs (content) + +These specs were already decided/implemented. Use them as context. + +### p2-minutes-and-decisions +# Context Brief: Minutes and Decisions + +**App:** Decidesk — Universal decision-making platform for governance bodies, associations, corporate boards, and operational meetings +**Spec:** p2-minutes-and-decisions +**Platform:** Nextcloud + OpenRegister + +**Depends on:** p1-schemas-and-data-model, p1-dashboard-and-navigation, p1-crud-operations + +## Dependency Specs (content) + +These specs were already decided/implemented. Use them as context. + +### p1-schemas-and-data-model +# Context Brief: Schemas and Data Model + +**App:** Decidesk — Universal decision-making platform for governance bodies, associations, corporate boards, and operational meetings +**Spec:** p1-schemas-and-data-model +**Platform:** Nextcloud + OpenRegister + +## Features (6 total, sorted by market demand) + +### Resolution Register +**demand: 206** (66 tender mentions) | Category: core + +### Identity Governance Management +**demand: 91** (27 tender mentions) | Category: governance + +### Register to speak at committee meeting +**demand: 56** (18 tender mentions) | Category: core + +### Voter Register +**demand: 26** (6 tender mentions) | Category: other + +### Attendance Register +**demand: 26** (6 tender mentions) | Category: other + +### Link emails to specific decisions via OpenRegister _mail metadata +**demand: unknown** | Category: other + +## User Stories (6 linked) + +### Story 1: Configure SAML 2.0 identity provider +**Priority:** should +As an IAM administrator, I want to configure a SAML 2.0 identity provider using a metadata XML file, so that I can integrate with government identity federations that do not support OIDC. + +**Acceptance Criteria:** +GIVEN the IdP configuration screen WHEN I upload a SAML metadata XML file THEN the entity ID, SSO URL, and signing certificate are parsed and pre-filled +GIVEN a saved SAML configuration WHEN I download the OpenRegister service provider metadata THEN I receive a valid SAML metadata XML I can import into the identity provider + +### Story 2: View provenance and update metadata for a dataset +**Priority:** should +As a researcher, I want to view the provenance metadata of a register dataset including its source organisation, data steward, creation date, and last update timestamp, so that I can assess whether the dataset is authoritative and current enough for my research. + +**Acceptance Criteria:** +GIVEN a public register WHEN I open the dataset information page THEN I see the responsible organisation (OIN), data steward contact, creation date, last modified timestamp, and the update frequency commitment +GIVEN the dataset page THEN it links to the processing register entry and any applicable open data licence + +### Story 3: Link Nextcloud Mail emails to invoices +**Priority:** must-have +As a Nextcloud user, I want to link emails from Nextcloud Mail to invoice/expense records using OpenRegister _mail metadata, creating a native email-to-invoice connection. + +### Story 4: Link to Nextcloud Contacts +**Priority:** must-have +As a Nextcloud user, I want invoicing contacts to sync with Nextcloud Contacts via OpenRegister _contacts metadata, so I have one unified address book. + +### Story 5: Link emails to specific decisions via OpenRegister _mail metadata +**Priority:** must +As a decision maker, I want emails related to a decision to be automatically linked via the _mail metadata column so that all correspondence is part of the decision dossier and visible in the Mail app sidebar. + +**Acceptance Criteria:** +GIVEN an email mentioning a decision reference number WHEN the email is received THEN it appears linked to the decision object in OpenRegister AND is visible in the Nextcloud Mail sidebar + +### Story 6: Unsubscribe directly from email +**Priority:** must +As a subscriber, I want to unsubscribe from a mailing list by clicking a single link in the email footer, so that I stop receiving unwanted emails immediately. + +**Acceptance Criteria:** +Unsubscribe link visible in email footer; single click completes unsubscribe (no login required); confirmation page shown; no further emails sent from that list + +## Customer Journeys (15 linked) + +### AV & Webcast Infrastructure Management +Managing AV infrastructure in raadzaal and commissiekamers. Discussion systems, PTZ cameras, AV control, webcast/streaming, microphone management. +**Trigger:** Meeting scheduled requiring AV support; system maintenance/upgrade +**Desired outcome:** Reliable AV infrastructure supporting meetings with high-quality recording and streaming +**Current pain:** Complex multi-vendor systems; AV-RIS integration for indexing; maintenance windows; high costs; rapid tech evolution +**Frequency:** Every meeting (setup/support) + periodic maintenance + +### Handle Complex Multi-Domain Citizen Question +A citizen has a question spanning multiple domains (e.g., housing benefit, parking permit, and social assistance). The front desk officer creates linked zaken or a combined intake and routes each to the correct department. +**Trigger:** Citizen presents with multiple interconnected service needs in +... (truncated) + +### p2-motion-and-voting +# Context Brief: Motion and Voting + +**App:** Decidesk — Universal decision-making platform for governance bodies, associations, corporate boards, and operational meetings +**Spec:** p2-motion-and-voting +**Platform:** Nextcloud + OpenRegister + +**Depends on:** p1-schemas-and-data-model, p1-dashboard-and-navigation, p1-crud-operations + +## Dependency Specs (content) + +These specs were already decided/implemented. Use them as context. + +### p1-schemas-and-data-model +# Context Brief: Schemas and Data Model + +**App:** Decidesk — Universal decision-making platform for governance bodies, associations, corporate boards, and operational meetings +**Spec:** p1-schemas-and-data-model +**Platform:** Nextcloud + OpenRegister + +## Features (6 total, sorted by market demand) + +### Resolution Register +**demand: 206** (66 tender mentions) | Category: core + +### Identity Governance Management +**demand: 91** (27 tender mentions) | Category: governance + +### Register to speak at committee meeting +**demand: 56** (18 tender mentions) | Category: core + +### Voter Register +**demand: 26** (6 tender mentions) | Category: other + +### Attendance Register +**demand: 26** (6 tender mentions) | Category: other + +### Link emails to specific decisions via OpenRegister _mail metadata +**demand: unknown** | Category: other + +## User Stories (6 linked) + +### Story 1: Configure SAML 2.0 identity provider +**Priority:** should +As an IAM administrator, I want to configure a SAML 2.0 identity provider using a metadata XML file, so that I can integrate with government identity federations that do not support OIDC. + +**Acceptance Criteria:** +GIVEN the IdP configuration screen WHEN I upload a SAML metadata XML file THEN the entity ID, SSO URL, and signing certificate are parsed and pre-filled +GIVEN a saved SAML configuration WHEN I download the OpenRegister service provider metadata THEN I receive a valid SAML metadata XML I can import into the identity provider + +### Story 2: View provenance and update metadata for a dataset +**Priority:** should +As a researcher, I want to view the provenance metadata of a register dataset including its source organisation, data steward, creation date, and last update timestamp, so that I can assess whether the dataset is authoritative and current enough for my research. + +**Acceptance Criteria:** +GIVEN a public register WHEN I open the dataset information page THEN I see the responsible organisation (OIN), data steward contact, creation date, last modified timestamp, and the update frequency commitment +GIVEN the dataset page THEN it links to the processing register entry and any applicable open data licence + +### Story 3: Link Nextcloud Mail emails to invoices +**Priority:** must-have +As a Nextcloud user, I want to link emails from Nextcloud Mail to invoice/expense records using OpenRegister _mail metadata, creating a native email-to-invoice connection. + +### Story 4: Link to Nextcloud Contacts +**Priority:** must-have +As a Nextcloud user, I want invoicing contacts to sync with Nextcloud Contacts via OpenRegister _contacts metadata, so I have one unified address book. + +### Story 5: Link emails to specific decisions via OpenRegister _mail metadata +**Priority:** must +As a decision maker, I want emails related to a decision to be automatically linked via the _mail metadata column so that all correspondence is part of the decision dossier and visible in the Mail app sidebar. + +**Acceptance Criteria:** +GIVEN an email mentioning a decision reference number WHEN the email is received THEN it appears linked to the decision object in OpenRegister AND is visible in the Nextcloud Mail sidebar + +### Story 6: Unsubscribe directly from email +**Priority:** must +As a subscriber, I want to unsubscribe from a mailing list by clicking a single link in the email footer, so that I stop receiving unwanted emails immediately. + +**Acceptance Criteria:** +Unsubscribe link visible in email footer; single click completes unsubscribe (no login required); confirmation page shown; no further emails sent from that list + +## Customer Journeys (15 linked) + +### AV & Webcast Infrastructure Management +Managing AV infrastructure in raadzaal and commissiekamers. Discussion systems, PTZ cameras, AV control, webcast/streaming, microphone management. +**Trigger:** Meeting scheduled requiring AV support; system maintenance/upgrade +**Desired outcome:** Reliable AV infrastructure supporting meetings with high-quality recording and streaming +**Current pain:** Complex multi-vendor systems; AV-RIS integration for indexing; maintenance windows; high costs; rapid tech evolution +**Frequency:** Every meeting (setup/support) + periodic maintenance + +### Handle Complex Multi-Domain Citizen Question +A citizen has a question spanning multiple domains (e.g., housing benefit, parking permit, and social assistance). The front desk officer creates linked zaken or a combined intake and routes each to the correct department. +**Trigger:** Citizen presents with multiple interconnected service needs in a single +... (truncated) + +### p2-agenda-management +# Context Brief: Agenda Management + +**App:** Decidesk — Universal decision-making platform for governance bodies, associations, corporate boards, and operational meetings +**Spec:** p2-agenda-management +**Platform:** Nextcloud + OpenRegister + +**Depends on:** p1-schemas-and-data-model, p1-dashboard-and-navigation, p1-crud-operations + +## Dependency Specs (content) + +These specs were already decided/implemented. Use them as context. + +### p1-schemas-and-data-model +# Context Brief: Schemas and Data Model + +**App:** Decidesk — Universal decision-making platform for governance bodies, associations, corporate boards, and operational meetings +**Spec:** p1-schemas-and-data-model +**Platform:** Nextcloud + OpenRegister + +## Features (6 total, sorted by market demand) + +### Resolution Register +**demand: 206** (66 tender mentions) | Category: core + +### Identity Governance Management +**demand: 91** (27 tender mentions) | Category: governance + +### Register to speak at committee meeting +**demand: 56** (18 tender mentions) | Category: core + +### Voter Register +**demand: 26** (6 tender mentions) | Category: other + +### Attendance Register +**demand: 26** (6 tender mentions) | Category: other + +### Link emails to specific decisions via OpenRegister _mail metadata +**demand: unknown** | Category: other + +## User Stories (6 linked) + +### Story 1: Configure SAML 2.0 identity provider +**Priority:** should +As an IAM administrator, I want to configure a SAML 2.0 identity provider using a metadata XML file, so that I can integrate with government identity federations that do not support OIDC. + +**Acceptance Criteria:** +GIVEN the IdP configuration screen WHEN I upload a SAML metadata XML file THEN the entity ID, SSO URL, and signing certificate are parsed and pre-filled +GIVEN a saved SAML configuration WHEN I download the OpenRegister service provider metadata THEN I receive a valid SAML metadata XML I can import into the identity provider + +### Story 2: View provenance and update metadata for a dataset +**Priority:** should +As a researcher, I want to view the provenance metadata of a register dataset including its source organisation, data steward, creation date, and last update timestamp, so that I can assess whether the dataset is authoritative and current enough for my research. + +**Acceptance Criteria:** +GIVEN a public register WHEN I open the dataset information page THEN I see the responsible organisation (OIN), data steward contact, creation date, last modified timestamp, and the update frequency commitment +GIVEN the dataset page THEN it links to the processing register entry and any applicable open data licence + +### Story 3: Link Nextcloud Mail emails to invoices +**Priority:** must-have +As a Nextcloud user, I want to link emails from Nextcloud Mail to invoice/expense records using OpenRegister _mail metadata, creating a native email-to-invoice connection. + +### Story 4: Link to Nextcloud Contacts +**Priority:** must-have +As a Nextcloud user, I want invoicing contacts to sync with Nextcloud Contacts via OpenRegister _contacts metadata, so I have one unified address book. + +### Story 5: Link emails to specific decisions via OpenRegister _mail metadata +**Priority:** must +As a decision maker, I want emails related to a decision to be automatically linked via the _mail metadata column so that all correspondence is part of the decision dossier and visible in the Mail app sidebar. + +**Acceptance Criteria:** +GIVEN an email mentioning a decision reference number WHEN the email is received THEN it appears linked to the decision object in OpenRegister AND is visible in the Nextcloud Mail sidebar + +### Story 6: Unsubscribe directly from email +**Priority:** must +As a subscriber, I want to unsubscribe from a mailing list by clicking a single link in the email footer, so that I stop receiving unwanted emails immediately. + +**Acceptance Criteria:** +Unsubscribe link visible in email footer; single click completes unsubscribe (no login required); confirmation page shown; no further emails sent from that list + +## Customer Journeys (15 linked) + +### AV & Webcast Infrastructure Management +Managing AV infrastructure in raadzaal and commissiekamers. Discussion systems, PTZ cameras, AV control, webcast/streaming, microphone management. +**Trigger:** Meeting scheduled requiring AV support; system maintenance/upgrade +**Desired outcome:** Reliable AV infrastructure supporting meetings with high-quality recording and streaming +**Current pain:** Complex multi-vendor systems; AV-RIS integration for indexing; maintenance windows; high costs; rapid tech evolution +**Frequency:** Every meeting (setup/support) + periodic maintenance + +### Handle Complex Multi-Domain Citizen Question +A citizen has a question spanning multiple domains (e.g., housing benefit, parking permit, and social assistance). The front desk officer creates linked zaken or a combined intake and routes each to the correct department. +**Trigger:** Citizen presents with multiple interconnected service needs in a single +... (truncated) + +### p2-meeting-management +# Context Brief: Meeting Management + +**App:** Decidesk — Universal decision-making platform for governance bodies, associations, corporate boards, and operational meetings +**Spec:** p2-meeting-management +**Platform:** Nextcloud + OpenRegister + +**Depends on:** p1-schemas-and-data-model, p1-dashboard-and-navigation, p1-crud-operations + +## Dependency Specs (content) + +These specs were already decided/implemented. Use them as context. + +### p1-schemas-and-data-model +# Context Brief: Schemas and Data Model + +**App:** Decidesk — Universal decision-making platform for governance bodies, associations, corporate boards, and operational meetings +**Spec:** p1-schemas-and-data-model +**Platform:** Nextcloud + OpenRegister + +## Features (6 total, sorted by market demand) + +### Resolution Register +**demand: 206** (66 tender mentions) | Category: core + +### Identity Governance Management +**demand: 91** (27 tender mentions) | Category: governance + +### Register to speak at committee meeting +**demand: 56** (18 tender mentions) | Category: core + +### Voter Register +**demand: 26** (6 tender mentions) | Category: other + +### Attendance Register +**demand: 26** (6 tender mentions) | Category: other + +### Link emails to specific decisions via OpenRegister _mail metadata +**demand: unknown** | Category: other + +## User Stories (6 linked) + +### Story 1: Configure SAML 2.0 identity provider +**Priority:** should +As an IAM administrator, I want to configure a SAML 2.0 identity provider using a metadata XML file, so that I can integrate with government identity federations that do not support OIDC. + +**Acceptance Criteria:** +GIVEN the IdP configuration screen WHEN I upload a SAML metadata XML file THEN the entity ID, SSO URL, and signing certificate are parsed and pre-filled +GIVEN a saved SAML configuration WHEN I download the OpenRegister service provider metadata THEN I receive a valid SAML metadata XML I can import into the identity provider + +### Story 2: View provenance and update metadata for a dataset +**Priority:** should +As a researcher, I want to view the provenance metadata of a register dataset including its source organisation, data steward, creation date, and last update timestamp, so that I can assess whether the dataset is authoritative and current enough for my research. + +**Acceptance Criteria:** +GIVEN a public register WHEN I open the dataset information page THEN I see the responsible organisation (OIN), data steward contact, creation date, last modified timestamp, and the update frequency commitment +GIVEN the dataset page THEN it links to the processing register entry and any applicable open data licence + +### Story 3: Link Nextcloud Mail emails to invoices +**Priority:** must-have +As a Nextcloud user, I want to link emails from Nextcloud Mail to invoice/expense records using OpenRegister _mail metadata, creating a native email-to-invoice connection. + +### Story 4: Link to Nextcloud Contacts +**Priority:** must-have +As a Nextcloud user, I want invoicing contacts to sync with Nextcloud Contacts via OpenRegister _contacts metadata, so I have one unified address book. + +### Story 5: Link emails to specific decisions via OpenRegister _mail metadata +**Priority:** must +As a decision maker, I want emails related to a decision to be automatically linked via the _mail metadata column so that all correspondence is part of the decision dossier and visible in the Mail app sidebar. + +**Acceptance Criteria:** +GIVEN an email mentioning a decision reference number WHEN the email is received THEN it appears linked to the decision object in OpenRegister AND is visible in the Nextcloud Mail sidebar + +### Story 6: Unsubscribe directly from email +**Priority:** must +As a subscriber, I want to unsubscribe from a mailing list by clicking a single link in the email footer, so that I stop receiving unwanted emails immediately. + +**Acceptance Criteria:** +Unsubscribe link visible in email footer; single click completes unsubscribe (no login required); confirmation page shown; no further emails sent from that list + +## Customer Journeys (15 linked) + +### AV & Webcast Infrastructure Management +Managing AV infrastructure in raadzaal and commissiekamers. Discussion systems, PTZ cameras, AV control, webcast/streaming, microphone management. +**Trigger:** Meeting scheduled requiring AV support; system maintenance/upgrade +**Desired outcome:** Reliable AV infrastructure supporting meetings with high-quality recording and streaming +**Current pain:** Complex multi-vendor systems; AV-RIS integration for indexing; maintenance windows; high costs; rapid tech evolution +**Frequency:** Every meeting (setup/support) + periodic maintenance + +### Handle Complex Multi-Domain Citizen Question +A citizen has a question spanning multiple domains (e.g., housing benefit, parking permit, and social assistance). The front desk officer creates linked zaken or a combined intake and routes each to the correct department. +**Trigger:** Citizen presents with multiple interconnected service needs in a sing +... (truncated) + +## Features (75 total, sorted by market demand) + +### Track BOB model phases for council decision-making +**demand: 1100** (365 tender mentions) | Category: core + +### BOB model tracking +**demand: 1049** | Category: governance bodies +Full BOB workflow (Beeldvorming-Oordeelsvorming-Besluitvorming) for Dutch municipalities + +### Publish council data via ORI API +**demand: 789** (263 tender mentions) | Category: integration + +### [competitor] new council member digitally +**demand: 754** (251 tender mentions) | Category: other + +### Migrate historical council data +**demand: 743** (244 tender mentions) | Category: other + +### Initiate works council consultation +**demand: 741** (246 tender mentions) | Category: other + +### Present recommendations to council +**demand: 740** (242 tender mentions) | Category: other + +### Approve proposal for council submission +**demand: 734** (241 tender mentions) | Category: other + +### Answer written council question +**demand: 734** (241 tender mentions) | Category: other + +### Submit youth council advice +**demand: 729** (243 tender mentions) | Category: other + +### Council Member Collaboration +**demand: 724** (241 tender mentions) | Category: collaboration + +### ORI API publishing +**demand: 720** | Category: governance bodies +Publish meetings, agendas, motions, votes, and decisions via ORI API + +### Delegate a task to a specialist role group +**demand: 609** (203 tender mentions) | Category: security + +### Digital Governance +**demand: 484** (159 tender mentions) | Category: governance + +### Cooperative Governance +**demand: 369** (123 tender mentions) | Category: governance + +### Hybrid Governance +**demand: 359** (101 tender mentions) | Category: governance + +### AI-Driven Board Reports and Governance Insights +**demand: 353** (115 tender mentions) | Category: governance + +### Committee Workspaces +**demand: 339** (113 tender mentions) | Category: other + +### IT governance scoping review +**demand: 337** (108 tender mentions) | Category: governance + +### Governance First Design +**demand: 321** (93 tender mentions) | Category: governance + +### IT governance frameworks comparison +**demand: 321** (93 tender mentions) | Category: governance + +### Governance Ready Output +**demand: 320** (93 tender mentions) | Category: governance + +### Multi Jurisdiction Governance +**demand: 320** (93 tender mentions) | Category: governance + +### Governance Gap Analysis +**demand: 320** (93 tender mentions) | Category: governance + +### Governance and Project Monitoring +**demand: 320** (93 tender mentions) | Category: governance + +### that match governance mandates +**demand: 320** (93 tender mentions) | Category: governance + +### nasdaq’s governance suite +**demand: 319** (93 tender mentions) | Category: governance + +### Governance Audit Trail +**demand: 307** (102 tender mentions) | Category: governance + +### Open Source Governance +**demand: 294** (96 tender mentions) | Category: governance + +### Structured Governance and Committee Workflows +**demand: 291** (95 tender mentions) | Category: governance + +### COVID-19 governance digitalization +**demand: 287** (94 tender mentions) | Category: governance + +### AI-enhanced governance +**demand: 286** (94 tender mentions) | Category: governance + +### Complete Governance Lifecycle for Annual General Meetings +**demand: 284** (93 tender mentions) | Category: governance + +### Pro-Forma Text Templates for Governance Teams +**demand: 280** (93 tender mentions) | Category: governance + +### board directors to annotate materials +**demand: 223** (49 tender mentions) | Category: other + +### directors confidential access to board materials +**demand: 199** (63 tender mentions) | Category: security + +### Prepare supervisory board approval request +**demand: 187** (62 tender mentions) | Category: other + +### Open source governance +**demand: 174** (45 tender mentions) | Category: governance + +### Community Governance +**demand: 152** (50 tender mentions) | Category: Governance +Multi-organization governance model for standards + +### Domain presets +**demand: 148** | Category: governance bodies +One-click setup for each of the 5 governance domains + +### Workflow template configuration +**demand: 148** | Category: governance bodies +Configure state machine workflows per governance body + +### Role and permission management +**demand: 148** | Category: governance bodies +Define custom roles and permissions per governance body + +### Committee management +**demand: 148** | Category: governance bodies +Manage sub-committees with their own meeting cycles + +### Term/period management +**demand: 148** | Category: governance bodies +Track governance periods (council terms, board terms) + +### Membership history +**demand: 148** | Category: governance bodies +Record when participants join/leave with role changes + +### Enhanced Security and Governance Controls +**demand: 142** (45 tender mentions) | Category: governance + +### Access Discount Governance on Mobile +**demand: 128** (32 tender mentions) | Category: governance + +### the foundation for ai-enhanced board operations +**demand: 122** (38 tender mentions) | Category: ai + +### Committee Tracking +**demand: 121** (14 tender mentions) | Category: analytics + +### Information governance OpenText +**demand: 103** (31 tender mentions) | Category: governance + +### Export change report for external audit committee +**demand: 96** (32 tender mentions) | Category: governance + +### Governance Services +**demand: 95** (29 tender mentions) | Category: governance + +### Track policy proposals across democratic bodies +**demand: 93** (31 tender mentions) | Category: governance + +### Receive notifications for Council Question Response +**demand: 84** (28 tender mentions) | Category: other + +### Export Council Question Response data +**demand: 84** (28 tender mentions) | Category: document-management + +### Submit committee report with recommendations +**demand: 75** (25 tender mentions) | Category: analytics + +### Account Password Management for Committee Administrators +**demand: 53** (17 tender mentions) | Category: security + +### Enterprise Security and Governance Features +**demand: 51** (16 tender mentions) | Category: governance + +### Data Governance +**demand: 49** (13 tender mentions) | Category: governance + +### Data Governance Policy Definition and Enforcement +**demand: 48** (13 tender mentions) | Category: governance + +### Submit written input to committee +**demand: 45** (15 tender mentions) | Category: other + +### Present audit results to committee +**demand: 43** (13 tender mentions) | Category: governance + +### Establish committee with formal mandate +**demand: 29** (3 tender mentions) | Category: other + +### Transparent Proposal and Activity Tracking with Accountability +**demand: 16** (5 tender mentions) | Category: governance + +### governance +**demand: 10** (3 tender mentions) | Category: governance + +### Governance +**demand: 8** (2 tender mentions) | Category: governance + +### Map buying committee +**demand: 6** (2 tender mentions) | Category: other + +### Monitor topics across multiple councils +**demand: 6** (2 tender mentions) | Category: other + +### Governance and certification +**demand: 2** | Category: Administration +Data governance with certification, PDP (Personalized Data Permissions), and lineage + +### Governance and lineage +**demand: 2** | Category: Administration +Data lineage tracking, impact analysis, endorsement, and usage metrics + +### Data governance +**demand: 2** | Category: Administration +Content certification, access audit logs, and data source governance controls + +### steering committees +**demand: 1** | Category: other + +### your chairperson +**demand: 1** | Category: other + +### the co-operative ( coöperatie ) +**demand: 1** | Category: other + +### huly-secretary-social-id +**demand: 1** | Category: general +Discovered from GitHub issue in hcengineering/platform + +## User Stories (153 linked) + +### Story 1: Proposal Submission +**Priority:** wont +As a council clerk, I want to have proposal submission capabilities, so that the platform meets diverse organizational needs. + +### Story 2: Process Modeling +**Priority:** wont +As a council clerk, I want to have process modeling capabilities, so that the platform meets diverse organizational needs. + +### Story 3: Regulatory Frameworks +**Priority:** wont +As a council clerk, I want to have regulatory frameworks capabilities, so that the platform meets diverse organizational needs. + +### Story 4: Budget Analysis +**Priority:** wont +As a council clerk, I want to budget analysis, so that the platform meets diverse organizational needs. + +### Story 5: Digital Submissions +**Priority:** wont +As a council clerk, I want to have digital submissions capabilities, so that the platform meets diverse organizational needs. + +### Story 6: Shared Information Model +**Priority:** wont +As a council clerk, I want to have shared information model capabilities, so that the platform meets diverse organizational needs. + +### Story 7: Functionality Categories +**Priority:** wont +As a council clerk, I want to have functionality categories capabilities, so that the platform meets diverse organizational needs. + +### Story 8: Stateninformatie +**Priority:** wont +As a council clerk, I want to have stateninformatie capabilities, so that the platform meets diverse organizational needs. + +### Story 9: Bestuursinformatie +**Priority:** wont +As a council clerk, I want to have bestuursinformatie capabilities, so that the platform meets diverse organizational needs. + +### Story 10: Public Records +**Priority:** wont +As a council clerk, I want to have public records capabilities, so that the platform meets diverse organizational needs. + +### Story 11: Actor Model +**Priority:** wont +As a council clerk, I want to have actor model capabilities, so that the platform meets diverse organizational needs. + +### Story 12: Categorization +**Priority:** wont +As a council clerk, I want to have categorization capabilities, so that the platform meets diverse organizational needs. + +### Story 13: Committee Workspaces +**Priority:** wont +As a meeting organizer, I want to have committee workspaces capabilities, so that the platform meets diverse organizational needs. + +### Story 14: Participation Frameworks +**Priority:** wont +As a council clerk, I want to have participation frameworks capabilities, so that the platform meets diverse organizational needs. + +### Story 15: Ethical Frameworks +**Priority:** wont +As a council clerk, I want to have ethical frameworks capabilities, so that the platform meets diverse organizational needs. + +### Story 16: 17 Information Categories +**Priority:** wont +As a council clerk, I want to have 17 information categories capabilities, so that the platform meets diverse organizational needs. + +### Story 17: Web Modeler +**Priority:** wont +As a council clerk, I want to have web modeler capabilities, so that the platform meets diverse organizational needs. + +### Story 18: Process Monitoring +**Priority:** wont +As a council clerk, I want to have process monitoring capabilities, so that the platform meets diverse organizational needs. + +### Story 19: Automatic Adoption +**Priority:** wont +As a council clerk, I want to have automatic adoption capabilities, so that the platform meets diverse organizational needs. + +### Story 20: Recorded as Cast +**Priority:** wont +As a council clerk, I want to have recorded-as-cast capabilities, so that the platform meets diverse organizational needs. + +## Customer Journeys (15 linked) + +### Contract Lifecycle +Create, negotiate, sign, monitor, and renew business contracts +**Trigger:** New business relationship or service need +**Desired outcome:** Active, compliant contract with tracked obligations +**Frequency:** monthly + +### Iv3 Reporting +Report financial data to CBS per Information for Third Parties standard +**Trigger:** Quarter-end; year-end +**Desired outcome:** Iv3-compliant data submitted to CBS on time +**Frequency:** quarterly + +### Government Expense Claims +Process expense claims from officials and employees +**Trigger:** Official incurs business expense +**Desired outcome:** Expense reimbursed per policy; recorded compliantly +**Frequency:** weekly + +### Supplier Management +[competitor], evaluate, and manage supplier relationships +**Trigger:** New supplier needed or periodic review +**Desired outcome:** Qualified suppliers with favorable terms under contract +**Frequency:** monthly + +### Budget Planning +Create annual budget and track actual vs planned spending +**Trigger:** Annual planning cycle +**Desired outcome:** Approved budget with regular variance monitoring +**Frequency:** yearly + +### Financial Transparency (Woo) +Proactively publish financial information per Wet open overheid +**Trigger:** Financial decision made; document created +**Desired outcome:** Financial data published openly; Woo-compliant +**Frequency:** continuous + +### Expense Reimbursement +Employee submits expense, gets approval, receives reimbursement +**Trigger:** Employee incurs business expense +**Desired outcome:** Employee reimbursed; expense recorded in correct category +**Frequency:** weekly + +### Test BPMN Process in Staging Environment +Before publishing, the process designer runs the BPMN model with test cases to verify gateway conditions, timer behaviour, and task routing behave as intended. +**Trigger:** Process model is completed and ready for validation before go-live +**Desired outcome:** All process paths are verified correct; edge cases and error paths are handled without unexpected process suspension +**Current pain:** No integrated test runner; testing requires manual zaak creation and step-by-step verification which is slow and incomplete +**Frequency:** monthly + +### Water Board General Assembly Meeting +Water board general assembly meets at least 6x/year. Sets policy, approves budgets, oversees executive board. Chaired by dijkgraaf. Secretary-director maintains minutes. +**Trigger:** Scheduled general assembly meeting (minimum 6x/year) +**Desired outcome:** Policy decisions made, budgets approved, oversight exercised, complete minutes maintained +**Current pain:** Similar needs as municipalities but different governance; fewer commercial RIS options; unique stakeholder categories +**Frequency:** Minimum 6 times per year (general assembly); bi-weekly (executive board) + +### Manage and Roll Back Process Versions +The functional administrator reviews deployed process versions, compares differences between versions, and rolls back to a previous version when a newly deployed model causes issues in production. +**Trigger:** Production incident caused by a faulty process deployment or stakeholder request to revert a change +**Desired outcome:** Previous stable version is active within minutes; in-flight cases are migrated or paused without data loss +**Current pain:** Version history is opaque; rolling back requires database intervention by IT; in-flight cases are left in an inconsistent state +**Frequency:** ad-hoc + +### Decision Execution & Follow-up +After council makes a decision, the executive is responsible for executing it. Includes implementing policy changes, allocating budgets, and reporting back to council. +**Trigger:** Council adopts a proposal, motion, or amendment requiring executive action +**Desired outcome:** Decision is fully implemented and the council is informed of completion +**Current pain:** Difficulty linking decisions to implementation; no automated tracking; reporting often delayed; unclear accountability +**Frequency:** Continuous (each adopted decision requires follow-up) + +### Live Meeting Following & Webcasting +Citizens and journalists follow meetings in real-time, physically or via live webcast/stream. Includes viewing agenda in real-time and tracking which item is being discussed. +**Trigger:** Council or committee meeting is in session +**Desired outcome:** Interested parties can follow the meeting in real-time with access to relevant documents +**Current pain:** Webcast quality varies; no real-time agenda tracking; difficult to find relevant document during live viewing; no live captions +**Frequency:** Every public meeting (3-6 per month) + +### RIS Platform Migration & Transition +Migrating from one RIS to another including data migration of historical records, user transition, integration reconfiguration, and training. +**Trigger:** Contract expiration, dissatisfaction with current RIS, or need for new features +**Desired outcome:** Successful migration with complete data transfer, minimal disruption, and satisfied users +**Current pain:** Complex data migration from proprietary formats; risk of data loss; user resistance; training needs; vendor lock-in +**Frequency:** Every 4-8 years (contract cycles) + +### Provincial States Meeting Cycle +Provincial States follow similar BOB model but larger scale. CdK chairs, griffier supports, factions coordinate through presidium. State proposals through statencommissies before statendag. +**Trigger:** Monthly meeting cycle of provincial states +**Desired outcome:** Provincial policy decisions made through structured committee and plenary process +**Current pain:** Similar to municipal pain points but larger scale; more formal procedures +**Frequency:** Monthly (statendag) plus committee meetings + +### Press Coverage & Media Access +Journalists access council meetings, documents, and officials for reporting. Includes press pass registration, gallery access, post-meeting briefings, and RIS research. +**Trigger:** Newsworthy item on council agenda or need for background research +**Desired outcome:** Journalist can efficiently access all public council information, attend meetings, contact officials +**Current pain:** Complex registration; limited press facilities; restrictions on filming/quoting; delayed recordings; declining journalism resources +**Frequency:** Continuous (more intense around plenary meetings) + +## Stakeholders (513 linked) + +### CEO / Managing Director +Chief Executive Officer or managing director responsible for day-to-day management of the company. In Dutch two-tier model, member of the Raad van Bestuur (management board). +**Responsibilities:** Setting corporate strategy, executing board decisions, representing the company externally, reporting to supervisory board, preparing annual accounts, convening shareholder meetings +**Pain points:** Complex approval chains for strategic decisions, balancing stakeholder interests, ensuring compliance with Dutch Corporate Governance Code, managing conflict of interest declarations, coordinating between management board and supervisory board +**Goals:** Efficient decision-making processes, clear audit trails for all governance decisions, streamlined communication with supervisory board and shareholders, digital-first governance workflows + +### CFO / Financial Director +Chief Financial Officer responsible for financial reporting, internal controls, SOX compliance (if applicable), and financial governance. Interfaces with audit committee and external auditors. +**Responsibilities:** Financial reporting and annual accounts, internal controls (SOX Section 302/404 certification), risk management, treasury, tax compliance, audit coordination, dividend proposals +**Pain points:** SOX compliance documentation burden, coordinating with external auditors, ensuring internal control effectiveness, managing financial reporting deadlines, audit committee preparation workload +**Goals:** Automated internal control documentation, streamlined audit processes, real-time financial governance dashboards, efficient committee reporting + +### Board Secretary / Company Secretary +Corporate governance professional who manages all governance processes, board meetings, minutes, compliance, and stakeholder communication. Guardian of governance procedures and compliance. +**Responsibilities:** Preparing board packs and agendas, taking and distributing minutes, managing governance calendar, ensuring quorum, advising on governance procedures, maintaining corporate registers, coordinating AGM logistics, filing with KVK/AFM +**Pain points:** Manual board pack assembly, version control of sensitive documents, tracking action items across multiple boards and committees, ensuring timely distribution, managing multiple meeting calendars, paper-based minute signing processes +**Goals:** Digital board portal with secure document distribution, automated meeting scheduling and reminders, electronic minute approval workflows, integrated governance calendar, real-time action item tracking + +### Supervisory Board Chair +Chair of the supervisory board (Raad van Commissarissen) in Dutch two-tier governance model. Leads supervisory oversight, sets RvC agenda, and maintains relationship with management board. +**Responsibilities:** Chairing supervisory board meetings, setting RvC agenda, appointing committee chairs, leading board evaluations, maintaining dialogue with CEO and shareholders, ensuring proper governance, managing conflicts of interest within RvC +**Pain points:** Limited visibility into management decisions between meetings, difficulty coordinating dispersed supervisory board members, managing information asymmetry with management board, ensuring all members are adequately informed +**Goals:** Secure digital workspace for supervisory board, real-time access to management information, efficient virtual meeting capabilities, structured oversight and approval workflows + +### Supervisory Board Member +Individual member of the supervisory board. Provides oversight, advice, and approval on management decisions. May serve on audit, remuneration, or nomination committees. +**Responsibilities:** Attending supervisory board and committee meetings, reviewing management decisions, approving major transactions and appointments, monitoring risk management, evaluating management board performance +**Pain points:** Information overload from board packs, limited time for preparation, difficulty accessing documents on mobile devices, lack of annotation and collaboration tools, managing multiple board memberships +**Goals:** Mobile-friendly board portal with offline access, smart document summaries, annotation and note-taking tools, secure communication with fellow board members, clear voting and resolution tracking + +### Shareholder +Owner of shares in a BV or NV. Has voting rights at the Algemene Vergadering van Aandeelhouders (AVA/AGM). Dutch law provides specific rights for minority shareholders. +**Responsibilities:** Attending and voting at AVA/AGM, approving annual accounts, appointing/dismissing directors, approving statute amendments, exercising inquiry rights (enquêterecht) +**Pain points:** Complex proxy voting processes, lack of transparency in pre-meeting information, difficulty participating in hybrid/digital meetings, limited engagement between AGMs, unclear resolution outcomes +**Goals:** Easy digital proxy voting, transparent access to meeting agendas and documents, real-time participation in hybrid AGMs, clear dividend and resolution information, accessible corporate governance information + +### Institutional Investor +Large-scale investor (pension fund, asset manager, insurance company) with significant shareholdings. Subject to Shareholder Rights Directive II (SRD II) stewardship obligations. +**Responsibilities:** Stewardship and engagement with portfolio companies, proxy voting across hundreds of AGMs, ESG assessment, compliance with SRD II disclosure requirements, filing substantial holdings notifications +**Pain points:** Managing proxy voting at scale across many companies, reliance on proxy advisors (ISS/Glass Lewis), cross-border voting complexity, meeting SRD II engagement and disclosure requirements, lack of standardized governance data +**Goals:** Automated proxy voting workflows, integrated ESG governance scoring, efficient engagement tracking, SRD II compliance automation, standardized corporate governance data feeds + +### Proxy Advisor +Firm that provides voting recommendations to institutional investors (ISS, Glass Lewis). Analyzes governance proposals and issues benchmark voting policies. Controls 90%+ of proxy advisory market. +**Responsibilities:** Analyzing AGM agenda items and resolutions, issuing voting recommendations, maintaining benchmark voting policies, researching corporate governance practices, reporting on voting outcomes +**Pain points:** Accessing timely and accurate meeting information across jurisdictions, analyzing large volumes of AGM proposals, maintaining consistent governance standards globally, adapting to regulatory changes +**Goals:** Standardized digital access to AGM agendas and resolutions, automated governance data collection, efficient cross-border meeting analysis, real-time resolution tracking + +### Province IT Security Officer +Provincial security officer assessing sovereignty risks across regional government services +**Responsibilities:** Regional cloud policy enforcement; vendor assessment; data classification +**Pain points:** Diverse IT landscapes across municipalities; no standardized sovereignty assessment +**Goals:** Unified sovereignty dashboard for the region; standardized assessment methodology + +### External Auditor +Independent auditor who audits annual accounts and reports to shareholders. In Dutch governance, appointed by AGM and reports to audit committee. Subject to auditor rotation requirements. +**Responsibilities:** Auditing annual financial statements, reporting to audit committee, attending AGM for shareholder questions, assessing internal controls (SOX 404 if applicable), issuing management letter, evaluating going concern +**Pain points:** Limited digital access to governance documentation, manual evidence collection for audit procedures, difficulty tracking management representations, coordinating with internal audit and audit committee +**Goals:** Digital audit evidence repository, secure access to board minutes and resolutions, automated management representation tracking, integrated communication with audit committee + +## Entities for This Spec (7) + +Full data model: see `openspec/architecture/adr-000-data-model.md`. +This spec uses: + +- **Area**: A geographic or jurisdictional area. Popolo: Area. Links a governance body to its jurisdiction (municipality, province, waterboard district). → GovernanceBody +- **ContactDetail**: A means of contacting a person or organization. Popolo: ContactDetail. Replaces the single email field on Participant with typed, multi-value contacts. → Person, GovernanceBody +- **GovernanceBody**: A governance body (council, board, committee, assembly) +- **Membership**: Relationship between a person and an organization, including role and time bounds. Popolo: Membership. Replaces the role field on Participant — a person can have multiple memberships in different governance bodies. → Person, GovernanceBody, Post +- **Participant**: A member or attendee of a governance body +- **Person**: An individual person who participates in governance. Popolo: Person. Replaces Participant — person data separated from membership/role data. → Membership, ContactDetail, Speech, Vote +- **Post**: A formal position within a governance body that can be filled by a person via Membership. Popolo: Post. Examples: Chair, Secretary, Treasurer. → GovernanceBody + +## Other App Entities (do NOT redefine) + +ActionItem, AgendaItem, Amendment, Decision, DigitalDocument, Meeting, Minutes, MonetaryAmount, Motion, Offer, Order, Product, Report, Speech, Vote, VotingRound + +## Company-Wide Architecture Rules (17 ADRs) + +These rules are MANDATORY for all Conduction apps. + +### ADR-001-data-layer +- ALL domain data → OpenRegister objects. NO custom Entity/Mapper for domain data. +- App config → `IAppConfig`. NOT OpenRegister. +- Cross-entity references: OpenRegister relations (register+schema+objectId). NO foreign keys. + MUST NOT store foreign keys or embed full objects. + +### Schema standards + +- Schemas: PascalCase, schema.org vocabulary, explicit types + required flags + description field. +- MUST NOT invent custom property names when a schema.org equivalent exists. +- Contact schemas MUST align with vCard properties (fn, email, tel, adr). +- Dutch government fields SHOULD use a mapping layer translating between international standards + and Dutch specs — do not hardcode Dutch field names as primary. +- Schema changes that remove or rename properties are BREAKING. Adding optional properties is non-breaking. + +### Register templates + +- Location: `lib/Settings/{app}_register.json` (OpenAPI 3.0 + `x-openregister` extensions). +- Three template categories: + - **App configuration** — define data models (schemas/registers/views/mappings). + Mark with `x-openregister.type: "application"`. + - **Mock data** — fictional but realistic seed data for dev/test. + Mark with `x-openregister.type: "mock"`. + - **Government standards** — aligned to Dutch API specs (BAG, BRP, KVK, DSO). +- Import mechanism: `ConfigurationService::importFromApp(appId, data, version, force)` → + `ImportHandler::importFromApp()`. Called from repair step or `SettingsLoadService`. +- Idempotency: re-importing with `force: false` MUST NOT create duplicates. Match by slug + using `ObjectService::searchObjects` with `_rbac: false` and `_multitenancy: false`. + Use `version_compare` for skip logic. + +### Seed data + +Apps that store data in OpenRegister are empty on first install. An empty app cannot be +meaningfully tested — there are no objects to view, search, filter, or interact with. +This blocks both automated browser testing and manual QA. The Loadable Register Template +pattern (see Register templates above) already supports seed data via `components.objects[]` +with the `@self` envelope. + +**Requirements:** + +- Every app using OpenRegister MUST include 3-5 realistic objects per schema in + `lib/Settings/{app}_register.json`. +- Use `@self` envelope: `{ "@self": { "register": ..., "schema": ..., "slug": ... }, ...properties }`. + Register/schema MUST match keys; slug is unique human-readable identifier for matching. +- Use general organisation data (municipality, consultancy, travel agency, non-profit) — + NOT context-specific. Varied, realistic field values. +- Mock data quality: real Dutch street names, valid postcodes (`[1-9][0-9]{3}[A-Z]{2}`), + correct municipality/KVK codes, BSNs that pass 11-proef. Fictional but distinguishable from real. +- Cross-register consistency: BRP→BAG, KVK→BAG, DSO→BAG references must be valid. +- Loaded on install alongside schemas via same `importFromApp()` pipeline. +- MUST be idempotent — re-importing skips existing objects matched by slug. + +**In OpenSpec artifacts:** + +- **In design.md**: MUST include a Seed Data section when change introduces/modifies schemas — + define seed objects per schema with concrete field values and related items (files, notes, tasks, contacts). +- **In tasks.md**: MUST include a seed data generation task when change introduces/modifies schemas. + +**Exceptions** (no seed data required): + +- **nldesign** — has no OpenRegister schemas. +- **ExApp sidecar wrappers** (openklant, opentalk, openzaak, valtimo, n8n-nextcloud) — proxy + external services and do not use OpenRegister. +- **nextcloud-vue** — shared library, no seed data applicable. +- Changes that only modify frontend components or non-schema backend logic (e.g., settings, + permissions) do not require seed data. + +**Limitations:** OpenRegister's `ImportHandler` currently supports only flat seed objects. +Related items (files, notes, tasks, contacts) linked through the relation system are tracked +on the product roadmap. Until then, seed data is limited to object properties defined in schemas. + +### Deduplication check + +- Before proposing new capability: search `openspec/specs/` and `openregister/lib/Service/` for overlap + with ObjectService, RegisterService, SchemaService, ConfigurationService, and shared Vue components. +- If similar capability exists: MUST reference it and explain why new code is needed rather than extending. +- Proposals duplicating existing functionality without justification MUST be rejected. +- **In design.md**: MUST include a "Reuse Analysis" section listing existing OpenRegister services leveraged. +- **In tasks.md**: MUST include a "Deduplication Check" task verifying no overlap — document findings + even if "no overlap found". + +### Schema migrations + +- Breaking schema changes → new migration in repair step. NEVER modify existing migrations. + +### OpenRegister + @conduction/nextcloud-vue — DO NOT REBUILD + +The platform provides 258+ backend methods and 69+ frontend components. Apps ONLY build +custom logic for domain-specific business rules. Everything below is provided for FREE. + +**CRUD & Data Management** (use ObjectService + CnIndexPage + CnDetailPage): +- Single & bulk create, read, update, delete — `ObjectService.saveObject()`, `deleteObject()` +- List with pagination, sorting, filtering — `ObjectService.findAll()` + `CnDataTable` +- Schema-driven forms — `CnFormDialog` (auto-generates from schema) or `CnAdvancedFormDialog` +- Detail views — `CnDetailPage` with `CnDetailGrid`, `CnDetailCard` sections +- Record merging/deduplication — `ObjectService.mergeObjects()` +- Object locking — `ObjectService.lockObject()` / `unlockObject()` + +**Import & Export** (use ImportService/ExportService + CnMassImportDialog/CnMassExportDialog): +- CSV, Excel, JSON import with intelligent field mapping — `ImportService` +- CSV, Excel, JSON export with column selection — `ExportService` +- Bulk import with validation and progress — `CnMassImportDialog` +- Filtered export with format picker — `CnMassExportDialog` +- NO custom import dialogs, parsers, upload handlers, or export controllers + +**Search & Discovery** (use IndexService + CnFilterBar + CnFacetSidebar): +- Full-text search with field weighting — `IndexService` +- Faceted navigation with counts — `FacetBuilder` + `CnFacetSidebar` +- Semantic search with embeddings — `VectorizationService` +- Hybrid search (keyword + semantic) — automatic +- Search analytics — `SearchTrailService` (popular terms, activity) +- NO custom search endpoints, query builders, or search pages + +**File Management** (use FileService + CnObjectSidebar): +- Upload (single/multipart), download, share links — `FileService` +- File tagging, public/private toggle — `FileService` +- Bulk download as ZIP — `createObjectFilesZip()` +- Text extraction from PDFs/Office docs — `TextExtractionService` +- File tab in object sidebar — `CnObjectSidebar` → `CnFilesTab` +- NO custom file upload components, file controllers, or download handlers + +**Audit & Compliance** (use AuditTrailService + CnObjectSidebar): +- Full change tracking with before/after snapshots — automatic +- Audit trail tab — `CnObjectSidebar` → `CnAuditTrailTab` +- GDPR data subject access requests — `inzageverzoek()`, `verwerkingsregister()` +- Audit export and analytics — `AuditTrailController` +- NO custom audit logging, change tracking, or compliance controllers + +**Dashboard & Analytics** (use CnDashboardPage + CnChartWidget + CnStatsBlock): +- Drag-drop widget dashboard — `CnDashboardPage` with GridStack +- KPI cards — `CnKpiGrid`, `CnStatsBlock`, `CnStatsPanel` +- Charts (line/bar/pie/donut) — `CnChartWidget` (ApexCharts) +- Data tables as widgets — `CnTableWidget` +- Editable data grids — `CnObjectDataWidget` +- NO custom dashboard layouts, chart components, or KPI cards + +**Forms & Dialogs** (use CnFormDialog + schema-driven generation): +- Auto-generated create/edit forms — `CnFormDialog` reads schema → generates fields +- JSON/metadata editing — `CnAdvancedFormDialog` with Properties/Data/Metadata tabs +- Schema editor — `CnSchemaFormDialog` +- Delete/Copy/Mass operations — `CnDeleteDialog`, `CnCopyDialog`, `CnMassDeleteDialog` +- NO custom form components, validation logic, or dialog wrappers + +**Navigation & Pagination** (use CnPagination + CnActionsBar + useListView): +- Pagination control with size selector — `CnPagination` +- Action bar (add, search, toggle views) — `CnActionsBar` +- List state management — `useListView` composable (handles search, filter, sort, page) +- Detail state management — `useDetailView` composable +- NO custom pagination logic, debounced search, or list state management + +**Authorization & RBAC** (use AuthorizationService + PropertyRbacHandler): +- Role-based access control — `AuthorizationService` +- Field-level permissions — `PropertyRbacHandler` +- Object-level restrictions — `PermissionHandler` +- Authorization audit — `AuthorizationAuditService` +- NO custom permission checks, role systems, or access control middleware + +**Webhooks & Events** (use WebhookService): +- Create, test, retry webhooks — `WebhookService` +- CloudEvents format — automatic +- Event subscriptions — selective per schema/action +- NO custom webhook controllers or event dispatchers + +**Notifications & Activity** (use NotificationService + ActivityService): +- Nextcloud notifications — `NotificationService` +- Activity feed — `ActivityService` +- Calendar events — `CalendarEventService` +- Deck/Kanban cards — `DeckCardService` + +**Store & State** (use createObjectStore + plugins): +- Object stores — `createObjectStore(name)` generates Pinia CRUD store +- Store plugins: `auditTrails`, `files`, `lifecycle`, `relations`, `search`, `selection` +- Column/field/filter generation from schema — `columnsFromSchema()`, `fieldsFromSchema()` +- NO custom Pinia stores for CRUD, Vuex, or manual API call management + +**Chat & AI** (use ChatService): +- Multi-turn conversation — `ChatService` +- RAG-based knowledge retrieval — `ContextRetrievalHandler` +- LLM response generation — `ResponseGenerationHandler` + +**Data Retention & Archival** (use ArchivalService): +- Legal hold — `LegalHoldService` +- Destruction schedules — `DestructionService` +- Retention policies — `RetentionService` + +**Semantic & Hybrid Search** (use SolrController + SettingsController): +- Semantic search via vector embeddings — `SettingsController.semanticSearch()` +- Hybrid search (keyword + semantic combined) — `SolrController.hybridSearch()` +- Vector embedding generation — `VectorizationService` +- NO custom search algorithms — configure via OpenRegister settings + +**GraphQL API** (use GraphQLController): +- Query objects across schemas via GraphQL — `GraphQLController.execute()` +- Alternative to REST for complex cross-entity queries + +**Organization / Multi-Tenancy** (use OrganisationController): +- Organization CRUD — `OrganisationController` +- Tenant-scoped data isolation — automatic via `TenantLifecycleService` +- NO custom multi-tenancy logic + +**Task & Workflow Management** (use TasksController + WorkflowEngineController): +- Task creation and tracking — `TasksController` +- Workflow orchestration — `WorkflowEngineRegistry` +- Scheduled workflows — `ScheduledWorkflowController` +- NO custom task/workflow systems + +**Text Extraction** (use FileTextController): +- Extract text from PDFs and Office docs — `TextExtractionService` +- Entity recognition (PII detection) — `EntityRecognitionHandler` +- Content anonymization — automatic + +**Timeline & Stages** (use CnTimelineStages): +- Workflow progression visualization — `CnTimelineStages` component +- Stage tracking with status colors + +### What apps SHOULD build (custom business logic only): +- External API integrations (SAP, Peppol, TenderNed, etc.) +- PDF/document generation with business-specific templates +- Workflow triggers and business rules specific to the domain +- Notification dispatch with app-specific event types +- Custom settings pages with app-specific configuration +- Background jobs for domain-specific processing + +### ADR-002-api +- URL pattern: `/index.php/apps/{app}/api/{resource}` — lowercase plural, hyphens. +- Methods: GET=read, POST=create, PUT=update, DELETE=remove. No custom methods. +- Pagination: support `_page` + `_limit`. Response includes `total`, `page`, `pages`. +- Errors: appropriate HTTP status + `message` field. NO stack traces in responses. +- Auth: Nextcloud built-in only. NO custom login/session/token flows. +- Public endpoints: annotate `#[PublicPage]` + `#[NoCSRFRequired]`. Register CORS OPTIONS route. + +### ADR-003-backend +- **Controller → Service → Mapper** (strict 3-layer). Controllers NEVER call mappers directly. +- Controllers: thin (<10 lines/method). Routing + validation + response only. +- Services: ALL business logic. Stateless — no instance state between requests. +- Mappers: DB CRUD only. No business logic. +- DI: constructor injection with `private readonly`. NO `\OC::$server` or static locators. +- Entity setters: POSITIONAL args only. `$e->setName('val')` — NEVER `$e->setName(name: 'val')`. + (`__call` passes `['name' => val]` but `setter()` uses `$args[0]`.) +- Routes: `appinfo/routes.php`. Specific routes BEFORE wildcard `{slug}` routes. +- Config: `IAppConfig` with sensitive flag for secrets. NEVER read DB directly. +- Lifecycle: schema init via repair steps (`IRepairStep`), background via job queue, events via dispatcher. +- **Spec traceability**: every class and public method MUST have `@spec` PHPDoc tag(s) linking to + the OpenSpec change that caused it: `@spec openspec/changes/{name}/tasks.md#task-N`. + Multiple `@spec` tags allowed (code touched by multiple changes). File-level `@spec` in header docblock. + This enables: code → docblock → spec traceability alongside code → git blame → commit → issue → spec. + +### ADR-004-frontend +- **Vue 2 + Pinia + @nextcloud/vue + @conduction/nextcloud-vue**. NO Vuex. Options API only. +- State: Pinia stores in `src/store/modules/`. Use `createObjectStore` for OpenRegister CRUD. +- API calls: `axios` from `@nextcloud/axios` — auto-attaches CSRF token. NEVER raw `fetch()` for mutations. + Loading state with `try/finally`. +- Translations: ALL user-visible strings via `t(appName, 'text')`. NO hardcoded strings. + Translation keys MUST be English — Dutch translations go in `l10n/nl.json`. +- CSS: ONLY Nextcloud CSS variables (`var(--color-primary-element)`, etc.). NO hardcoded colors. + NEVER reference `--nldesign-*` directly — nldesign app handles theming. +- Router: history mode, base `generateUrl('/apps/{app}/')`. Requires matching PHP routes in `routes.php`. + Deep link URL templates MUST match the router mode — use path format (`/apps/{app}/entities/{uuid}`), + NOT hash format (`/apps/{app}/#/entities/{uuid}`). +- OpenRegister dependency: settings returns `openRegisters` (bool) + `isAdmin`. + Show empty state if OR missing. NEVER use `OC.isAdmin` — get from backend. +- NEVER `window.confirm()` or `window.alert()` — use `NcDialog` or `CnFormDialog` (WCAG, theming). +- NEVER read app state from DOM (`document.getElementById`, `dataset`) — use backend API or store. +- EVERY `await store.action()` call MUST be wrapped in `try/catch` with user-facing error feedback. +- NEVER import from `@nextcloud/vue` directly — use `@conduction/nextcloud-vue` which re-exports all + NC components plus Conduction components. This ensures consistent theming and component versions. +- EVERY component used in `