diff --git a/l10n/en.json b/l10n/en.json index 4624127..0b091ea 100644 --- a/l10n/en.json +++ b/l10n/en.json @@ -1,6 +1,6 @@ { "translations": { - "App Template settings": "App Template settings", + "Decidesk settings": "Decidesk settings", "Configure the app settings": "Configure the app settings", "Configuration": "Configuration", "Completed": "Completed", diff --git a/l10n/nl.json b/l10n/nl.json index 3e30fe9..8fd9bdd 100644 --- a/l10n/nl.json +++ b/l10n/nl.json @@ -1,6 +1,6 @@ { "translations": { - "App Template settings": "App Template instellingen", + "Decidesk settings": "Decidesk instellingen", "Configure the app settings": "Configureer de app-instellingen", "Configuration": "Configuratie", "Completed": "Afgerond", diff --git a/lib/Sections/SettingsSection.php b/lib/Sections/SettingsSection.php index 738cfe0..cc4b341 100644 --- a/lib/Sections/SettingsSection.php +++ b/lib/Sections/SettingsSection.php @@ -61,7 +61,7 @@ public function getID(): string */ public function getName(): string { - return $this->l->t('App Template'); + return $this->l->t('Decidesk'); }//end getName() /** diff --git a/lib/Settings/decidesk_register.json b/lib/Settings/decidesk_register.json index c4506dc..58e7b6c 100644 --- a/lib/Settings/decidesk_register.json +++ b/lib/Settings/decidesk_register.json @@ -1,15 +1,15 @@ { "openapi": "3.0.0", "info": { - "title": "App Template Register", - "description": "Register containing all schemas for the App Template application.", + "title": "Decidesk Register", + "description": "Universal decision-making platform for governance bodies, associations, corporate boards, and operational meetings", "version": "0.1.0" }, "x-openregister": { "type": "application", "app": "decidesk", "openregister": "^v0.2.10", - "description": "App Template — replace with your app description" + "description": "Universal decision-making platform for governance bodies, associations, corporate boards, and operational meetings" }, "paths": {}, "components": { diff --git a/openspec/specs/admin-settings/spec.md b/openspec/specs/admin-settings/spec.md index 4b36709..16b21ad 100644 --- a/openspec/specs/admin-settings/spec.md +++ b/openspec/specs/admin-settings/spec.md @@ -6,18 +6,51 @@ status: idea ## Purpose -Admin settings enable organization administrators to configure Decidesk for their specific governance context. This includes setting up governing bodies (bodies), assigning members with roles, selecting process templates, configuring voting rules, and managing the OpenRegister schema setup. The admin interface is the first thing configured after installation and determines how the entire system behaves. +Admin settings enable organization administrators to configure Decidesk for their specific governance context. This includes setting up organizations and governing bodies (bestuursorganen), assigning members with roles, selecting process templates, configuring voting methods and quorum rules, managing integration settings, and importing member data. The admin interface is the first thing configured after installation and determines how the entire system behaves. -**Standards**: Nextcloud Settings API (`OCP\Settings\ISettings`), Schema.org (`Organization`, `Role`) +**Standards**: Nextcloud Settings API (`OCP\Settings\ISettings`), Schema.org (`Organization`, `Role`, `GovernmentOrganization`), WBTR (Wet bestuur en toezicht rechtspersonen) **Feature tier**: MVP +**Evidence sources**: Intelligence DB user stories #23, #28, #39, #40, #43, #46, #48, #55, #56, #59, #61, #70, #76, #79, #82, #85, #106, #107, #129, #309, #312, #330, #342, #347, #394; Requirement clusters #18 (Authorization/RBAC, 876 reqs/205 tenders), #19 (Role-based access, 629 reqs/200 tenders), #31 (Zaaktype configuration, 2425 reqs/159 tenders), #43 (Besluitvorming, 271 reqs/133 tenders), #73 (Document templates, 240 reqs/96 tenders); Category features: rbac, role-based-views, template-management, calendar-integration + ## Requirements --- -### Requirement: Governing Body Management +### REQ-AS-01: Organization Configuration -The system MUST support creating and managing governing bodies (bestuursorganen). Each body MUST have a name, type (council, board, assembly, committee, team), member list with roles, default process template, and quorum rules. Bodies MUST be stored as OpenRegister objects in the `decidesk` register using the `body` schema. +The system MUST support configuring organization-level settings: organization name, logo, legal form (vereniging, stichting, cooperatie, NV, BV), default language (nl/en), timezone, currency for cost calculations, and archival retention period. Organization settings MUST be stored as an OpenRegister object using the `organization` schema. + +**Feature tier**: MVP + +#### Scenario: Configure organization defaults + +- GIVEN an administrator opens the organization settings section +- WHEN they set organization name "Vereniging De Harmonie", legal form "vereniging", language "nl", timezone "Europe/Amsterdam", and currency "EUR" +- THEN these defaults MUST apply to all meetings, decisions, and generated documents +- AND the organization name and logo MUST appear on generated resolutions and minutes +- AND the legal form MUST determine which statutory rules (BW 2:38-52) are applied by default + +#### Scenario: Upload organization logo and branding + +- GIVEN an administrator in the organization branding section +- WHEN they upload a logo image and set primary branding color +- THEN the logo MUST be used on generated documents (minutes, resolutions, convocations) +- AND the branding MUST be applied to the Decidesk interface header +- AND the logo MUST be stored in Nextcloud Files under a configurable path + +#### Scenario: Configure archival retention period + +- GIVEN an organization subject to Archiefwet retention rules +- WHEN the administrator sets the default retention period to 10 years +- THEN all decisions, minutes, and resolutions MUST carry this retention metadata +- AND the system MUST warn when documents approach their retention deadline + +--- + +### REQ-AS-02: Governing Body Management + +The system MUST support creating and managing governing bodies (bestuursorganen). Each body MUST have a name, type (council, board, assembly, committee, team, ledenraad), member list with roles, default process template, quorum rules, and optional parent body reference. Bodies MUST be stored as OpenRegister objects in the `decidesk` register using the `body` schema. **Feature tier**: MVP @@ -29,26 +62,89 @@ The system MUST support creating and managing governing bodies (bestuursorganen) - AND each member MUST be linked to a Nextcloud user account - AND the default process template MUST be selectable from available templates -#### Scenario: Configure quorum rules for a body +#### Scenario: Create a committee under a parent body -- GIVEN an existing body "Algemene Ledenvergadering" with 200 members -- WHEN the administrator sets quorum to "50%+1 of members present or represented" -- THEN the quorum rule MUST be stored on the body configuration -- AND the quorum MUST be automatically calculated at each meeting +- GIVEN an existing body "Bestuur" (board) +- WHEN the administrator creates a body "Kascommissie" with type "committee" and parent "Bestuur" +- THEN the committee MUST be linked to its parent body +- AND the committee MUST have its own member list independent of the parent +- AND the committee MUST validate that members are not board members (per BW 2:48) + +#### Scenario: Create an ALV body with large membership + +- GIVEN an organization with 200 registered members +- WHEN the administrator creates a body "Algemene Ledenvergadering" with type "assembly" +- THEN the body MUST support all 200 members as potential voters +- AND the system MUST differentiate between voting and non-voting members +- AND the body MUST support proxy (volmacht) configuration + +--- + +### REQ-AS-03: Member Role Management + +The system MUST support assigning roles to body members. Standard roles MUST include chair (voorzitter), secretary (secretaris), treasurer (penningmeester), and member (lid). Custom roles MUST be supported. Each role MUST map to specific permissions within the governance workflow. + +**Feature tier**: MVP #### Scenario: Assign roles within a body - GIVEN an existing body with members - WHEN the administrator assigns the "chair" role to a member -- THEN the member MUST have chair-specific permissions (start votes, manage agenda, set speaking order) -- AND the "secretary" role MUST grant minute-taking and convocation permissions +- THEN the member MUST have chair-specific permissions (start votes, manage agenda, set speaking order, declare meeting opened/closed) +- AND the "secretary" role MUST grant minute-taking, convocation, and document management permissions +- AND the "treasurer" role MUST grant financial report upload and budget proposal permissions - AND the "member" role MUST grant voting and speaking rights only +#### Scenario: Configure role-specific notification defaults + +- GIVEN an administrator configuring the "secretary" role +- WHEN they set notification defaults for the role +- THEN all users assigned this role MUST receive notifications for convocation deadlines, minute approval requests, and action item assignments by default +- AND individual users MAY override these defaults in their personal settings + +#### Scenario: Assign multiple roles to a single member + +- GIVEN a small board where one person serves as both secretary and treasurer +- WHEN the administrator assigns both roles to member A +- THEN member A MUST have the combined permissions of both roles +- AND both roles MUST be visible in the member's profile and in meeting attendance records + --- -### Requirement: Process Template Assignment +### REQ-AS-04: Quorum Rule Configuration -The system MUST allow administrators to assign process templates to bodies. Each body MUST have a default template and MAY have additional templates for specific decision types (e.g., statute amendment, board election). +The system MUST allow administrators to configure quorum rules per body. Quorum rules MUST support absolute numbers, percentages, and formulas (e.g., "50%+1 of members present or represented"). The system MUST support different quorum rules for different decision types (ordinary decisions vs. statute amendments). + +**Feature tier**: MVP + +#### Scenario: Configure standard quorum for a body + +- GIVEN an existing body "ALV" with 200 members +- WHEN the administrator sets quorum to "50%+1 of members present or represented" +- THEN the quorum MUST be automatically calculated at each meeting based on registered attendance and proxy votes +- AND the system MUST display real-time quorum status (met / not met / at risk) + +#### Scenario: Configure qualified majority for statute amendments + +- GIVEN a body "ALV" with standard quorum rules +- WHEN the administrator adds a special rule: "Statute amendments require 2/3 of members present AND 2/3 majority" +- THEN this rule MUST automatically apply when a decision is marked as "statute amendment" type +- AND the voting interface MUST show both the quorum and majority thresholds +- AND the system MUST generate proof documents for the notary confirming proper quorum and majority + +#### Scenario: Configure quorum with proxy vote limits + +- GIVEN statutes that limit proxy votes to maximum 3 per person +- WHEN the administrator configures this limit on the body +- THEN the system MUST reject proxy assignments that exceed the limit +- AND proxy votes MUST be counted toward quorum calculation +- AND the system MUST flag members holding more than the allowed number of proxies + +--- + +### REQ-AS-05: Process Template Assignment + +The system MUST allow administrators to assign process templates to bodies. Each body MUST have a default template and MAY have additional templates for specific decision types (e.g., statute amendment, board election, budget approval, circular resolution). **Feature tier**: MVP @@ -60,26 +156,50 @@ The system MUST allow administrators to assign process templates to bodies. Each - AND when creating a decision, the user MUST be able to choose the applicable template - AND if no template is chosen, the default MUST apply +#### Scenario: Create a circular resolution template + +- GIVEN a body "Bestuur" that needs to make decisions between meetings +- WHEN the administrator creates a template "Written Decision (BW 2:40)" with workflow steps: propose, circulate, collect votes, record +- THEN the template MUST require unanimous consent for valid decisions +- AND the template MUST enforce a configurable response deadline +- AND non-responding board members MUST receive escalating reminders + +#### Scenario: Configure template with mandatory agenda items + +- GIVEN a body "ALV" that must always include certain agenda items +- WHEN the administrator configures mandatory items (opening, approval previous minutes, annual report, financial statements, kascommissie report, board election, rondvraag, closing) +- THEN every meeting created with this template MUST include these items +- AND mandatory items MUST NOT be removable from the agenda + --- -### Requirement: Organization Configuration +### REQ-AS-06: Voting Method Configuration -The system MUST support configuring organization-level settings: organization name, logo, default language (nl/en), timezone, currency for cost calculations, and archival retention period. +The system MUST allow administrators to configure voting methods per body and per decision type. Supported methods MUST include: open vote (show of hands), roll call vote (per-member recorded), secret ballot, and digital/hybrid vote. Each method MUST define how results are calculated and displayed. **Feature tier**: MVP -#### Scenario: Configure organization defaults +#### Scenario: Configure voting methods for a body -- GIVEN the administrator opens the organization settings -- WHEN they set organization name "Vereniging De Harmonie", language "nl", timezone "Europe/Amsterdam", and currency "EUR" -- THEN these defaults MUST apply to all meetings, decisions, and generated documents -- AND the organization name and logo MUST appear on generated resolutions and minutes +- GIVEN a body "Bestuur" with 7 members +- WHEN the administrator sets default voting method to "open vote" and adds "secret ballot" for board elections +- THEN ordinary decisions MUST use open (per-member visible) voting +- AND board election decisions MUST automatically use secret ballot +- AND the administrator MUST be able to override the method for individual decisions + +#### Scenario: Configure majority calculation rules + +- GIVEN a body with configurable voting +- WHEN the administrator sets majority rules: simple majority (>50% of votes cast), absolute majority (>50% of all members), qualified majority (2/3 of votes cast), unanimous +- THEN each decision type MUST use its configured majority rule +- AND the voting results screen MUST show both the threshold and actual result +- AND abstentions MUST be handled according to the configured rule (counted or excluded) --- -### Requirement: Member Import +### REQ-AS-07: Member Import and Synchronization -The system MUST support importing members from Nextcloud Groups, Nextcloud Contacts, or CSV file. Imported members MUST be linked to Nextcloud user accounts where possible. +The system MUST support importing members from Nextcloud Groups, Nextcloud Contacts, or CSV file. Imported members MUST be linked to Nextcloud user accounts where possible. The system MUST support ongoing synchronization with Nextcloud Groups. **Feature tier**: MVP @@ -93,26 +213,192 @@ The system MUST support importing members from Nextcloud Groups, Nextcloud Conta #### Scenario: Import members from CSV -- GIVEN a CSV file with columns: name, email, role +- GIVEN a CSV file with columns: name, email, role, membership_category, voting_rights - WHEN the administrator uploads the CSV for a body - THEN the system MUST create member entries for each row - AND members with matching Nextcloud accounts (by email) MUST be automatically linked - AND unmatched members MUST be flagged for manual linking or invitation +#### Scenario: Synchronize body membership with Nextcloud group + +- GIVEN a body "Bestuur" linked to Nextcloud group "bestuur" +- WHEN a new user is added to the Nextcloud group +- THEN the user MUST be automatically added to the Decidesk body with "member" role +- AND when a user is removed from the group, they MUST be deactivated (not deleted) in the body +- AND the sync MUST be configurable as automatic or manual + +--- + +### REQ-AS-08: Conflict of Interest Register + +The system MUST support maintaining a digital conflict of interest register for all body members. The register MUST be automatically checked against agenda items to flag potential conflicts before meetings. + +**Feature tier**: V1 + +#### Scenario: Manage conflict of interest register + +- GIVEN a board with 7 members +- WHEN the administrator or secretary adds interests for each member (company affiliations, family relationships, financial interests) +- THEN the register MUST store all declared interests per member +- AND the system MUST automatically flag potential conflicts when agenda items match registered interests +- AND members MUST receive a notification to confirm or dismiss flagged conflicts before the meeting + +#### Scenario: Annual conflict of interest update + +- GIVEN a conflict of interest register that was last updated 11 months ago +- WHEN the annual review deadline approaches +- THEN all body members MUST receive a notification to review and update their declarations +- AND the secretary MUST receive a dashboard showing which members have completed their update +- AND the system MUST track declaration history with timestamps + +--- + +### REQ-AS-09: Board Handover Management + +The system MUST support structured handover when body members change. The handover process MUST include a configurable checklist covering access transfer, KvK registration, signing authority, and knowledge transfer. + +**Feature tier**: V1 + +#### Scenario: Execute board member handover checklist + +- GIVEN a board member is being replaced +- WHEN the administrator initiates a handover process +- THEN a checklist MUST be created with all required steps (KvK update, bank access transfer, system access revocation/granting, document handover) +- AND each step MUST have an assignee and deadline +- AND the handover MUST NOT be marked complete until all steps are confirmed + +--- + +### REQ-AS-10: Integration Settings + +The system MUST allow administrators to configure integration settings for connected Nextcloud apps. Integrations MUST include Calendar (meeting sync), Files (document storage path), Talk (meeting channels), Mail (convocation delivery), and Activity (audit trail). + +**Feature tier**: V1 + +#### Scenario: Configure document storage path + +- GIVEN the administrator in integration settings +- WHEN they set the base document path to "Governance/Decidesk" +- THEN all meeting folders MUST be created under this path in Nextcloud Files +- AND the path MUST be validated for write permissions +- AND existing meetings MUST NOT be affected by a path change + +#### Scenario: Configure mail integration for convocations + +- GIVEN the administrator enabling mail integration +- WHEN they configure the sender address and convocation template +- THEN convocations MUST be sent from the configured address +- AND the template MUST support merge fields for meeting date, body name, agenda link, and document links +- AND the system MUST track delivery status per recipient + +--- + +### REQ-AS-11: Meeting Cost Configuration + +The system MUST allow administrators to configure meeting cost calculation parameters per body. This includes hourly rates (average or per-member), cost components (salary, benefits, overhead), and reporting periods. + +**Feature tier**: V2 + +#### Scenario: Configure meeting cost parameters + +- GIVEN an administrator setting up cost tracking for the MT body +- WHEN they set average hourly rate to EUR 95 including benefits and overhead +- THEN the system MUST calculate meeting costs as attendees x hourly rate x duration +- AND the cost dashboard MUST show cost trends over time per body +- AND the live meeting cost ticker MUST be optionally displayable during meetings + +--- + +### REQ-AS-12: Compliance Configuration + +The system MUST allow administrators to configure statutory compliance settings based on the organization's legal form and applicable regulations (BW, WBTR, statutes). + +**Feature tier**: V2 + +#### Scenario: Configure WBTR compliance rules + +- GIVEN an organization of type "vereniging" +- WHEN the administrator enables WBTR compliance +- THEN the system MUST enforce conflict of interest declarations (BW 2:10) +- AND multiple voting restrictions MUST be applied per BW 2:40 +- AND board decision documentation requirements MUST be enforced +- AND the Corporate Governance Code provisions MUST be trackable with comply-or-explain statements + ## User Stories -1. **Board secretary managing conflict of interest register**: As a board secretary, I want to maintain a digital conflict of interest register for all board and supervisory board members, so that potential conflicts are proactively identified before meetings. (Source: intelligence DB #23) +1. **Board secretary managing conflict of interest register**: As a board secretary, I want to maintain a digital conflict of interest register for all board and supervisory board members, so that potential conflicts are proactively identified before meetings. (Source: intelligence DB #23, priority: must) + +2. **Supervisory board chair managing director appointment**: As a supervisory board chair, I want to manage the full director appointment process from vacancy to formal appointment, so that governance procedures are properly followed. (Source: intelligence DB #28, priority: should) + +3. **Board secretary organizing document archive**: As a board secretary, I want to maintain a structured, searchable governance document archive with access controls, so that governance documents are secure, findable, and properly retained. (Source: intelligence DB #43, priority: must) + +4. **Legal counsel tracking governance code compliance**: As legal counsel, I want to track compliance with each provision of the Corporate Governance Code, so that I can prepare the comply-or-explain statement for the annual report. (Source: intelligence DB #39, priority: must) + +5. **Board secretary preparing governance chapter**: As a board secretary, I want to compile the corporate governance chapter for the annual report from compliance data, so that reporting is consistent and complete. (Source: intelligence DB #40, priority: should) + +6. **Secretary sending ALV convocation**: As secretary, I want to send the ALV convocation to all voting members via their preferred channel so that I can prove all members were properly notified within the statutory deadline. (Source: intelligence DB #46, priority: critical) + +7. **Secretary handling extraordinary ALV request**: As secretary, I want to verify that an extraordinary ALV request is valid (signed by 10%+ of members) and convene the meeting within 4 weeks so that we comply with BW 2:41. (Source: intelligence DB #48, priority: high) + +8. **Secretary registering attendance and verifying quorum**: As secretary, I want to register member attendance and automatically calculate quorum including proxy votes so that I can confirm the meeting is valid. (Source: intelligence DB #55, priority: critical) + +9. **Secretary verifying member voting rights**: As secretary, I want to verify each attendee's voting rights so that only eligible members participate in voting. (Source: intelligence DB #56, priority: critical) + +10. **Secretary verifying qualified majority for statute amendments**: As secretary, I want to verify that a statute amendment vote meets the required quorum and qualified majority so that the notary can confirm proper procedure. (Source: intelligence DB #59, priority: critical) + +11. **Chair nominating kascommissie members**: As chair, I want to present kascommissie candidates for ALV approval ensuring they meet requirements (non-board, minimum 2) so that the audit function is properly established. (Source: intelligence DB #70, priority: high) + +12. **Administrator publishing meeting decisions**: As administrator, I want to publish key decisions from ALV and board meetings on the member portal so that all members stay informed about association governance. (Source: intelligence DB #76, priority: medium) + +13. **Member petitioning for extraordinary ALV**: As a member, I want to digitally petition for an extraordinary ALV and collect supporting signatures so that we can reach the 10% threshold required by law. (Source: intelligence DB #79, priority: medium) + +14. **Ledenraad member preparing for council meeting**: As a ledenraad member, I want to review the agenda, consult my constituency, and prepare my voting position so that I can effectively represent my members. (Source: intelligence DB #82, priority: medium) + +15. **Secretary executing board member handover**: As secretary, I want to follow a structured handover checklist when board members change so that KvK registration, signing authority, bank access, and system access are all properly transferred. (Source: intelligence DB #85, priority: high) + +16. **MT member cascading new policy**: As an MT member, I want to cascade an approved policy through the management layers so that every employee understands what changed and what it means for them. (Source: intelligence DB #106, priority: medium) + +17. **CEO tracking policy adoption**: As a CEO, I want to track which policies have been acknowledged and implemented across departments so that I can identify compliance gaps. (Source: intelligence DB #107, priority: low) + +18. **Employee searching decision register**: As an employee, I want to search a central decision register by topic, date, meeting, or decision-maker, so that I can find relevant past decisions. (Source: intelligence DB #129, priority: high) + +19. **Clerk publishing vote results**: As a clerk, I want to publish vote results including each member's position so that citizens can verify how their representatives voted. (Source: intelligence DB #309, priority: must) + +20. **Board chair verifying quorum before voting**: As a board chair, I want to verify quorum before opening voting so that all decisions taken are legally valid per BW 2:38. (Source: intelligence DB #312, priority: must) + +21. **CEO viewing meeting cost dashboard**: As a CEO, I want to see a real-time dashboard showing total organizational meeting costs and trends so that I can identify optimization opportunities. (Source: intelligence DB #330, priority: must) + +22. **Meeting secretary tracking quorum and attendance**: As a meeting secretary, I want real-time quorum tracking with automatic alerts when quorum is at risk, and historical attendance analytics per member. (Source: intelligence DB #342, priority: must) + +23. **Board secretary conducting formal votes**: As a board secretary, I want to conduct formal votes with configurable majority rules (simple, absolute, qualified 2/3) and an auditable record. (Source: intelligence DB #347, priority: must) + +24. **Raadslid drafting motion from template**: As a raadslid, I want to create a motion using a standard template, so that my motion meets all procedural requirements. (Source: intelligence DB #144, priority: must) + +25. **New council member onboarding**: As a new raadslid, I want a guided onboarding process for all digital tools, so that I can start my council work immediately after being sworn in. (Source: intelligence DB #201, priority: should) -2. **Supervisory board chair managing director appointment**: As a supervisory board chair, I want to manage the full director appointment process from vacancy to formal appointment, so that governance procedures are properly followed. (Source: intelligence DB #28) +26. **Candidate presenting profile to members**: As a board candidate, I want to present my profile, vision, and qualifications to all members before the election so that they can make an informed choice. (Source: intelligence DB #61, priority: medium) -3. **Board secretary organizing document archive**: As a board secretary, I want to maintain a structured, searchable governance document archive with access controls, so that governance documents are secure, findable, and properly retained. (Source: intelligence DB #43) +27. **CEO viewing meeting health report**: As a CEO, I want a monthly organizational meeting health report showing key metrics compared to industry benchmarks. (Source: intelligence DB #349, priority: should) ## Acceptance Criteria -- Governing bodies are stored as OpenRegister objects with member lists and roles -- Body roles (chair, secretary, treasurer, member) map to specific permissions -- Process templates are assignable to bodies with default and specialized options -- Organization-level settings (name, logo, language, timezone) are configurable -- Member import from Nextcloud Groups, Contacts, and CSV is supported -- Quorum rules are configurable per body -- Admin settings use Nextcloud Settings API (OCP\Settings\ISettings) +1. Organization settings (name, logo, legal form, language, timezone, currency, retention) are stored as an OpenRegister object with the `organization` schema +2. Governing bodies are stored as OpenRegister objects with member lists, roles, and parent body references +3. Body types include council, board, assembly, committee, team, and ledenraad +4. Body roles (chair, secretary, treasurer, member, custom) map to specific governance permissions +5. Quorum rules are configurable per body with support for absolute numbers, percentages, and formulas +6. Different quorum/majority rules are configurable per decision type (ordinary vs. statute amendment) +7. Proxy vote limits are configurable per body according to statutes +8. Process templates are assignable to bodies with default and specialized options +9. Templates support mandatory agenda items that cannot be removed +10. Voting methods (open, roll call, secret ballot, digital) are configurable per body and decision type +11. Majority calculation rules (simple, absolute, qualified, unanimous) are configurable +12. Member import from Nextcloud Groups, Contacts, and CSV is supported with automatic account linking +13. Group synchronization is configurable as automatic or manual +14. Conflict of interest register with automatic agenda-item flagging is supported +15. Board handover checklist with step tracking and deadline management is supported +16. Integration settings (Calendar, Files, Talk, Mail, Activity) are configurable +17. Meeting cost calculation parameters (hourly rates, components) are configurable per body +18. WBTR and statutory compliance rules are configurable based on legal form +19. Admin settings use Nextcloud Settings API (`OCP\Settings\ISettings`) +20. All configuration changes are logged in the Nextcloud Activity feed for audit purposes diff --git a/openspec/specs/agenda-management/spec.md b/openspec/specs/agenda-management/spec.md index 1dab077..17814c5 100644 --- a/openspec/specs/agenda-management/spec.md +++ b/openspec/specs/agenda-management/spec.md @@ -4,27 +4,46 @@ status: idea # Agenda Management Specification -## Purpose +**Status**: idea +**Standards**: Schema.org (`ItemList`, `ListItem`), Akoma Ntoso (`debateSection`, `pointOfOrder`), OpenRaadsinformatie (`AgendaPunt`), Woo, Digitoegankelijk (EN 301 549) +**Feature tier**: MVP -Agenda management handles the creation, ordering, and conduct of meeting agendas. An agenda is a structured list of items to be discussed at a meeting, each with a type (informational, discussion, decision), allocated time, and attached documents. The system supports drag-and-drop reordering, legally required items for specific meeting types (e.g., ALV statutory items), and real-time agenda tracking during meetings. +## Purpose -**Standards**: Schema.org (`ItemList`, `ListItem`), Akoma Ntoso (`debateSection`, `pointOfOrder`), OpenRaadsinformatie (`AgendaPunt`) -**Feature tier**: MVP +Agenda management handles the creation, ordering, and conduct of meeting agendas. An agenda is a structured list of items to be discussed at a meeting, each with a type (informational, discussion, decision), allocated time, and attached documents. The system supports drag-and-drop reordering, legally required items for specific meeting types (e.g., ALV statutory items), and real-time agenda tracking during meetings. Research shows that 67% of professionals say a clear agenda is the most important meeting element (source #320), yet only 37% of meetings use agendas (source #319). ## Data Model -See [ARCHITECTURE.md](../../docs/ARCHITECTURE.md) for the full AgendaItem entity definition including property tables, Schema.org mappings, and OpenRaadsinformatie alignment. +See [ARCHITECTURE.md](../../docs/ARCHITECTURE.md) for the full entity definitions. + +| Entity | Schema.org Type | Key Properties | +|--------|----------------|----------------| +| AgendaItem | `schema:ListItem` | title, itemType, position, startTime, indiener (submitter), presenter, decisionPoint (linked Motion/Vote), speakers[], meeting, documents | +| MeetingType | `schema:EventSeries` | name, domain, defaultAgendaItems (JSON), quorumRule, votingMethod, speakingTimeRules | +| DocumentPackage | `schema:CreativeWork` | meeting, tableOfContents, documents | + +### Key Design Decisions + +**Dynamic duration**: An agenda item's duration is NOT a fixed property but is calculated dynamically as `nextItem.startTime - thisItem.startTime` (or `meeting.endTime - thisItem.startTime` for the last item). Only `startTime` is stored. + +**Indiener (submitter)**: Every agenda item tracks who submitted/proposed it. This enables proposal status tracking — submitters can see where their item is in the review/approval pipeline. + +**Decision points**: An agenda item can be linked to a Motion, Amendment, or Vote via the `decisionPoint` field. This means "agenda item 7 is about voting on motion X". The voting interface activates when the meeting progresses to this item. + +**Speakers**: Participants can register as speakers for specific agenda items before or during the meeting. The chair manages the speakers list. Speaking time is tracked per speaker per item. + +**Meeting types are configuration, not code**: Meeting types (council meeting, ALV, board meeting, MT, committee) are seeded configuration objects, not hardcoded enums. Each type defines default agenda items, quorum rules, voting methods, and speaking time rules. Admins can create new types or modify existing ones. + +**Default agenda items**: A MeetingType seeds its meetings with default items. For example, a Dutch council meeting type seeds: 1. Opening, 2. Vaststellen agenda, 3. Vaststellen notulen vorige vergadering, ... N-1. Rondvraag, N. Sluiting. These can be reordered or removed per meeting. ## Requirements --- -### Requirement: Agenda Item Creation +### Requirement: Agenda Item Creation [MVP] The system MUST support creating agenda items with a title, type (informational, discussion, decision), description, allocated time, presenter, and attached documents. Agenda items MUST be stored as OpenRegister objects in the `decidesk` register using the `agendaItem` schema. -**Feature tier**: MVP - #### Scenario: Create a decision agenda item - GIVEN a user preparing an agenda for the board meeting @@ -48,13 +67,25 @@ The system MUST support creating agenda items with a title, type (informational, - AND the chair MUST be notified of the pending proposal - AND the chair MUST be able to accept or reject the agenda addition ---- +#### Scenario: Submit agenda item with structured form -### Requirement: Agenda Ordering and Structure +- GIVEN an MT member preparing items for the next meeting +- WHEN they submit an agenda item through a structured form with title, description, decision required (yes/no), time needed, and supporting documents +- THEN the secretary MUST receive the submission for compilation +- AND the system MUST validate that all required fields are completed -The system MUST support drag-and-drop reordering of agenda items. The system MUST enforce legally required items for specific meeting types (e.g., ALV must include annual report, financial statements, kascommissie report, board elections). Sub-items MUST be supported for grouping related topics. +#### Scenario: Shareholder agenda item request (NV/BV) -**Feature tier**: MVP +- GIVEN a shareholder with 3% (NV) or 1% (BV) of share capital +- WHEN they request an item to be added to the AGM agenda +- THEN the board MUST include the item unless it conflicts with vital company interests +- AND the system MUST track the request with the shareholder's identity and share percentage + +--- + +### Requirement: Agenda Ordering and Structure [MVP] + +The system MUST support drag-and-drop reordering of agenda items. The system MUST enforce legally required items for specific meeting types. Sub-items MUST be supported for grouping related topics. #### Scenario: Reorder agenda items via drag-and-drop @@ -70,6 +101,12 @@ The system MUST support drag-and-drop reordering of agenda items. The system MUS - THEN the system MUST prompt to include required items: opening, approval of previous minutes, annual report, financial statements, kascommissie report, board elections, any other business, closing - AND missing required items MUST be highlighted with a warning +#### Scenario: Enforce required items for cooperative ALV + +- GIVEN a meeting of type "general_assembly" for a cooperative (cooperatie) +- WHEN the user creates the agenda +- THEN the system MUST additionally prompt for: profit distribution/loss allocation, member liability considerations (UA/BA/WA), and cooperative-specific business items + #### Scenario: Group agenda items with sub-items - GIVEN an agenda item "Committee Reports" @@ -77,13 +114,55 @@ The system MUST support drag-and-drop reordering of agenda items. The system MUS - THEN the sub-items MUST appear nested under the parent item - AND each sub-item MUST have its own allocated time, type, and presenter +#### Scenario: Classify items as hamerstuk or bespreekstuk + +- GIVEN a council meeting agenda with multiple items +- WHEN the voorzitter classifies agenda items as hamerstuk (consent) or bespreekstuk (discussion) +- THEN hamerstukken MUST be grouped together for batch processing +- AND bespreekstukken MUST have full speaking time allocation +- AND the classification MUST be visible in the published agenda + +#### Scenario: Set document submission deadlines per agenda item + +- GIVEN an agenda item requiring supporting documents +- WHEN the griffier sets a document submission deadline +- THEN document owners MUST be notified of the deadline +- AND the system MUST warn when deadlines are missed +- AND the agenda package MUST NOT be published until all required documents are received + --- -### Requirement: Agenda Time Management +### Requirement: Agenda Templates [MVP] -The system MUST calculate total meeting duration from individual item allocations. The system MUST warn when total allocated time exceeds a configured meeting length. During meetings, the system MUST track time spent per agenda item. +The system MUST support agenda templates for recurring meeting types that pre-populate required items. -**Feature tier**: MVP +#### Scenario: Create agenda from ALV template + +- GIVEN an ALV meeting template with required statutory items +- WHEN the secretary creates a new ALV from the template +- THEN the agenda MUST be pre-populated with: opening, approval of previous minutes, annual report, financial statements, kascommissie report, board elections, any other business, closing +- AND the secretary MUST be able to add, remove, or reorder additional items +- AND removed required items MUST trigger a compliance warning + +#### Scenario: Create agenda from MT weekly template + +- GIVEN an MT weekly meeting template with standing items (action item review, decisions pending, department updates) +- WHEN a new meeting instance is created from the recurring schedule +- THEN standing items MUST be pre-populated +- AND open action items from previous meetings MUST be automatically carried over as a sub-item + +#### Scenario: Create agenda from council meeting template + +- GIVEN a council meeting template following the BOB model +- WHEN the griffier creates a new council meeting agenda +- THEN items MUST be tagged with their BOB phase (Beeldvorming/Oordeelsvorming/Besluitvorming) +- AND the template MUST include: opening, hamerstukken, bespreekstukken, moties/amendementen, closing + +--- + +### Requirement: Agenda Time Management [MVP] + +The system MUST calculate total meeting duration from individual item allocations. The system MUST warn when total allocated time exceeds a configured meeting length. During meetings, the system MUST track time spent per agenda item. #### Scenario: Calculate total agenda duration @@ -99,14 +178,27 @@ The system MUST calculate total meeting duration from individual item allocation - THEN the system MUST display a time-over indicator - AND the chair MUST be able to extend the time or move to the next item +#### Scenario: Use per-item countdown timers + +- GIVEN a meeting with agenda items having specific time allocations +- WHEN the chair starts an agenda item +- THEN a visible countdown timer MUST display the remaining time +- AND audio/visual alerts MUST fire when time is up +- AND the chair MUST be able to extend or skip to the next item + +#### Scenario: Track agenda adherence metrics + +- GIVEN a completed meeting with time-tracked agenda items +- WHEN the meeting analytics are generated +- THEN the system MUST show: actual vs allocated time per item, total meeting overrun/underrun, and agenda adherence percentage +- AND this MUST feed into the meeting efficiency dashboard + --- -### Requirement: Agenda Document Package +### Requirement: Agenda Document Package (Vergaderstukken) [MVP] The system MUST support assembling all agenda item documents into a single meeting package (vergaderstukken) for distribution to participants. -**Feature tier**: MVP - #### Scenario: Assemble meeting package from agenda documents - GIVEN a meeting with 5 agenda items, each with one or more attached documents @@ -115,24 +207,572 @@ The system MUST support assembling all agenda item documents into a single meeti - AND documents MUST be organized by agenda item number and title - AND the package MUST be available for download and distribution via convocation -## User Stories +#### Scenario: Publish agenda package in one action + +- GIVEN a complete agenda with all documents attached +- WHEN the griffier triggers "Publish agenda package" +- THEN the complete agenda with all accompanying documents MUST be published in one action +- AND council members and the public MUST be able to access everything they need +- AND the publication timestamp MUST be recorded for Woo compliance + +#### Scenario: Board pack assembly from multiple sources + +- GIVEN a board meeting with documents from finance, legal, HR, and operations +- WHEN the secretary assembles the board pack +- THEN documents MUST be combined into a structured, indexed package +- AND the package MUST be accessible on tablet with offline capability +- AND version tracking MUST ensure only the latest document versions are included + +--- + +### Requirement: Agenda Item Proposals and Member Submissions [MVP] + +The system MUST support members submitting agenda item proposals through a structured workflow. + +#### Scenario: Member submits motion for ALV agenda + +- GIVEN a member of an association with an upcoming ALV +- WHEN they submit a motion with title, supporting arguments, and the desired outcome +- THEN the board/chair MUST be notified of the pending proposal +- AND the proposal MUST be reviewed before the statutory deadline for agenda additions +- AND if accepted, the motion MUST appear on the published agenda with all supporting materials + +#### Scenario: Citizen submits initiative for council agenda (burgerinitiatief) + +- GIVEN a citizen with a proposal that has collected the required signatures +- WHEN they submit a formal citizen initiative to the municipal council +- THEN the system MUST validate the signature count against the requirement +- AND the initiative MUST be placed on the council agenda per the burgerinitiatief procedure +- AND the citizen MUST be notified of the scheduled date + +#### Scenario: Neighbourhood council collects agenda items from residents + +- GIVEN a neighbourhood council with an upcoming meeting +- WHEN residents submit agenda items digitally +- THEN items MUST be collected and presented to the council for prioritization +- AND residents who submitted items MUST be notified of whether their item was included + +--- + +### Requirement: Agenda Item Linking and Cross-References [MVP] + +The system MUST support linking agenda items to decisions, motions, amendments, and previous meeting items. + +#### Scenario: Link motion to agenda item + +- GIVEN a raadslid who has drafted a motion +- WHEN they link the motion to a specific agenda item +- THEN the motion MUST be automatically included in the debate on that topic +- AND the motion MUST appear in the agenda view under its linked item + +#### Scenario: Link agenda item to previous meeting decision + +- GIVEN an agenda item that is a follow-up to a previous decision +- WHEN the secretary links it to the original decision +- THEN the linked decision MUST be visible on the agenda item +- AND the implementation status of the previous decision MUST be shown + +#### Scenario: Committee advice attached to plenary agenda item + +- GIVEN a committee that has discussed an item and formed an advice +- WHEN the commissievoorzitter formally records the committee advice +- THEN the advice MUST be linked to the corresponding plenary agenda item +- AND the presidium MUST be able to see the advice when planning the plenary agenda + +--- + +### Requirement: Speaking Order and Inspreekrecht [V1] + +The system SHOULD support managing the speaking order for agenda items and citizen speaking rights (inspreekrecht) for committee meetings. + +#### Scenario: Manage committee speaking order + +- GIVEN a committee meeting with members and registered insprekers +- WHEN the chair manages the speaking order +- THEN insprekers MUST be scheduled first per standard practice +- AND each speaker MUST have a configurable time limit (default 5 minutes per Reglement van Orde) +- AND time tracking MUST be visible to the chair and speakers + +#### Scenario: Schedule hearing speakers + +- GIVEN a hearing with multiple registered speakers +- WHEN the hearing secretary schedules speakers +- THEN each speaker MUST receive a time slot and topic confirmation +- AND the schedule MUST account for breaks and transitions +- AND late registrations MUST be handled per the hearing rules + +--- + +### Requirement: Real-Time Agenda Tracking During Meetings [MVP] + +The system MUST support real-time tracking of which agenda item is currently being discussed during a meeting. + +#### Scenario: Track current agenda item during meeting + +- GIVEN a meeting in progress +- WHEN the chair moves to the next agenda item +- THEN the system MUST update the current item indicator in real-time +- AND all participants (including remote) MUST see which item is active +- AND citizens following via webcast MUST be able to see the current item + +#### Scenario: Auto-create Talk conversation per agenda item + +- GIVEN an agenda item flagged for deliberation +- WHEN the agenda is finalized +- THEN the system SHOULD auto-create a Nextcloud Talk conversation for informal discussion (insight #27) +- AND the conversation MUST be linked to the agenda item and accessible to body members + +--- + +### Requirement: Agenda Publication and Transparency [MVP] + +The system MUST support publishing agendas for public access per Woo requirements. + +**Legal reference**: Woo Art. 3.3 -- active publication of agendas of councils, B&W, and other public bodies + +#### Scenario: Publish council meeting agenda for public access -1. **Board secretary creating AGM agenda**: As a board secretary, I want to create and manage the AGM agenda with drag-and-drop resolution ordering, so that I can efficiently prepare a compliant meeting agenda within statutory deadlines. (Source: intelligence DB #1) +- GIVEN a finalized council meeting agenda +- WHEN the griffier publishes the agenda +- THEN the agenda MUST be publicly accessible with all non-confidential documents +- AND confidential items MUST be marked but not publicly visible +- AND the publication MUST comply with Digitoegankelijk (WCAG 2.1) -2. **Chair composing ALV agenda**: As chair, I want to compose the ALV agenda ensuring all legally required items are included (annual report, financial statements, kascommissie report, board elections) so that the meeting is legally valid. (Source: intelligence DB #49) +#### Scenario: Notify citizens of agenda topics of interest -3. **MT member submitting agenda item**: As an MT member, I want to submit agenda items with supporting documents through a structured form, so that the secretary can compile a complete and well-organized agenda. (Source: intelligence DB #87) +- GIVEN citizens who have set up keyword-based alerts +- WHEN a new agenda is published containing matching keywords +- THEN those citizens MUST receive notifications about relevant agenda items +- AND the notification MUST link directly to the agenda item -4. **Member submitting a motion for agenda**: As a member, I want to submit a motion or proposal for the ALV agenda with supporting arguments so that my topic is formally discussed and voted on. (Source: intelligence DB #54) +--- + +### Requirement: Consent Agenda (Hamerstukken) Processing [MVP] + +The system MUST support grouping non-controversial items as hamerstukken for batch adoption. + +#### Scenario: Process consent agenda items in one batch + +- GIVEN a council meeting agenda with 4 items classified as hamerstukken +- WHEN the voorzitter calls the consent agenda +- THEN all hamerstukken MUST be votable as a single batch +- AND if any member requests to remove an item from the consent agenda, it MUST be moved to the discussion items +- AND adopted hamerstukken MUST be recorded as individual decisions + +--- + +### Requirement: Automatic Agenda Generation for Recurring Meetings [V1] + +The system SHOULD support automatic agenda generation for recurring meetings with carried-over items. + +#### Scenario: Generate agenda for next recurring meeting + +- GIVEN a weekly MT meeting with standing items +- WHEN the next meeting instance is auto-created +- THEN the agenda MUST include: standing items from template, open action items from previous meeting, and items submitted since last meeting +- AND the secretary MUST be able to review and adjust before distribution + +#### Scenario: Carry over unfinished agenda items + +- GIVEN a meeting that ended with 2 agenda items not discussed +- WHEN the next meeting's agenda is prepared +- THEN the system MUST offer to carry over the unfinished items +- AND carried-over items MUST be marked as such with the original meeting reference + +--- + +### Requirement: Agenda Annotations and Preparation [V1] + +The system SHOULD support annotating agenda documents for meeting preparation. + +#### Scenario: Annotate meeting documents on tablet + +- GIVEN a raadslid reviewing meeting documents +- WHEN they highlight text and add notes to agenda documents +- THEN annotations MUST be saved privately for the user +- AND annotations MUST be accessible during the meeting +- AND annotations MUST NOT be lost when documents are replaced (addressing iBabs limitation -- source #372) + +--- + +### Requirement: Agenda Data Export and Interoperability [MVP] + +The system MUST export agendas in standardized formats. + +#### Scenario: Export agenda as OpenRaadsinformatie AgendaPunt + +- GIVEN a finalized council meeting agenda +- WHEN the system exports the agenda +- THEN each agenda item MUST conform to the OpenRaadsinformatie `AgendaPunt` schema +- AND linked documents, decisions, and motions MUST be included + +#### Scenario: Export agenda as iCalendar with item times + +- GIVEN a meeting agenda with timed items +- WHEN exported as iCalendar +- THEN each agenda item MUST appear as a sub-event with start/end times +- AND the export MUST be importable into calendar applications + +--- + +### Requirement: Configurable Meeting Types with Default Agenda Items [MVP] + +Meeting types MUST be configurable seed data objects, NOT hardcoded enums. Each meeting type defines default agenda items that are automatically populated when creating a new meeting of that type. Admins MUST be able to create, modify, and delete meeting types. + +#### Scenario: Create meeting from type with default items + +- GIVEN a meeting type "Raadsvergadering" configured with default items [Opening, Vaststellen agenda, Vaststellen notulen vorige vergadering, Ingekomen stukken, ..., Rondvraag, Sluiting] +- WHEN a user creates a new meeting of type "Raadsvergadering" +- THEN the agenda MUST be pre-populated with all default items in the configured order +- AND the user MUST be able to add, remove, or reorder items before publishing +- AND each default item MUST have its type (informational/discussion/decision) pre-set + +#### Scenario: Seed application with standard meeting types + +- GIVEN a fresh Decidesk installation +- WHEN the repair step runs +- THEN the system MUST seed the following meeting types: Raadsvergadering (council), Commissievergadering (committee), ALV (general assembly), Bestuursvergadering (board meeting), MT-vergadering (management team), AVA/Aandeelhoudersvergadering (shareholder meeting), Burgerberaad (citizens' assembly) +- AND each MUST include domain-appropriate default agenda items, quorum rules, and voting methods + +#### Scenario: Admin creates a custom meeting type + +- GIVEN an admin of a sports association +- WHEN they create a meeting type "Jaarvergadering" with default items [Opening, Notulen vorige jaarvergadering, Jaarverslag, Financieel verslag, Verslag kascommissie, Bestuursverkiezing, Begroting, Rondvraag, Sluiting] +- THEN this meeting type MUST be available when creating new meetings +- AND the quorum and voting rules MUST be configurable per type + +--- + +### Requirement: Agenda Item Indiener and Proposal Status Tracking [MVP] + +Every agenda item MUST track its indiener (submitter). The indiener MUST be able to see the status of their submitted proposals across all meetings. The system MUST provide a "My Proposals" view. + +#### Scenario: Track proposal status from submission to decision + +- GIVEN a council member who submitted a motion "Amendement klimaatbegroting" +- WHEN they open their "My Proposals" view +- THEN they MUST see the proposal with its current status (submitted → under review → on agenda → debated → voted → approved/rejected) +- AND they MUST see which meeting it is scheduled for +- AND they MUST see the agenda item position and estimated time + +#### Scenario: Indiener receives notifications on status changes + +- GIVEN a board member who submitted a proposal for the next meeting +- WHEN the chair accepts the proposal and places it on the agenda +- THEN the indiener MUST receive a notification "Your proposal 'X' has been placed on the agenda for meeting Y, item Z" +- AND when the item is discussed during the meeting, they MUST be notified +- AND when a vote is taken, they MUST see the result + +--- + +### Requirement: Agenda Item Decision Points [MVP] + +An agenda item MUST be linkable to a decision point (Motion, Amendment, or Vote). When the meeting progresses to an item with a decision point, the voting interface MUST activate automatically. + +#### Scenario: Agenda item linked to a motion vote + +- GIVEN an agenda item "Stemming over motie verkeersplan" +- WHEN the item is linked to Motion #42 as its decision point +- THEN when the chair activates this agenda item during the meeting, the voting interface MUST appear with Motion #42's text +- AND participants MUST be able to cast their vote directly + +#### Scenario: Multiple decision points per agenda item + +- GIVEN an agenda item "Behandeling begroting 2027" with 3 amendments and the main motion +- WHEN the chair activates this item +- THEN the system MUST present amendments in the correct voting order (most radical first, or LIFO) +- AND after all amendments are voted on, the (possibly amended) main motion MUST be put to vote + +--- + +### Requirement: Speaker Registration for Agenda Items [MVP] + +Participants MUST be able to register as speakers for specific agenda items before and during the meeting. The chair manages the speakers list and speaking order. + +#### Scenario: Pre-register as speaker + +- GIVEN a published meeting agenda with item "Bestemmingsplan Westpark" +- WHEN a council member registers to speak on this item before the meeting +- THEN they MUST appear on the speakers list for that item +- AND the chair MUST see all registered speakers when the item is activated + +#### Scenario: Register during meeting + +- GIVEN an active agenda item during a meeting +- WHEN a participant presses "Request to speak" +- THEN they MUST be added to the speakers queue +- AND the chair MUST see the updated queue in real-time +- AND speaking time MUST be tracked per speaker from the moment the chair grants the floor + +--- + +### Requirement: Dynamic Time Tracking Per Agenda Item [MVP] + +Agenda item duration MUST be calculated dynamically based on start times, not stored as a fixed allocation. The system MUST track actual time spent per item during meetings. + +#### Scenario: Calculate duration from start times + +- GIVEN agenda item 3 starts at 20:15 and item 4 starts at 20:45 +- THEN item 3's allocated duration MUST display as 30 minutes +- AND the last item's duration MUST be calculated as meeting.endTime minus item.startTime + +#### Scenario: Track actual time during meeting + +- GIVEN agenda item 3 is active during a meeting +- WHEN the chair moves to item 4 at 20:52 (7 minutes over the planned 20:45) +- THEN item 3's actual duration MUST be recorded as 37 minutes (20:15 to 20:52) +- AND item 4's start time MUST update to 20:52 +- AND the remaining items MUST show updated estimated times +- AND the meeting dashboard MUST show "running 7 minutes over schedule" + +--- + +### Requirement: Live Meeting Page for Participants [MVP] + +The system MUST provide a real-time meeting page where participants can see: the current agenda item, all meeting documents, the speakers queue, active votes, and the timer. This page MUST update in real-time without manual refresh. + +#### Scenario: Participant views live meeting + +- GIVEN a meeting is in progress with item 5 "Behandeling motie parkeerbeleid" active +- WHEN a participant opens the live meeting page +- THEN they MUST see: the current item title and description, the attached documents, the speakers queue with current speaker highlighted, the item timer showing elapsed time, any active vote with the ability to cast their ballot, and the full agenda with current position indicated + +#### Scenario: Remote participant follows along + +- GIVEN a hybrid meeting where some participants attend remotely +- WHEN the chair advances to the next agenda item +- THEN all remote participants' screens MUST update in real-time +- AND documents for the new item MUST be immediately accessible +- AND if the item has a decision point, the voting interface MUST appear + +#### Scenario: Meeting page shows proposal status inline + +- GIVEN a participant who submitted a proposal now on the agenda +- WHEN they view the live meeting page +- THEN their proposal MUST be highlighted/marked as "yours" +- AND they MUST see real-time status updates as the chair processes it + +--- + +### Requirement: Calendar Integration for Meetings [MVP] + +Meetings MUST be integrated with Nextcloud Calendar via OpenRegister's CalDAV provider. Meeting creation MUST optionally create a calendar event, and calendar events MUST link back to the meeting in Decidesk. + +#### Scenario: Meeting creates calendar event + +- GIVEN a user creates a new meeting "Bestuursvergadering 15 april" with date, time, and location +- WHEN they check "Add to calendar" +- THEN a CalDAV event MUST be created in the organization's shared calendar +- AND the event MUST include a link back to the Decidesk meeting page +- AND invited participants MUST receive calendar invitations + +#### Scenario: Recurring meeting series + +- GIVEN a meeting type "MT-vergadering" configured as bi-weekly on Tuesday 10:00-12:00 +- WHEN the admin sets up a recurring series +- THEN CalDAV RRULE events MUST be created for the series +- AND each occurrence MUST auto-create a Decidesk meeting with default agenda items from the meeting type + +--- -5. **Management assistant compiling agenda package**: As a management assistant, I want to compile submitted agenda items into a structured agenda and distribute the complete package to all MT members, so that everyone is prepared for the meeting. (Source: intelligence DB #88) +## User Stories (from intelligence database) + +### Legislative Domain + +1. As a griffier, I want to create a meeting agenda by selecting and ordering proposals from the backlog so that council members and the public can see what will be discussed. (DB #136) +2. As a griffier, I want to set deadlines for document submission per agenda item so that all required documents are available before publication. (DB #137) +3. As a griffier, I want to publish the complete agenda with all accompanying documents in one action. (DB #138) +4. As a raadslid, I want to highlight text and add notes to meeting documents on my tablet so that I can prepare for debate. (DB #140) +5. As a raadslid, I want to link my motion to a specific agenda item so that it is automatically included in the debate. (DB #147) +6. As a voorzitter, I want to classify agenda items as hamerstuk or bespreekstuk so that meeting time is used efficiently. (DB #158) +7. As a commissievoorzitter, I want to manage the speaking order for committee members and insprekers. (DB #159) +8. As a burger, I want to register online to speak at a committee meeting about an agenda item that affects me. (DB #160) +9. As a commissievoorzitter, I want to formally record the committee advice on whether an item is ready for plenary decision. (DB #162) +10. As a voorzitter, I want to process all hamerstukken in one batch without debate. (DB #164) +11. As a commissiegriffier, I want minutes to be automatically structured by agenda item. (DB #174) +12. As a fractievoorzitter, I want to record the agreed faction position on each agenda item. (DB #153) +13. As a burger, I want to set up keyword-based alerts for council agenda items so I am notified when topics that affect me are being discussed. (DB #208) + +### Association Domain + +14. As a chair, I want to compose the ALV agenda ensuring all legally required items are included so that the meeting is legally valid. (DB #49) +15. As a treasurer, I want to upload the financial statements and budget proposal to the ALV agenda so that members can review them before the meeting. (DB #50) +16. As a member, I want to receive the ALV invitation with the complete agenda and supporting documents so that I can prepare. (DB #47) +17. As a member, I want to submit a motion or proposal for the ALV agenda with supporting arguments. (DB #54) +18. As a secretary, I want to prepare a digital meeting package with agenda, previous minutes, action items, and new documents. (DB #65) +19. As a board member, I want to declare a conflict of interest for a specific agenda item so I am properly excluded per WBTR. (DB #69) +20. As a ledenraad member, I want to review the agenda and consult my constituency before the council meeting. (DB #82) +21. As a secretary, I want recurring meeting series where each occurrence automatically gets a new agenda. (DB #1827) + +### Corporate Governance Domain + +22. As a board secretary, I want to create and manage the AGM agenda with drag-and-drop resolution ordering within statutory deadlines. (DB #1) +23. As a shareholder, I want to access all AGM documents (agenda, annual report, resolution proposals) through a secure online portal. (DB #3) +24. As a proxy advisor, I want to receive standardized AGM agenda and resolution data digitally for analysis. (DB #6) +25. As a notary, I want secure access to the meeting agenda, attendee list, and voting results. (DB #12) + +### Corporate Operations Domain + +26. As an MT member, I want to submit agenda items with supporting documents through a structured form. (DB #87) +27. As a management assistant, I want to compile submitted agenda items into a structured agenda and distribute the complete package. (DB #88) +28. As a CEO, I want to review major budget requests on the MT agenda with financial controller assessment. (DB #99) +29. As a meeting facilitator, I want visible countdown timers per agenda item with configurable time allocations. (DB #334) +30. As a director, I want a periodic meeting audit report showing which meetings have agendas and achieve their goals. (DB #333) +31. As a council secretary, I want to tag each meeting or agenda item with its BOB phase and track progress across meetings. (DB #341) + +### Citizen Participation Domain + +32. As a coordinator, I want to plan and manage the assembly meeting schedule including information sessions and deliberation rounds. (DB #223) +33. As a neighbourhood council member, I want residents to submit agenda items digitally so our meetings address what the neighbourhood cares about. (DB #247) +34. As a hearing secretary, I want to schedule speakers with time slots and topics so that the hearing runs efficiently. (DB #238) + +### Cross-Domain (Nextcloud Integration) + +35. As a member, I want each major agenda item to have a linked Talk conversation for informal deliberation. (DB #1851, #1852, #1853) +36. As any user, I want to search for agenda items and related documents from the Nextcloud unified search bar. (DB #1873) + +## Evidence Sources + +### Legal Standards (Mandatory) + +| Standard | Scope | Key Requirements | +|----------|-------|-----------------| +| **Woo** | Public transparency | Art. 3.3: active publication of agendas of councils, B&W, and public bodies | +| **Gemeentewet** | Municipal councils | Reglement van Orde defines agenda structure, speaking rules (max 5 min, max 2 terms) | +| **BW Boek 2** | Legal entities | Art. 2:38: ALV agenda requirements; Art. 2:225: AGM agenda notice | +| **Digitoegankelijk** | Accessibility | Published agendas must comply with EN 301 549 / WCAG 2.1 | + +### Forum Standaardisatie Standards (Recommended) + +| Standard | Relevance | +|----------|-----------| +| **PDF/UA** | Accessible agenda document publication | +| **ODF** | Editable agenda document format | +| **Akoma Ntoso** | XML representation of parliamentary agenda items | + +### External Research & Market Evidence + +- **67% of professionals say clear agenda is most important meeting element** (source #320) +- **Only 37% of meetings use agendas** -- massive compliance/quality gap (source #319) +- **Agenda adherence is a key KPI** tracked by leading meeting analytics platforms (source #323) +- **158 stories reference scheduling, deadlines, or agenda items** -- Calendar integration is high-value (insight #26) +- **iBabs**: users praise ease of use, but replacing documents loses annotations (source #372) -- we should do better +- **OnBoard**: easy agenda building, centralized docs, e-signatures (source #462) +- **Sherpany**: 45% productivity boost through structured meeting lifecycle including agenda management (source #108) +- **Lucid Meetings**: in-meeting timers, sub-topic support, decision tracking for process-driven meetings (source #327) +- **Flowtrace**: agenda compliance tracking as core metric across 2.2M+ meetings (source #322) + +### Competitor Agenda Features + +| Competitor | Agenda Features | Gap | +|-----------|----------------|-----| +| **Notubiz** | Agenda publication for council meetings | Poor search, documents barely findable (source #361) | +| **iBabs** | Board agenda building | Annotations lost on document replacement | +| **OnBoard** | Easy agenda building, centralized docs | Font customization limited, all-or-nothing downloads | +| **Fellow** | Collaborative agendas, AI note-taking | No formal governance compliance | +| **Sherpany** | End-to-end meeting lifecycle | Corporate boards only | +| **Lucid Meetings** | In-meeting timers, sub-topics | No legislative/association support | +| **Decisions (Teams)** | AI-driven agenda management | Microsoft ecosystem only | +| **Confluence** | Meeting templates, decision macros | No real-time agenda tracking | + +### Tender Requirements + +- **W-BESL** (70 pts): "Beschrijf ondersteuning bestuurlijk besluitvormingsproces inclusief agendabeheer" +- **W9** (68 pts): Agenda management as part of full BBV process +- **W11** (48 pts): "iBabs voor agendabeheer" -- municipalities expect agenda management integration +- **W13** (56 pts): "inclusief agendabeheer, vergaderbehandeling, publicatie" +- **W2-22** (5 pts): "Automatisch een welstandsagenda genereren uit de applicatie" + +## Customer Journeys + +### Legislative Domain +- **Agenda Preparation & Setting** -- Griffier creates meeting agenda from proposal backlog +- **Document Package Review & Preparation** -- Council members review documents, prepare notes +- **Presidium Agenda Setting** -- Faction leaders classify items, set meeting planning +- **Council Proposal Preparation** -- Civil servants draft proposals for agenda inclusion +- **Faction Position Coordination** -- Faction leaders coordinate voting positions per agenda item +- **Live Meeting Following & Webcasting** -- Citizens track which agenda item is being discussed +- **Meeting Recording Publication** -- Video indexed by agenda item +- **Document & Decision Search** -- Searching across agendas, minutes, decisions +- **Active Disclosure (Actieve Openbaarmaking)** -- Woo Art. 3.3 mandatory publication +- **Submit a citizen initiative (Burgerinitiatief)** -- Formal placement on council agenda + +### Association Domain +- **ALV Convocation & Scheduling** -- Agenda distribution with convocation +- **ALV Agenda & Document Preparation** -- Board prepares ALV agenda with all documents +- **Member Proposal / Motion Submission** -- Members submit proposals for agenda +- **Financial Statements & Budget Preparation** -- Treasurer prepares items for ALV agenda +- **Annual Report Preparation** -- Board prepares annual report as ALV agenda item +- **Board Meeting Preparation** -- Secretary drafts agenda with chair +- **Meeting Minutes Preparation & Approval** -- Minutes structured by agenda item +- **Smart Agenda & Meeting Scheduling** -- Templates and calendar integration + +### Corporate Governance Domain +- **AGM Convocation & Agenda Setting** -- End-to-end AGM agenda and convocation process +- **Shareholder Agenda Item Request** -- 3% (NV) / 1% (BV) threshold for agenda items +- **Board Pack Preparation & Distribution** -- Structured, indexed document package +- **Smart Agenda & Meeting Scheduling** -- Templates and calendar integration + +### Corporate Operations Domain +- **MT Agenda Preparation** -- Collect items, compile package, distribute +- **MT Decision Making During Meeting** -- Discussing agenda items, forming positions +- **Meeting Efficiency & Analytics** -- Agenda adherence as KPI +- **Smart Agenda & Meeting Scheduling** -- Templates and calendar integration + +### Citizen Participation Domain +- **Run neighbourhood council meeting cycle** -- Collect agenda items from residents +- **Submit a citizen initiative** -- Agenda placement via burgerinitiatief ## Acceptance Criteria -- Agenda items are stored as OpenRegister objects with sequential ordering -- Drag-and-drop reordering persists immediately with automatic order number recalculation -- Legally required items are enforced per meeting type with warnings for missing items -- Time allocation is tracked per item with over-time warnings -- Meeting document packages can be assembled from agenda attachments -- Sub-items are supported for hierarchical agenda structure -- OpenRaadsinformatie `AgendaPunt` mapping is available +1. Agenda items are stored as OpenRegister objects with sequential ordering +2. Drag-and-drop reordering persists immediately with automatic order number recalculation +3. Legally required items are enforced per meeting type with warnings for missing items +4. ALV required items: opening, approval of previous minutes, annual report, financial statements, kascommissie report, board elections, AOB, closing +5. Agenda templates pre-populate required items and can be customized per body +6. Time allocation is tracked per item with real-time countdown timers during meetings +7. Over-time warnings fire with audio/visual alerts +8. Total agenda duration is calculated and compared against meeting schedule +9. Meeting document packages can be assembled from agenda attachments with table of contents +10. Document packages are publishable in one action with Woo-compliant timestamps +11. Member proposal workflow supports submission, review, acceptance/rejection +12. Shareholder agenda requests track identity and share percentage +13. Sub-items are supported for hierarchical agenda structure +14. Items can be classified as hamerstuk/bespreekstuk with batch processing +15. Hamerstukken can be adopted as a batch with individual decision records +16. Motions and amendments can be linked to specific agenda items +17. Speaking order is managed per agenda item with configurable time limits +18. Citizen speaking registration (inspreekrecht) is supported for committee meetings +19. Real-time current agenda item indicator is visible to all participants +20. Agenda items can be tagged with BOB phase (Beeldvorming/Oordeelsvorming/Besluitvorming) +21. Document submission deadlines can be set per agenda item with notifications +22. Unfinished agenda items can be carried over to the next meeting +23. Document annotations are preserved across document replacements +24. Published agendas comply with Digitoegankelijk (WCAG 2.1) +25. OpenRaadsinformatie `AgendaPunt` mapping is available for each agenda item +26. Agenda items and documents are searchable from Nextcloud unified search +27. Talk conversations can be auto-created per agenda item for informal deliberation +28. Agenda adherence metrics feed into the meeting efficiency dashboard + +## Notes + +### Open Questions + +- Should the system enforce a maximum number of agenda items per meeting to prevent overloading? Research suggests meetings with 5-7 items are most effective. +- How to handle confidential agenda items in public agendas? Woo requires transparency but allows exceptions for specific categories. +- Should we support "consent-based agenda setting" (sociocratic practice) in addition to chair-driven agenda setting? + +### Legal Risks + +- Woo requires active publication of agendas -- the system must ensure publication timestamps are recorded and documents are accessible. +- Missing required ALV agenda items could invalidate the meeting and all decisions taken -- the warning system must be prominent and non-dismissable. +- Shareholder agenda requests have specific legal thresholds (3% NV, 1% BV) -- incorrect validation could expose the organization to legal challenges. + +### Technical Decisions + +- Use OpenRegister _calendar metadata to sync agenda items as calendar sub-events +- Use OpenRegister _talk metadata for auto-creating Talk conversations per agenda item +- Drag-and-drop implemented with Vue.js sortable library, persisted via immediate API call +- Real-time agenda tracking uses WebSocket or Nextcloud Push for live updates +- Document package assembly uses Nextcloud Files API for document aggregation +- Annotations stored per-user in OpenRegister with document version tracking to survive replacements diff --git a/openspec/specs/dashboard/spec.md b/openspec/specs/dashboard/spec.md index 6c70b9e..e4937db 100644 --- a/openspec/specs/dashboard/spec.md +++ b/openspec/specs/dashboard/spec.md @@ -11,6 +11,58 @@ The Decidesk dashboard provides an at-a-glance overview of active decisions, upc **Standards**: Schema.org (`Dashboard` pattern), Nextcloud Dashboard Widget API **Feature tier**: MVP +## Evidence Base + +### Market Research + +| Statistic | Source | +|-----------|--------| +| $541 billion wasted on pointless meetings globally per year | Intelligence DB insight #1 (Doodle) | +| 44% of action items never completed after meetings | External source #342 (Count.co) | +| 78% of workers say they attend too many meetings | External source #319 (Fellow) | +| Only 45% of boards deemed effective (Gartner benchmark) | External source #172 (Gartner Peer Insights) | +| AI meeting tool usage grew 17x in 2024 | Intelligence DB insight #5 | +| 438 user stories reference participants/members/stakeholders -- largest integration category | Intelligence DB insight #29 | +| 158 user stories reference scheduling, deadlines, or agenda items | Intelligence DB insight #26 | +| 213 user stories reference tasks and action items | Intelligence DB insight #26 | + +### KPI Benchmarks + +The following benchmarks from Flowtrace (2.2M meetings analyzed, external source #322) and Worklytics (external source #347) inform the KPI cards and analytics: + +| KPI | Benchmark | Source | +|-----|-----------|--------| +| Meetings per week per person | 8-12 (knowledge workers) | Worklytics #347 | +| Average meeting duration | 45-60 min | Flowtrace #322 | +| Decision rate | 2-3 decisions per meeting | Flowtrace #323 | +| Action item completion rate | >90% target (EOS), 56% actual average | Count.co #342 | +| Meeting cost per employee/year | $25K average | MeetingKing #325 | +| Focus time ratio | >50% of workday without meetings | Worklytics #347 | +| Agenda compliance | 37% average (low!) | Fellow #319 | +| Attendance rate | >80% target | Flowtrace #323 | + +### Dashboard Design References + +| Source | Key Pattern | Evidence | +|--------|-------------|----------| +| Flowtrace Meeting Analytics Dashboard | Executive tiles, team investment view, meeting audit, trend visualization | External source #349 | +| Worklytics Manager Scorecard | 12 highest-impact KPIs with benchmarks, focus time ratio | External source #347 | +| iBabs Board Portal | Quorum tracking, RSVP, next meeting, pending actions | External source #97 | +| BoardPro Decision Register | Automated decision register, searchable by keyword/date | External source #114 | +| Dimpact ZAC Dashboard | Customizable drag-and-drop dashboard with signaling cards | Competitor feature analysis | +| EspoCRM Dashboard | Draggable dashlets, pipeline reports, stream/activity feed | Competitor feature analysis | + +### Competitor Analysis + +| Competitor | Dashboard Features | Gap | +|------------|-------------------|-----| +| Diligent Boards | Board book summarization, action tracking, compliance | No meeting cost KPIs, $48K-$155K/year | +| iBabs | Next meeting, pending actions, document status | No analytics, no cost tracking, no KPI benchmarks | +| Fellow.app | Action items, meeting notes, AI summaries | No governance-specific KPIs, no voting | +| Flowtrace | Meeting cost, team comparison, trend visualization | SaaS-only, no governance, no decision tracking | +| BoardPro | Decision register, action items, meeting calendar | No cost analytics, no personal scorecard | +| Dimpact ZAC | Signaling cards, configurable worklists | Case management focused, not governance | + ## Requirements --- @@ -26,7 +78,7 @@ The dashboard MUST use the `CnDashboardPage` component to render a configurable - GIVEN the user has not customized their dashboard layout - WHEN the user navigates to the dashboard - THEN the layout MUST render with the default configuration: - - Row 1: Four KPI cards (3 columns each) — Active Decisions, Upcoming Meetings, Pending Votes, Overdue Actions + - Row 1: Four KPI cards (3 columns each) -- Active Decisions, Upcoming Meetings, Pending Votes, Overdue Actions - Row 2: "My Pending Votes" widget (6 columns) and "Upcoming Meetings" widget (6 columns) - Row 3: "Recent Decisions" widget spanning full width (12 columns) - AND each widget MUST be rendered inside a `CnDashboardPage` widget slot @@ -38,13 +90,21 @@ The dashboard MUST use the `CnDashboardPage` component to render a configurable - THEN a welcome message MUST be displayed: "Welcome to Decidesk! Get started by setting up your first governing body in Settings." - AND quick action buttons MUST be shown: "Set Up Body", "Create Meeting", "Create Decision" +#### Scenario: Role-based dashboard variants + +- GIVEN a user with the "chair" role in one body and "member" role in another +- WHEN they view the dashboard +- THEN widgets MUST aggregate data across all bodies the user belongs to +- AND role-specific actions MUST be contextual (e.g., chair sees "Start Meeting", member sees "Join Meeting") + --- ### Requirement: KPI Cards -The dashboard MUST display KPI summary cards showing headline governance metrics using `CnStatsBlock` components. +The dashboard MUST display KPI summary cards showing headline governance metrics using `CnStatsBlock` components. KPI values MUST be backed by benchmark data from external research. **Feature tier**: MVP +**Evidence**: 15 essential meeting KPIs identified by Flowtrace (external source #323). 12 highest-impact manager KPIs with benchmarks by Worklytics (external source #347). #### Scenario: Display active decisions count @@ -52,11 +112,12 @@ The dashboard MUST display KPI summary cards showing headline governance metrics - THEN the "Active Decisions" KPI card MUST display the count of decisions with status not in (`enacted`, `archived`, `rejected`) - AND clicking the card MUST navigate to the Decisions view filtered by active status -#### Scenario: Display pending votes count +#### Scenario: Display pending votes count with urgency - WHEN the user views the dashboard - THEN the "Pending Votes" KPI card MUST display the count of decisions currently in `voting` status where the user has not yet cast their vote - AND if the count is greater than 0, the card MUST use `variant="warning"` (orange accent) +- AND if any vote has less than 24 hours remaining, the card MUST use `variant="error"` (red accent) - AND clicking the card MUST navigate to the user's pending votes #### Scenario: Display overdue action items count @@ -65,6 +126,14 @@ The dashboard MUST display KPI summary cards showing headline governance metrics - THEN the "Overdue Actions" KPI card MUST display the count of action items past their deadline - AND if overdue count is greater than 0, the card MUST use `variant="error"` (red accent) - AND clicking the card MUST navigate to the action items view filtered by overdue +- AND the card MUST show the completion rate percentage alongside the count (benchmark: >90% target per EOS Level 10) + +#### Scenario: Display upcoming meetings count + +- WHEN the user views the dashboard +- THEN the "Upcoming Meetings" KPI card MUST display the count of meetings within the next 7 days +- AND if a meeting is within 24 hours, the card MUST show the next meeting time +- AND clicking the card MUST navigate to the meetings calendar view --- @@ -73,6 +142,7 @@ The dashboard MUST display KPI summary cards showing headline governance metrics The dashboard MUST include a widget showing decisions awaiting the current user's vote, ordered by urgency (voting deadline). **Feature tier**: MVP +**Evidence**: Institutional investor story #5 shows need for centralized vote management. Pending vote urgency is critical for governance compliance deadlines. #### Scenario: Show pending votes with urgency indicators @@ -80,6 +150,7 @@ The dashboard MUST include a widget showing decisions awaiting the current user' - WHEN the dashboard loads - THEN the "My Pending Votes" widget MUST list each decision with title, body, and time remaining - AND decisions with less than 24 hours remaining MUST show a red urgency indicator +- AND decisions with less than 48 hours remaining MUST show an orange urgency indicator - AND clicking a decision MUST navigate to the voting interface #### Scenario: No pending votes @@ -88,13 +159,22 @@ The dashboard MUST include a widget showing decisions awaiting the current user' - WHEN the dashboard loads - THEN the widget MUST show "No pending votes" with a check mark icon +#### Scenario: Quick vote from dashboard + +- GIVEN a simple yes/no vote pending +- WHEN the user clicks the quick-vote action on a decision card +- THEN a vote confirmation dialog MUST appear +- AND the user MUST be able to cast their vote without leaving the dashboard +- AND the KPI card MUST update immediately after voting + --- ### Requirement: Upcoming Meetings Widget -The dashboard MUST include a widget showing the user's upcoming meetings across all bodies, ordered by date. +The dashboard MUST include a widget showing the user's upcoming meetings across all bodies, ordered by date. The widget MUST provide a calendar strip view for the current week. **Feature tier**: MVP +**Evidence**: 158 user stories reference scheduling and agenda items (insight #26). Calendar integration is the second-highest-value Nextcloud integration. #### Scenario: Show upcoming meetings with context @@ -104,6 +184,141 @@ The dashboard MUST include a widget showing the user's upcoming meetings across - AND meetings within the next 24 hours MUST be highlighted - AND clicking a meeting MUST navigate to the meeting detail view +#### Scenario: Calendar strip for the current week + +- GIVEN the current week has 3 meetings +- WHEN the dashboard loads +- THEN a horizontal calendar strip MUST show days of the current week +- AND days with meetings MUST show dot indicators with the count +- AND clicking a day MUST show meeting details for that day + +#### Scenario: Meeting preparation status + +- GIVEN a meeting in 2 days with a meeting package +- WHEN the user views the upcoming meetings widget +- THEN each meeting MUST show preparation status (documents read/total) +- AND meetings where documents have not been read MUST show a reminder indicator + +--- + +### Requirement: Decision Board (Kanban) + +The dashboard MUST include an optional kanban-style decision board that groups decisions by their current state within their process template. + +**Feature tier**: V1 +**Evidence**: EspoCRM and Dimpact ZAC both provide kanban views for status-based entity management. BottleCRM uses Pipeline->Stage->Entity pattern with drag-drop (competitor analysis). 300 user stories match workflow/pipeline patterns (insight #32). + +#### Scenario: View decisions as kanban board + +- GIVEN the user selects the "Decision Board" view +- WHEN the board loads +- THEN decisions MUST be grouped into columns by their current state (e.g., Draft, Proposed, Debating, Voting, Adopted) +- AND each card MUST show decision title, body, and days in current state +- AND cards MUST be color-coded by urgency or body + +#### Scenario: Filter board by governing body + +- GIVEN the user is a member of 3 bodies +- WHEN they select a specific body filter +- THEN only decisions from that body MUST be shown +- AND the columns MUST reflect the process template states for that body + +#### Scenario: Drag-and-drop state transitions (chair/secretary only) + +- GIVEN a user with chair or secretary role +- WHEN they drag a decision card from "Debating" to "Voting" +- THEN the system MUST validate the transition against the process template guards +- AND if valid, the state transition MUST be executed with audit trail +- AND if invalid (e.g., quorum not met), an error MUST be displayed explaining why + +--- + +### Requirement: My Work Section + +The dashboard MUST include a "My Work" section showing the user's personal pending items across all governance activities. + +**Feature tier**: MVP + +#### Scenario: Show personal pending items + +- GIVEN a user with various pending governance items +- WHEN they view the "My Work" section +- THEN the following MUST be shown in a unified list: + - Pending votes (with deadline) + - Action items assigned to them (with due date and status) + - Documents requiring their review + - Meetings requiring their preparation +- AND items MUST be sorted by urgency (deadline) +- AND each item MUST show the governing body context + +#### Scenario: Mark items as complete + +- GIVEN an action item in the "My Work" section +- WHEN the user clicks "Mark Complete" +- THEN the action item status MUST update to "completed" +- AND the item MUST move to a "Recently Completed" section (visible for 24 hours) +- AND the completion rate KPI MUST update + +--- + +### Requirement: Organization-Wide Decision Overview + +The dashboard MUST provide an organization-wide view of all decisions for users with administrative or oversight roles. + +**Feature tier**: V1 +**Evidence**: Council member story #179 needs dashboard of all adopted motions. Story #203 needs dashboard of executive commitments. Story #290 needs compliance dashboard. + +#### Scenario: View all decisions across bodies + +- GIVEN an administrator or compliance officer +- WHEN they view the organization-wide overview +- THEN all decisions across all bodies MUST be shown +- AND decisions MUST be filterable by body, status, date range, and type +- AND a summary bar MUST show total active, adopted this quarter, and overdue + +#### Scenario: Monitor executive commitments (toezeggingen) + +- GIVEN a council member viewing the oversight dashboard +- WHEN they filter by "commitments" +- THEN all open commitments from the executive MUST be listed with deadlines and status (user story #203) +- AND overdue commitments MUST be highlighted +- AND a compliance rate MUST be calculated + +#### Scenario: View motion follow-up status + +- GIVEN adopted motions from council meetings +- WHEN the user views the motion status dashboard +- THEN each adopted motion MUST show its current implementation status (user story #179) +- AND the responsible executive member MUST be shown +- AND a timeline of status updates MUST be available + +--- + +### Requirement: Meeting Efficiency Analytics Widget + +The dashboard MUST include an analytics widget showing key meeting efficiency metrics for the user's governance bodies. + +**Feature tier**: V1 +**Evidence**: $541B wasted globally (insight #1). 15 KPIs from Flowtrace (external source #323). 12 manager KPIs from Worklytics (external source #347). + +#### Scenario: Display efficiency metrics + +- GIVEN the user has meeting history data +- WHEN the analytics widget loads +- THEN the following metrics MUST be displayed: + - Average meeting duration (trend over last 6 months) + - Decision throughput (decisions per meeting, trend) + - Action item completion rate (vs. 90% target) + - Meeting cost trend (total and per-meeting) +- AND each metric MUST show a trend indicator (improving/declining/stable) + +#### Scenario: Compare bodies + +- GIVEN the user is a member of 3 bodies +- WHEN they view the comparative analytics +- THEN efficiency metrics MUST be shown side-by-side for each body +- AND the best-performing body MUST be highlighted as a benchmark + --- ### Requirement: Nextcloud Dashboard Widget Integration @@ -116,23 +331,120 @@ The system MUST register a Nextcloud Dashboard widget via `OCP\Dashboard\IWidget - GIVEN a user with Decidesk access - WHEN they view the Nextcloud main dashboard -- THEN a "Decidesk" widget MUST be available showing pending votes count and next meeting +- THEN a "Decidesk" widget MUST be available showing: + - Pending votes count (with urgency indicator) + - Next meeting (title, time, body) + - Overdue action items count - AND clicking the widget MUST navigate to the Decidesk dashboard +#### Scenario: Widget data refresh + +- GIVEN the Decidesk widget is displayed on the Nextcloud dashboard +- WHEN the user receives a new pending vote +- THEN the widget MUST update without requiring a page refresh (if Nextcloud push is available) +- AND the count MUST increment and show the new vote's title + +--- + +### Requirement: Quick Actions + +The dashboard MUST provide quick action buttons for common governance tasks, accessible from the dashboard header. + +**Feature tier**: MVP + +#### Scenario: Create new meeting from dashboard + +- GIVEN a user with secretary or chair role +- WHEN they click the "New Meeting" quick action +- THEN a meeting creation form MUST open with the user's default body pre-selected +- AND the form MUST include agenda template options + +#### Scenario: Create new decision from dashboard + +- GIVEN a user with permission to create decisions +- WHEN they click the "New Decision" quick action +- THEN a decision creation form MUST open +- AND the form MUST offer process template selection based on the selected body + +#### Scenario: Start ad-hoc vote from dashboard + +- GIVEN a chair viewing the dashboard +- WHEN they click "Start Vote" +- THEN a quick-vote creation form MUST open for simple yes/no decisions +- AND the form MUST auto-populate quorum requirements from the body's process template + ## User Stories -1. **New board member accessing knowledge base**: As a new board member, I want to access all historical decisions, current action items, financial status, and governance documents so that I can quickly become effective in my role. (Source: intelligence DB #84) +### High-Priority Stories (from Intelligence DB) + +1. **New board member accessing knowledge base** (DB #84, priority: high): As a new board member, I want to access all historical decisions, current action items, financial status, and governance documents so that I can quickly become effective in my role. *AC: Complete decision archive, current open items, latest financial status, key contacts.* + +2. **Institutional investor managing proxy voting** (DB #5, priority: should): As an institutional investor, I want to manage proxy voting across all portfolio company AGMs from a single dashboard, so that I can efficiently exercise my voting rights at scale. *AC: All upcoming AGMs with deadlines, bulk voting, SRD II compliance.* + +3. **CEO viewing meeting cost dashboard** (DB #330, priority: must): As a CEO/director, I want a real-time dashboard showing organizational meeting costs, trends, and cost per department. *AC: Total cost per period, department breakdown, trend lines, benchmarks.* + +4. **Manager tracking personal meeting KPIs** (DB #331, priority: must): As a manager, I want a personal meeting scorecard showing my KPIs so I can optimize meeting behavior. *AC: Meetings/week, duration, decision rate, completion rate, focus time ratio.* + +5. **Council member viewing motion dashboard** (DB #179, priority: should): As a raadslid, I want a dashboard showing all adopted motions with their current status, so I can hold the executive accountable. + +6. **Council member monitoring executive commitments** (DB #203, priority: should): As a raadslid, I want a dashboard showing all open commitments from the executive with deadlines and status. + +7. **Alderman reviewing participation results** (DB #255, priority: high): As an alderman, I want a dashboard showing all active and completed participation processes with key results so I can prioritize responses. *AC: Status, participation numbers, key themes, response deadline.* + +8. **Financial controller monitoring budget utilization** (DB #101, priority: medium): As a financial controller, I want a dashboard of all approved budget decisions with actual spend tracking. *AC: Approved vs actual, variance alerts, drill-down.* + +9. **Administrator publishing meeting decisions** (DB #76, priority: medium): As administrator, I want to publish key decisions from ALV and board meetings on the member portal so that all members stay informed. + +10. **CFO viewing risk management dashboard** (DB #21, priority: should): As a CFO, I want a real-time risk dashboard showing enterprise risks, control effectiveness, and compliance status. *AC: Risk heat map, control testing status, trend analysis, drill-down.* + +### Capability Stories (from external source clustering) + +11. **KPI dashboard** (DB #1212): As an organizational leader, I want to use a KPI dashboard for meeting effectiveness measurement. + +12. **Manager dashboard** (DB #1207): As an organizational leader, I want to use a manager dashboard for meeting effectiveness. + +13. **Executive dashboard** (DB #1222): As an organizational leader, I want to use an executive dashboard for organizational meeting visibility. -2. **Institutional investor managing proxy voting across AGMs**: As an institutional investor, I want to manage proxy voting across all portfolio company AGMs from a single dashboard, so that I can efficiently exercise my voting rights at scale. (Source: intelligence DB #5) +14. **Analytics dashboard** (DB #1539): As an organizational leader, I want to use an analytics dashboard for meeting effectiveness measurement. -3. **Administrator publishing meeting decisions**: As administrator, I want to publish key decisions from ALV and board meetings on the member portal so that all members stay informed about association governance. (Source: intelligence DB #76) +15. **Personal dashboard** (DB #1684): As an organizational leader, I want a personal dashboard for individual meeting performance. ## Acceptance Criteria - Dashboard uses CnDashboardPage with 12-column grid layout - Four KPI cards show active decisions, upcoming meetings, pending votes, and overdue actions -- Pending votes widget shows urgency indicators with countdown -- Upcoming meetings widget shows meetings across all user's bodies +- KPI cards use color variants (warning/error) based on urgency thresholds +- Pending votes widget shows urgency indicators with countdown (24h red, 48h orange) +- Quick vote from dashboard is supported for simple yes/no votes +- Upcoming meetings widget shows meetings across all user's bodies with preparation status +- Calendar strip shows current week with meeting indicators +- Decision board (kanban) groups decisions by process template state +- Kanban drag-and-drop validates against process template guards before transitioning +- My Work section shows unified list of pending votes, action items, documents, and meetings +- Organization-wide decision overview available for admins/oversight roles +- Motion follow-up and executive commitment tracking dashboards available +- Meeting efficiency analytics widget shows duration trends, decision throughput, completion rate, cost +- Comparative analytics across bodies available - Empty state shows setup guidance for new installations -- Nextcloud Dashboard widget registered via OCP\Dashboard\IWidget -- Quick action buttons in header for creating meetings and decisions +- Nextcloud Dashboard widget registered via OCP\Dashboard\IWidget with pending votes, next meeting, overdue actions +- Quick action buttons in header for creating meetings, decisions, and ad-hoc votes +- All KPI values backed by benchmark data from Flowtrace/Worklytics research +- Dashboard data refreshes without full page reload + +## External Sources + +| # | Type | Title | Key Insight | +|---|------|-------|-------------| +| 323 | product | 15 Meeting KPIs (Flowtrace) | Decision rate, action item completion, attendance analytics | +| 347 | research | 12 Manager Scorecard KPIs (Worklytics) | Meeting hours/week, 1:1 frequency, focus time ratio, benchmarks | +| 349 | product | Meeting Analytics Dashboard Guide (Flowtrace) | Executive tiles, team investment view, meeting audit | +| 322 | product | Flowtrace Meeting Analytics | 2.2M meetings benchmarked, real-time cost, behavioral nudges | +| 319 | research | State of Meetings Report 2024 (Fellow) | 78% too many meetings, only 37% use agendas | +| 342 | research | Action Item Completion Rate (Count.co) | 44% never completed, 71% meetings fail objectives | +| 325 | research | $37B/Year in Unnecessary Meetings | $25K/employee/year, $100M/year large companies | +| 172 | analyst-report | Gartner Corporate Governance Software | Only 45% of boards deemed effective | +| 114 | product | BoardPro Decision Register | Automated decision capture, searchable by keyword/date | +| 97 | case-study | iBabs for Local Government | Quorum tracking, RSVP, voting, ISO/GDPR certified | +| 151 | comparison | Top Board Portal Software 2026 | Diligent, OnBoard, iDeals, Nasdaq, Govenda, Boardable | +| 442 | review | BoardEffect Reviews (G2) | 4.5/5, real-time sync, limited meeting minutes | +| 432 | review | Diligent Boards Reviews (Capterra) | Organized single location, reusable templates, admin not user-friendly | diff --git a/openspec/specs/decision-management/spec.md b/openspec/specs/decision-management/spec.md index 915b6e8..e0fc2f2 100644 --- a/openspec/specs/decision-management/spec.md +++ b/openspec/specs/decision-management/spec.md @@ -4,26 +4,34 @@ status: idea # Decision Management Specification -## Purpose +**Status**: idea +**Standards**: Schema.org (`Action`, `VoteAction`, `ChooseAction`), Akoma Ntoso (`decision`, `judgment`), OpenRaadsinformatie (`Besluit`), Awb, BW Boek 2, Gemeentewet, DMN, BPMN 2.0 +**Feature tier**: MVP -Decision management is the core capability of Decidesk. A decision represents a formal choice made by a governance body, association, corporate board, or operational team. Each decision follows a configurable state machine lifecycle from proposal through deliberation, voting, and resolution. This specification covers the decision entity, status transitions, the Symfony Workflow-backed state machine, and audit trail recording. +## Purpose -**Standards**: Schema.org (`Action`, `VoteAction`, `ChooseAction`), Akoma Ntoso (`decision`, `judgment`), OpenRaadsinformatie (`Besluit`) -**Feature tier**: MVP +Decision management is the core capability of Decidesk. A decision represents a formal choice made by a governance body, association, corporate board, or operational team. Each decision follows a configurable state machine lifecycle from proposal through deliberation, voting, and resolution. This specification covers the decision entity, status transitions, the Symfony Workflow-backed state machine, and audit trail recording. The system uniquely spans five decision-making domains (legislative, association, corporate governance, corporate operations, and citizen participation) -- no competitor currently covers all five (insight #7). ## Data Model -See [ARCHITECTURE.md](../../docs/ARCHITECTURE.md) for the full Decision entity definition including property tables, Schema.org mappings, Akoma Ntoso alignment, and OpenRaadsinformatie mapping. +See [ARCHITECTURE.md](../../architecture/README.md) for the full Decision entity definition including property tables, Schema.org mappings, Akoma Ntoso alignment, and OpenRaadsinformatie mapping. + +| Entity | Schema.org Type | Key Properties | +|--------|----------------|----------------| +| Decision | `schema:ChooseAction` | title, body, status, decisionType, votingResult, enactedDate | +| Vote | `schema:VoteAction` | candidate, option, result, voter, actionStatus | +| Resolution | `schema:Action` | identifier, title, body, datePublished, legislationIdentifier | +| AuditEntry | `schema:Action` | timestamp, actor, fromState, toState, comment | ## Requirements --- -### Requirement: Decision Creation +### Requirement: Decision Creation [MVP] The system MUST support creating decision records linked to a meeting, agenda item, or body. Each decision MUST have a `title`, a `body` (governing body reference), and an initial status of `draft`. Decisions MUST be stored as OpenRegister objects in the `decidesk` register using the `decision` schema. -**Feature tier**: MVP +**Legal reference**: Awb Art. 1:3 -- all administrative decisions (besluiten) must be in writing, contain motivation, and follow proper procedure. #### Scenario: Create a decision from a meeting agenda item @@ -51,12 +59,12 @@ The system MUST support creating decision records linked to a meeting, agenda it --- -### Requirement: Decision State Machine +### Requirement: Decision State Machine [MVP] -The system MUST enforce a configurable state machine for decision lifecycle management using the Symfony Workflow Component. The default lifecycle MUST include states: `draft`, `proposed`, `deliberating`, `voting`, `decided`, `enacted`, `archived`. Only valid transitions MUST be allowed. +The system MUST enforce a configurable state machine for decision lifecycle management using the Symfony Workflow Component (insight #11). The default lifecycle MUST include states: `draft`, `proposed`, `deliberating`, `voting`, `decided`, `enacted`, `archived`. Only valid transitions MUST be allowed. The state machine MUST be defined in YAML configuration, support guards via expression language and event listeners, and fire transition events for audit trail recording. -**Feature tier**: MVP **Legal reference**: Awb 3:40-3:45 (formal decision requirements), Gemeentewet 56 (council decision procedures) +**Technical reference**: Symfony Workflow Component -- PHP-native state machine, lightweight, supports both `workflow` and `state_machine` types (insight #14: avoid full BPMN engines -- overkill for this use case) #### Scenario: Transition a decision from draft to proposed @@ -81,13 +89,19 @@ The system MUST enforce a configurable state machine for decision lifecycle mana - AND the system MUST generate a resolution record (see resolution-minutes spec) - AND the enacted date MUST be recorded +#### Scenario: Custom state machine per body type + +- GIVEN a governance body of type "management_team" with a simplified workflow (draft -> proposed -> decided -> enacted) +- WHEN an administrator configures the body's decision workflow +- THEN the system MUST allow skipping the `deliberating` and `voting` states +- AND only the configured transitions MUST be available for that body's decisions + --- -### Requirement: Decision Audit Trail +### Requirement: Decision Audit Trail [MVP] The system MUST maintain a complete audit trail for every decision, recording all state transitions, modifications, votes, and comments with timestamps and actor identities. The audit trail MUST be immutable. -**Feature tier**: MVP **Legal reference**: WBTR (Wet bestuur en toezicht rechtspersonen) documentation requirements #### Scenario: View the complete history of a decision @@ -104,14 +118,19 @@ The system MUST maintain a complete audit trail for every decision, recording al - THEN the system MUST reject the modification - AND the original entry MUST remain unchanged +#### Scenario: Export audit trail for compliance + +- GIVEN a decision with a complete audit trail +- WHEN a user exports the audit trail +- THEN the system MUST produce a timestamped document containing all entries +- AND the export MUST be suitable for compliance reporting (WBTR, Archiefwet) + --- -### Requirement: Decision List and Search +### Requirement: Decision List and Search [MVP] The system MUST provide a list view of all decisions with search, sort, and filter capabilities. Users MUST be able to filter by status, body, date range, and decision type. -**Feature tier**: MVP - #### Scenario: Filter decisions by status - GIVEN the decision list contains decisions in various statuses @@ -126,14 +145,19 @@ The system MUST provide a list view of all decisions with search, sort, and filt - THEN the decision "Budget 2026" MUST appear in the results - AND the search MUST be case-insensitive +#### Scenario: Search across decisions, motions, and minutes + +- GIVEN the Nextcloud unified search is available +- WHEN the user searches from the Nextcloud search bar +- THEN decisions, motions, and meeting minutes MUST appear in results +- AND results MUST link directly to the decision detail view + --- -### Requirement: Decision Detail View +### Requirement: Decision Detail View [MVP] The system MUST provide a detail view for each decision using the `CnDetailPage` and `CnObjectSidebar` components. The detail view MUST show decision metadata, current status with state machine visualization, linked agenda item/meeting, voting results, and the audit trail. -**Feature tier**: MVP - #### Scenario: View decision detail with voting results - GIVEN a decision in `decided` status with completed voting @@ -143,23 +167,438 @@ The system MUST provide a detail view for each decision using the `CnDetailPage` - AND the state machine visualization MUST highlight the current state - AND the sidebar MUST show metadata, linked meeting, and action buttons -## User Stories +#### Scenario: Visualize state machine with XState + +- GIVEN a decision with a configured workflow +- WHEN the user views the decision detail +- THEN the frontend MUST render the state machine diagram using XState (insight #12) +- AND the current state MUST be visually highlighted +- AND past states MUST show transition timestamps + +--- + +### Requirement: Voting Execution [MVP] + +The system MUST support multiple voting methods configurable per body and decision type. The default MUST be simple majority (for/against/abstain). The system MUST enforce quorum before allowing votes. + +**Legal reference**: Gemeentewet Art. 30 (absolute majority, tie-breaking), BW 2:38 (one member one vote), BW 2:230 (configurable majority) + +#### Scenario: Conduct open vote with simple majority + +- GIVEN a decision in `voting` status with quorum met +- WHEN each member casts their vote (for/against/abstain) +- THEN the system MUST tally votes in real-time +- AND the result MUST be determined by simple majority (>50% of valid votes) +- AND the voting result MUST be recorded with individual vote records + +#### Scenario: Conduct secret ballot for personnel appointment + +- GIVEN a decision of type "appointment" requiring secret ballot +- WHEN members cast their votes +- THEN individual votes MUST NOT be attributable to specific members +- AND only the aggregate result (for/against/abstain counts) MUST be recorded +- AND the system MUST comply with Gemeentewet Art. 31 (mandatory secret ballot for appointments) + +#### Scenario: Enforce qualified majority for statute amendment + +- GIVEN a decision of type "statute_amendment" requiring 2/3 majority +- WHEN 60% vote in favor +- THEN the decision MUST be marked as "rejected" because 2/3 threshold was not met +- AND the required threshold MUST be clearly displayed + +#### Scenario: Handle tie-breaking + +- GIVEN a decision with equal for/against votes in a full meeting +- WHEN the votes are tallied +- THEN the decision MUST be rejected per Gemeentewet Art. 30 +- AND for tied votes on persons, the system MUST support resolution by lot + +--- + +### Requirement: Written Decision Procedure (Besluitvorming buiten vergadering) [MVP] + +The system MUST support decision-making outside of meetings via written/electronic procedure per BW 2:238 (BV) and BW 2:40 (association). + +**Legal reference**: BW 2:238 requires unanimous consent to the METHOD (not the decision itself), BW 2:40 for associations + +#### Scenario: Circulate written resolution to board members + +- GIVEN a chair who wants to make an urgent decision between meetings +- WHEN they create a written resolution and circulate it to all board members +- THEN each member MUST be able to consent to the method and vote on the resolution electronically +- AND the system MUST track that ALL eligible members have consented to the written procedure +- AND the resolution MUST only be valid if unanimity on the method is achieved + +#### Scenario: Written resolution with deadline + +- GIVEN a written resolution circulated with a 5-day response deadline +- WHEN the deadline expires with 8 of 10 members having responded +- THEN the system MUST notify the chair that 2 members have not responded +- AND the resolution MUST NOT be considered valid until all members respond or explicitly waive + +--- + +### Requirement: Decision by Silence (Stilzwijgende goedkeuring) [V1] + +The system SHOULD support "decision by silence" where a proposal is adopted if no member objects within a configured period. + +#### Scenario: Adopt proposal by silence + +- GIVEN a proposal circulated with a 7-day objection period +- WHEN no member raises an objection within 7 days +- THEN the proposal MUST be automatically adopted +- AND the system MUST record the adoption with "adopted by silence" as the method + +--- + +### Requirement: Decision Categorization and Types [MVP] + +The system MUST support configurable decision types that map to different workflows, required majorities, and document templates. + +#### Scenario: Configure decision types per body + +- GIVEN an administrator configuring a municipal council body +- WHEN they define decision types: "raadsbesluit", "motie", "amendement", "hamerstuk" +- THEN each type MUST have its own workflow, required majority, and document template +- AND "hamerstuk" MUST default to adoption without debate + +#### Scenario: Track decision type distribution + +- GIVEN a body with decisions of various types +- WHEN a user views the decision analytics +- THEN the system MUST show the distribution of decision types (pie chart) +- AND the decision rate (decisions per meeting) MUST be trackable + +--- + +### Requirement: Decision Implementation Tracking [V1] + +The system SHOULD track the implementation status of decisions with responsible persons and deadlines. + +#### Scenario: Assign implementation tasks after decision -1. **Board secretary creating a structured decision**: As a board secretary, I want to create a structured decision proposal with options analysis, risk assessment, and financial impact, so that the board can make well-informed strategic decisions. (Source: intelligence DB #15) +- GIVEN a decision in `enacted` status +- WHEN the chair assigns implementation tasks with owners and deadlines +- THEN each task MUST be tracked with status (pending/in-progress/completed) +- AND tasks MUST sync to Nextcloud Tasks via CalDAV VTODO (insight #26) +- AND overdue tasks MUST trigger notifications -2. **Supervisory board reviewing proposals**: As a supervisory board chair, I want to review strategic proposals with full context and approve or reject them digitally, so that governance oversight is exercised efficiently. (Source: intelligence DB #16) +#### Scenario: Report implementation progress at next meeting + +- GIVEN a meeting with pending implementation items from previous decisions +- WHEN the chair reviews the implementation status +- THEN the system MUST show all open implementation tasks grouped by decision +- AND completion percentage MUST be visible per decision + +--- + +### Requirement: Decision Notification and State Change Alerts [MVP] + +The system MUST send notifications on every decision state change to relevant stakeholders (insight #31). + +#### Scenario: Notify body members of new proposal + +- GIVEN a decision transitioning from `draft` to `proposed` +- WHEN the transition occurs +- THEN all members of the governing body MUST receive a Nextcloud notification +- AND the notification MUST link directly to the decision detail view +- AND email notifications MUST be sent to external stakeholders without Nextcloud accounts (insight #28) + +--- + +### Requirement: Decision ID and Numbering [MVP] + +The system MUST assign a unique, sequential decision identifier per body and year (e.g., "RB-2026-042" for Raadsbesluit 42 of 2026). + +#### Scenario: Auto-generate decision number + +- GIVEN a decision being enacted for the municipal council in 2026 +- WHEN the decision transitions to `enacted` +- THEN the system MUST assign the next sequential number in the format `{body_prefix}-{year}-{sequence}` +- AND the number MUST be permanently immutable once assigned + +--- + +### Requirement: BOB Model Support (Beeldvorming-Oordeelsvorming-Besluitvorming) [V1] + +The system SHOULD support the Dutch 3-phase decision model used by municipalities: Beeldvorming (information gathering), Oordeelsvorming (opinion formation), Besluitvorming (decision-making). + +**Evidence**: BOB model used by Dutch municipalities including Hollands Kroon with separate phase meetings (source #337) + +#### Scenario: Track decision through BOB phases + +- GIVEN a council proposal entering the BOB process +- WHEN the proposal moves through committee (Beeldvorming), faction meetings (Oordeelsvorming), and plenary (Besluitvorming) +- THEN the system MUST track the current BOB phase +- AND the phase history MUST be visible on the decision detail view + +--- + +### Requirement: Decision Archiving and Publication [V1] + +The system SHOULD support archiving decisions per Archiefwet and publishing decision lists per Woo (Wet open overheid). + +**Legal reference**: Woo Art. 3.3 requires active publication of decision lists, agendas, and meeting documents + +#### Scenario: Publish decision list after council meeting + +- GIVEN a council meeting with 12 decisions taken +- WHEN the griffier publishes the decision list +- THEN the system MUST generate a structured list with decision number, title, vote outcome, and date +- AND the list MUST be publishable to the public portal per Woo requirements + +#### Scenario: Archive decision with retention schedule + +- GIVEN an enacted decision with associated documents +- WHEN the archivaris initiates archiving +- THEN the system MUST apply the VNG selectielijst retention period +- AND all associated documents, audit trail, and voting records MUST be included + +--- + +### Requirement: Collegial Decision-Making [Enterprise] + +The system MAY support collegial decision models where a body acts as a collective (e.g., College van B&W). + +#### Scenario: Record collegial B&W decision + +- GIVEN a College van B&W meeting with 5 wethouders +- WHEN the college takes a decision collectively +- THEN the decision MUST be recorded as a collegial decision +- AND individual positions MUST NOT be publicly recorded (per collegialiteitsbeginsel) + +--- + +### Requirement: Decision Support with AI [Enterprise] + +The system MAY provide AI-augmented decision support using self-hosted LLM capabilities. + +**Market context**: AI meeting tool usage grew 17x in 2024 (insight #5), no self-hosted AI meeting solution exists (insight #9) + +#### Scenario: AI-generated decision summary + +- GIVEN a decision that has gone through deliberation with extensive discussion +- WHEN the user requests an AI summary +- THEN the system MUST generate a concise summary of the discussion points, arguments for/against, and key considerations +- AND the AI MUST run on self-hosted infrastructure (privacy-first, GDPR-native) + +--- + +### Requirement: Consent-Based Decision-Making [V1] + +The system SHOULD support sociocratic consent-based decision-making with structured rounds. + +**Evidence**: Consent process -- proposal, question round, reaction round, objection round, integration. Faster than consensus, more inclusive (source #256) + +#### Scenario: Run consent decision process + +- GIVEN a decision using consent-based method +- WHEN the facilitator initiates the consent rounds +- THEN the system MUST guide through: proposal presentation, question round, reaction round, objection round, integration +- AND "no objection" MUST count as consent (different from agreement) +- AND valid objections MUST be integrated into amended proposals + +--- + +### Requirement: Decision Data Export and Interoperability [MVP] + +The system MUST export decisions in standardized formats for interoperability. + +#### Scenario: Export decision as OpenRaadsinformatie Besluit + +- GIVEN an enacted council decision +- WHEN the system exports the decision +- THEN the export MUST conform to the OpenRaadsinformatie `Besluit` schema +- AND the export MUST include Akoma Ntoso-compatible document structure + +#### Scenario: Export decision register as CSV/JSON + +- GIVEN a set of decisions filtered by body and date range +- WHEN the user triggers export +- THEN the system MUST produce CSV or JSON with all decision metadata +- AND the export MUST include decision numbers, dates, outcomes, and links + +--- -3. **Secretary recording decisions in real-time**: As a secretary, I want to record decisions in real-time during the MT meeting with a structured format (decision text, type, vote, conditions), so that there is immediate clarity on what was decided. (Source: intelligence DB #89) +## User Stories (from intelligence database) -4. **Chair circulating written resolution**: As chair, I want to circulate a proposal for written decision to all board members and collect their votes electronically so that urgent decisions can be made between meetings per BW 2:40. (Source: intelligence DB #68) +### Legislative Domain -5. **Member tracking decision implementation**: As chair, I want to track the implementation status of ALV decisions with responsible persons and deadlines so that I can report progress at the next ALV. (Source: intelligence DB #77) +1. As a griffier, I want to publish the complete decision list after each council meeting so that citizens and media can immediately see what was decided. (DB #86, journey: Decision List Publication) +2. As a raadslid, I want to track how my faction voted on all decisions this term so that I can report to my constituents. (DB #96, journey: Voting Record Analysis) +3. As a voorzitter, I want to process all hamerstukken in one batch without debate so that meeting time is reserved for items requiring discussion. (DB #164, journey: Plenary Debate & Decision-Making) +4. As a burger, I want to set up keyword-based alerts for council decisions so that I am notified when topics that affect me are being discussed. (DB #208, journey: Meeting & Topic Notifications) +5. As an archivaris, I want to verify that all council meeting records (agenda, minutes, decisions, recordings, documents) are complete in the archive so that no gaps exist. (DB #183, journey: Records Archiving & Compliance) +6. As a commissievoorzitter, I want to formally record the committee advice on whether an item is ready for plenary decision so that the presidium can plan the plenary agenda. (DB #162, journey: Committee Information Gathering) +7. As a fractievoorzitter, I want to record the agreed faction position on each agenda item so that all members know how to vote. (DB #153, journey: Faction Position Coordination) +8. As a dijkgraaf, I want to chair the water board general assembly with proper quorum and voting rules so that decisions are legally valid. (DB #103, journey: Water Board General Assembly Meeting) + +### Association Domain + +9. As a secretary, I want to record decisions in real-time during the meeting with a structured format (decision text, type, vote, conditions) so that there is immediate clarity on what was decided. (DB #89) +10. As a chair, I want to circulate a proposal for written decision to all board members and collect their votes electronically so that urgent decisions can be made between meetings per BW 2:40. (DB #68) +11. As a chair, I want to track the implementation status of ALV decisions with responsible persons and deadlines so that I can report progress at the next ALV. (DB #77) +12. As a secretary, I want to verify that a statute amendment vote meets the required quorum and qualified majority so that the notary can confirm validity. (DB #59) +13. As a member, I want to cast my vote securely during the ALV so that my participation is equal to physical attendees. (DB #58) +14. As a kascommissie member, I want to present our audit findings and decharge recommendation to the ALV so that members can make an informed decision about board discharge. (DB #62) +15. As a board member, I want to formally declare a conflict of interest for a specific decision so that I am properly excluded per WBTR. (DB #69) +16. As a ledenraad member, I want to prepare my voting position with constituency input so that I can effectively represent my members. (DB #82) + +### Corporate Governance Domain + +17. As a board secretary, I want to create a structured decision proposal with options analysis, risk assessment, and financial impact so that the board can make well-informed strategic decisions. (DB #15) +18. As a supervisory board chair, I want to review strategic proposals and approve or reject them digitally so that governance oversight is exercised efficiently. (DB #16) +19. As a supervisory board chair, I want a digital workflow for approving major management decisions so that approvals can be obtained efficiently even outside scheduled meetings. (DB #25) +20. As a CFO, I want to review major budget requests with financial controller assessment so that the MT can make well-informed spending decisions. (DB #99) + +### Corporate Operations Domain + +21. As a CEO, I want to review the outcomes of decisions made in previous MT meetings so that we can assess decision quality and adjust course when needed. (DB #95) +22. As an employee, I want to search a central decision register by topic, date, meeting, or decision-maker so that I can find relevant past decisions and their rationale. (DB #129) +23. As an MT member, I want to selectively cascade specific decisions from the MT meeting to my department so that my team knows what was decided. (DB #94) +24. As a project manager, I want to prepare a steering committee meeting with decision items and risk overview so that the committee can make informed decisions efficiently. (DB #108) +25. As a meeting facilitator, I want to run consent-based decision processes with structured rounds so that decisions have broad support. (DB #346) + +### Citizen Participation Domain + +26. As a neighbourhood council member, I want decisions from our meetings to be formally tracked and reported to the municipality so that citizen input leads to action. (DB #247, journey: Run neighbourhood council meeting cycle) +27. As a coordinator, I want to track decisions from citizens assembly deliberation rounds so that the outcomes are structured and actionable. (DB #223) +28. As a citizen, I want to search for decisions, motions, and meeting minutes from the Nextcloud unified search bar so that I can find information without navigating multiple systems. (DB #1873) + +### Cross-Domain (Nextcloud Integration) + +29. As a secretary, I want action items from decisions to automatically become CalDAV VTODO tasks assigned to the responsible person so that nothing falls through the cracks. (DB #1836) +30. As a member, I want each major decision to have a linked Talk conversation for informal deliberation so that discussion can happen before the formal meeting. (DB #1851) +31. As any user, I want decisions to appear as embeddable references in Nextcloud Mail, Text, and Talk via Smart Picker so that I can reference decisions in context. (insight #30) +32. As a chair, I want to see decision pipelines as Deck boards with cards moving through stages automatically so that progress is visually clear. (insight #32) + +## Evidence Sources + +### Legal Standards (Mandatory) + +| Standard | Scope | Key Requirements | +|----------|-------|-----------------| +| **Awb** (Algemene wet bestuursrecht) | All administrative decisions | Art. 1:3 defines 'besluit'; must be written with motivation | +| **Gemeentewet** | Municipal councils | Art. 20: quorum >50%; Art. 30: absolute majority; Art. 31: secret ballot for appointments | +| **BW Boek 2** (Burgerlijk Wetboek) | Legal entities (BV, NV, associations) | Art. 2:38: voting rights; Art. 2:230: majority/quorum; Art. 2:238: written procedure | +| **Woo** (Wet open overheid) | Government transparency | Art. 3.3: active publication of decision lists and meeting documents | +| **Provinciewet** | Provincial States | Similar to Gemeentewet for provincial level | +| **Waterschapswet** | Water boards | Oldest democratic institutions in NL with unique voting rules | + +### Forum Standaardisatie Standards (Recommended) + +| Standard | Relevance | +|----------|-----------| +| **BPMN 2.0** | Process modeling for decision workflows | +| **DMN** | Decision tables for configurable voting rules | +| **Akoma Ntoso** | XML representation of legislative documents and decisions | + +### External Research & Market Evidence + +- **$541B wasted on meetings globally** (Doodle analysis of 19M meetings) -- insight #1 +- **AI meeting tool usage grew 17x in 2024** (Fellow State of Meetings 2024) -- insight #5 +- **European participation market 300M EUR, e-voting 500M EUR** (expected within 5 years) -- insight #23 +- **No competitor covers all 5 decision-making domains** -- market is completely siloed -- insight #7 +- **No self-hosted AI meeting solution exists** -- Otter.ai and Fireflies.ai face class-action lawsuits over recording consent -- insight #9 +- **Council of Europe CM/Rec(2017)5**: 49 standards for e-voting (secrecy, auditability, verifiability) -- source #258 +- **POLYAS**: only BSI Common Criteria certified voting software -- source #270 + +### Competitor Features + +| Competitor | Key Decision Features | Gap | +|-----------|----------------------|-----| +| **Notubiz/GO** | Council decisions, decision lists | No corporate/association governance | +| **iBabs** | Board portal, decision tracking | No formal voting, no legislative workflow | +| **Diligent** | Enterprise board governance | No legislative features, closed source | +| **Loomio** | 7+ voting types, async decisions | No formal governance compliance | +| **Decidim** | Participatory budgeting, e-voting | No corporate governance | +| **OpenSlides** | Assembly voting (4 modes) | No cross-domain governance | + +### Tender Requirements + +- **W-BESL** (gemeente zaaksysteem): "Beschrijf ondersteuning bestuurlijk besluitvormingsproces inclusief agendabeheer, vergaderingen, publiceren en archiveren" (70 pts) +- **W9** (zaaksysteem): "Beschrijf hoe de Oplossing het proces van bestuurlijke besluitvorming ondersteunt" (68 pts) +- **SGC 1** (RIS/BIS): "Ondersteuning bestuurlijke besluitvormingsketen" (30 pts) +- Multiple tenders require integration with iBabs for decision workflows + +## Customer Journeys + +### Legislative Domain +- **Plenary Debate & Decision-Making (Besluitvorming)** -- Voting on proposals, motions, amendments in council +- **Decision List Publication** -- Compiling and publishing decisions after meetings +- **Voting Record Analysis** -- Analyzing voting patterns across meetings and topics +- **Committee Information Gathering (Beeldvorming)** -- Committee phase of BOB model +- **Presidium Agenda Setting** -- Classifying items as hamerstuk/bespreekstuk + +### Association Domain +- **ALV Regular Voting** -- Simple majority votes on regular agenda items +- **ALV Qualified Majority Voting (Statute Amendments)** -- 2/3 majority with quorum +- **Board Discharge (Decharge) Voting** -- Annual discharge vote based on kascommissie report +- **Proxy Vote Management** -- Digital proxy (volmacht) management +- **Written Board Resolution (Outside Meeting)** -- BW 2:40 written procedure +- **Decision Implementation Tracking** -- Tracking implementation with responsible persons + +### Corporate Governance Domain +- **Supervisory Board Oversight & Approval** -- Digital workflows for major decisions +- **Board Conflict of Interest Declaration** -- WBTR-compliant conflict management +- **AGM Minutes & Legal Documentation** -- Notarial minutes and resolution filing + +### Corporate Operations Domain +- **MT Decision Making During Meeting** -- Real-time decision recording with structured format +- **MT Recurring Review Cycle** -- Reviewing outcomes of previous decisions +- **Steering Committee Meeting** -- Project decision escalation +- **Decision Register Search and Reference** -- Central searchable decision register +- **Meeting Efficiency & Analytics** -- Decision rate, time-to-decision KPIs + +### Citizen Participation Domain +- **Organize a citizens assembly** -- Structured deliberation to decision +- **Run neighbourhood council meeting cycle** -- Community-level decision tracking ## Acceptance Criteria -- Decisions are stored as OpenRegister objects with `@type` of `schema:ChooseAction` -- State machine enforces valid transitions only (Symfony Workflow Component) -- All transitions are recorded in an immutable audit trail -- Decision list supports search, sort, and filter by status/body/date -- Detail view uses CnDetailPage + CnObjectSidebar with state machine visualization -- OpenRaadsinformatie `Besluit` mapping is available for each decision +1. Decisions are stored as OpenRegister objects with `@type` of `schema:ChooseAction` +2. State machine enforces valid transitions only (Symfony Workflow Component) +3. State machine configuration is defined in YAML and customizable per body +4. Frontend state machine visualization uses XState with @xstate/vue integration +5. All transitions are recorded in an immutable audit trail +6. Decision list supports search, sort, and filter by status/body/date/type +7. Detail view uses CnDetailPage + CnObjectSidebar with state machine visualization +8. OpenRaadsinformatie `Besluit` mapping is available for each decision +9. Voting supports simple majority, qualified majority, and secret ballot +10. Quorum is verified before voting can begin +11. Written decision procedure (buiten vergadering) is supported per BW 2:238 +12. Decision numbers are auto-generated in format `{body_prefix}-{year}-{sequence}` +13. Notifications fire on every state change to relevant stakeholders +14. Decision lists are publishable per Woo requirements +15. Tie-breaking follows Gemeentewet Art. 30 (rejection) and Art. 31 (lot for persons) +16. Conflict of interest declarations are tracked per WBTR +17. Implementation tasks sync to Nextcloud Tasks via CalDAV VTODO +18. Decisions are searchable from Nextcloud unified search +19. Audit trail is exportable for compliance reporting +20. BOB model phases are trackable for legislative decisions +21. Decision-by-silence is supported with configurable objection periods +22. Consent-based decision rounds are supported (sociocratic model) +23. Decision data is exportable as CSV, JSON, and OpenRaadsinformatie XML +24. Collegial decisions (B&W model) record collective outcome without individual positions +25. AI decision summaries run on self-hosted infrastructure only + +## Notes + +### Open Questions + +- What is the minimum viable set of voting methods for MVP? (Simple majority + qualified majority + secret ballot recommended) +- Should we implement full E2E verifiable voting (homomorphic encryption, zero-knowledge proofs) or defer to V2? Council of Europe standard has 49 requirements. +- How to handle the transition when WDAV (Wet Digitale Algemene Vergadering) passes the Eerste Kamer? Expected impact on digital voting requirements. + +### Legal Risks + +- E-voting security is complex and regulated (insight #21). POLYAS is the only BSI-certified system. Start with internal governance voting, not public elections. +- Otter.ai and Fireflies.ai face class-action lawsuits over recording without consent -- self-hosted approach mitigates this risk. +- BW 2:238 written procedure requires UNANIMOUS consent to the method -- the system must enforce this strictly. + +### Technical Decisions + +- Use Symfony Workflow (PHP) for backend state machine, XState (JS) for frontend visualization (insights #11, #12) +- Avoid full BPMN engines (Camunda, Flowable) -- Java-based, significant infrastructure overhead (insight #14) +- Use DMN-inspired decision tables for configurable voting rules (insight #13) +- Smart Picker / References integration for embedding decisions in other Nextcloud apps is low-effort, high-value (insight #30) diff --git a/openspec/specs/meeting-efficiency/spec.md b/openspec/specs/meeting-efficiency/spec.md index 232adf7..13bfe94 100644 --- a/openspec/specs/meeting-efficiency/spec.md +++ b/openspec/specs/meeting-efficiency/spec.md @@ -8,9 +8,58 @@ status: idea Meeting efficiency features help governance bodies run productive meetings. This includes real-time timers for agenda items and speaking time, a meeting cost calculator (based on participant hourly rates), analytics on meeting duration and decision throughput, and tools to keep discussions focused. These features transform Decidesk from a compliance tool into a productivity platform that actively improves organizational decision-making. -**Standards**: Schema.org (`Duration`, `MonetaryAmount`) +**Standards**: Schema.org (`Duration`, `MonetaryAmount`), Dutch BOB model, Robert's Rules of Order, EOS Level 10 Meeting format **Feature tier**: V1 +## Evidence Base + +### Market Research -- The Meeting Crisis + +| Statistic | Source | +|-----------|--------| +| $541 billion wasted on pointless meetings globally per year | Intelligence DB insight #1 (Doodle, 19M meetings analyzed) | +| 67% of meeting time is wasted | Intelligence DB insight #1 (HBR) | +| Executives spend 23 hours/week in meetings | Intelligence DB insight #1 (HBR) | +| $37 billion/year wasted on unnecessary meetings in the US alone | External source #325 (MeetingKing) | +| Mid-level employee costs $25K/year in meetings (3hrs/day) | External source #325 | +| Large companies lose $100 million/year to unnecessary meetings | External source #325 (CBS) | +| 78% of workers say they attend too many meetings | External source #319 (Fellow State of Meetings 2024) | +| 60% of meetings are ad hoc (unplanned) | External source #321 (Microsoft Work Trend Index) | +| Workers are interrupted every 2 minutes; communication consumes 60% of workday | External source #321 | +| 44% of action items are never completed | External source #342 (Count.co) | +| 71% of meetings fail objectives due to poor follow-through | External source #342 | +| AI meeting tool usage grew 17x in 2024 | Intelligence DB insight #5 (Fellow) | +| Women's speaking time increased 65% when tracked and displayed | Intelligence DB insight #24 (Equal Time case study) | +| Only 37% of meetings use an agenda | External source #319 | +| Managers spend 13 hours/week in meetings | External source #320 | +| After-hours meetings up 16% year-over-year | External source #321 | +| 2.2 million+ meetings benchmarked by Flowtrace | External source #322 | + +### Methodology Evidence + +| Method | Description | Source | +|--------|-------------|--------| +| Dutch BOB model | 3-phase decision model: Beeldvorming (info gathering), Oordeelsvorming (opinion formation), Besluitvorming (decision). Used by Dutch municipalities. Hollands Kroon: separate BOB-phase meetings | External source #337 | +| Robert's Rules of Order | Parliamentary procedure for motions, amendments, debate, and voting. Speaking time limits, point of order, quorum rules | User stories #159, #163, #340 | +| Sociocracy / Consent-based | Structured rounds: proposal, reactions, objections, integration. "No objection" = consent. Timer per round | External source #256 | +| EOS Level 10 Meeting | Structured 90-min format with IDS (Identify, Discuss, Solve). Target >90% to-do completion rate | User story #337 | +| Dutch Reglement van Orde | Max 5 min speaking time (proportional if >6 speakers). Max 2 speaking terms per topic per faction | External source #339 | + +### Competitor Analysis + +| Competitor | Meeting Efficiency Features | Gap | +|------------|---------------------------|-----| +| Flowtrace | 2.2M meetings benchmarked, real-time cost, meeting audit dashboards, behavioral nudges | SaaS-only, no governance integration, no self-hosted | +| Fellow.app | AI meeting notes, action item tracking, meeting templates, 17x AI growth | No formal voting, no speaking time, no cost calculator | +| Decisions.com | Smart timer, AI agenda, engagement score, behavioral science | Microsoft Teams only, no self-hosted | +| iBabs | Quorum tracking, RSVP, document distribution | No timers, no cost calculator, no analytics dashboard | +| Lucid Meetings | Per-item timeboxing, sub-topics, meeting templates | Limited analytics, no governance features | +| Equal Time | Speaking time balance, gender breakdown, interruption detection | Single feature, no meeting management | + +### Self-Hosted Advantage + +No self-hosted AI meeting solution exists that combines transcription, action item extraction, and speaking time tracking with GDPR compliance (intelligence DB insight #9). Otter.ai and Fireflies.ai face class-action lawsuits over recording without consent and biometric data collection. Decidesk's Nextcloud-native approach keeps all data in the tenant. + ## Requirements --- @@ -20,6 +69,7 @@ Meeting efficiency features help governance bodies run productive meetings. This The system MUST provide a visible countdown timer for each agenda item during meeting conduct. The timer MUST start when the chair opens an agenda item and alert when the allocated time is exceeded. The chair MUST be able to extend, pause, or skip the timer. **Feature tier**: V1 +**Evidence**: Only 37% of meetings use agendas (external source #319). Per-item timeboxing is the #1 most-requested meeting productivity feature (external source #334, user story #334). #### Scenario: Timer alerts when time is exceeded @@ -28,6 +78,7 @@ The system MUST provide a visible countdown timer for each agenda item during me - THEN the system MUST display a visual alert (flashing timer, color change to red) - AND the chair MUST be presented with options: "Extend 5 min", "Extend 10 min", "Close item" - AND the actual time spent MUST be recorded for analytics +- AND a 1-minute warning MUST be shown before time expires (user story #334) #### Scenario: Pause timer during procedural interruption @@ -44,6 +95,13 @@ The system MUST provide a visible countdown timer for each agenda item during me - THEN no timer MUST be displayed - AND the elapsed time MUST still be tracked in the background for analytics +#### Scenario: Sub-topic timeboxing + +- GIVEN an agenda item with sub-topics (e.g., 2.1, 2.2, 2.3) +- WHEN the chair opens sub-topic 2.1 +- THEN a separate sub-timer MUST be available within the parent item's allocation +- AND the parent timer MUST continue running (per Lucid Meetings pattern, user story #334) + --- ### Requirement: Speaking Time Management @@ -51,6 +109,7 @@ The system MUST provide a visible countdown timer for each agenda item during me The system MUST track speaking time per participant during discussions. The chair MUST be able to set speaking time limits. The system MUST maintain a speaker queue for managing turn-taking. **Feature tier**: V1 +**Evidence**: Women's speaking time increased 65% when tracked (insight #24). Dutch Reglement van Orde mandates max 5 min per speaker, proportional allocation per faction (external source #339). Council debate speaking time is legally regulated (user story #340). #### Scenario: Enforce speaking time limit @@ -58,6 +117,7 @@ The system MUST track speaking time per participant during discussions. The chai - WHEN a speaker has been speaking for 3 minutes - THEN the system MUST display a visual and optional audio alert - AND the chair MUST be able to grant an extension or move to the next speaker +- AND a 1-minute warning MUST precede the time-up signal (user story #340) #### Scenario: Manage speaker queue @@ -67,6 +127,34 @@ The system MUST track speaking time per participant during discussions. The chai - AND the chair MUST be able to reorder the queue - AND the current speaker MUST be highlighted +#### Scenario: Track speaking balance with equity indicators + +- GIVEN a meeting with 8 participants +- WHEN the meeting is in progress +- THEN the system MUST display speaking time per participant as duration and percentage +- AND a balance indicator MUST show over/under-participation (green = balanced, red = imbalanced) +- AND gender breakdown MUST be available (per Equal Time pattern, user story #336) +- AND interruption detection MUST be flagged (user story #336) +- AND historical trends per participant across meetings MUST be tracked + +#### Scenario: Configure proportional faction-based speaking time + +- GIVEN a council debate with 5 factions of different sizes +- WHEN the clerk configures speaking time allocation +- THEN time MUST be allocated proportionally to faction size (user story #340) +- AND a maximum of 2 speaking terms per faction per topic MUST be enforceable +- AND interruptions MUST be tracked separately (Tweede Kamer model) +- AND a post-debate report MUST show allocation vs. actual time per faction + +#### Scenario: BOB phase speaking rules + +- GIVEN a council agenda item in the Beeldvorming (image-forming) phase +- WHEN the chair opens the item for discussion +- THEN speaking rules MUST differ from Besluitvorming (decision) phase +- AND the BOB phase MUST be visible to all participants (user story #161, #341) +- AND citizens MUST be enabled to participate in the Beeldvorming phase (user story #341) +- AND time spent per BOB phase MUST be tracked across meetings + --- ### Requirement: Meeting Cost Calculator @@ -74,13 +162,15 @@ The system MUST track speaking time per participant during discussions. The chai The system MUST calculate and display the running cost of a meeting based on participant count and configurable hourly rates. The cost MUST be displayed in real-time during the meeting and in meeting analytics afterward. **Feature tier**: V1 +**Evidence**: $541B wasted globally (insight #1). $25K/employee/year (external source #325). $100M/year for large companies (CBS via external source #325). Meeting cost visibility is a behavioral nudge that reduces meeting duration by 10-15% (external source #322, Flowtrace). #### Scenario: Display running meeting cost - GIVEN a meeting with 12 participants and an average hourly rate of EUR 75 - WHEN the meeting has been running for 45 minutes - THEN the system MUST display the running cost as "EUR 675" (12 x 75 x 0.75) -- AND the cost MUST update in real-time as the meeting progresses +- AND the cost MUST update in real-time (per second) as the meeting progresses (user story #335) +- AND the cost MUST include fully loaded cost (salary + benefits) when configured #### Scenario: Show cost per agenda item in analytics @@ -89,13 +179,118 @@ The system MUST calculate and display the running cost of a meeting based on par - THEN the cost MUST be broken down per agenda item based on actual time spent - AND the most expensive agenda items MUST be highlighted +#### Scenario: Meeting cost threshold alerts + +- GIVEN a meeting with a configured cost budget of EUR 1,500 +- WHEN the running cost exceeds the budget threshold +- THEN a visual alert MUST be displayed to the chair +- AND the alert MUST show percentage over budget (user story #335) + +#### Scenario: Organizational meeting cost dashboard + +- GIVEN a CEO viewing the meeting analytics for their organization +- WHEN they open the meeting cost dashboard +- THEN total meeting cost per week/month/quarter MUST be displayed +- AND cost breakdown by team/department MUST be visible +- AND trend lines MUST show cost trajectory over time +- AND benchmark data MUST be available for comparison (user story #330) + +--- + +### Requirement: Action Item Tracking + +The system MUST support capturing, assigning, and tracking action items from meetings. Action items MUST have an owner, deadline, and status. The system MUST integrate with Nextcloud Tasks via CalDAV VTODO. + +**Feature tier**: V1 +**Evidence**: 44% of action items never completed (external source #342). 71% of meetings fail objectives due to poor follow-through. EOS Level 10 targets >90% completion rate. Action item tracking appears in 213 user stories across all domains (insight #26). + +#### Scenario: Capture action item during meeting + +- GIVEN a meeting in progress +- WHEN the secretary adds an action item with owner "Jan" and deadline "2026-04-15" +- THEN the action item MUST be linked to the current agenda item and decision +- AND Jan MUST receive a notification (user story #337) +- AND a CalDAV VTODO task MUST be created in Nextcloud Tasks via _todos metadata (user story #1834) + +#### Scenario: AI-suggested action items from transcription + +- GIVEN meeting transcription is enabled +- WHEN the meeting ends +- THEN the system SHOULD suggest action items extracted from the transcription (user story #1170) +- AND each suggestion MUST include a proposed owner and deadline +- AND the secretary MUST be able to confirm, modify, or dismiss each suggestion + +#### Scenario: Track action item completion rate + +- GIVEN multiple meetings with action items over the past quarter +- WHEN the user views action item analytics +- THEN the completion rate MUST be calculated: (completed / total) x 100 (external source #342) +- AND the rate MUST be shown per person, per team, and per meeting +- AND items not completed MUST automatically roll over to the next meeting agenda (user story #19) + +#### Scenario: Action item status updates between meetings + +- GIVEN an action item assigned to an MT member +- WHEN the MT member updates status from "in progress" to "completed" +- THEN the secretary and chair MUST be automatically notified (user story #92) +- AND a history log of status changes MUST be maintained +- AND the team MUST have real-time visibility without waiting for the next meeting + +--- + +### Requirement: Meeting Preparation Compliance + +The system SHOULD track whether attendees have reviewed pre-meeting documents and provide preparation compliance analytics. + +**Feature tier**: V1 +**Evidence**: 67% of meeting time is wasted, partially due to unprepared attendees (insight #1). Only 37% of meetings use agendas (external source #319). + +#### Scenario: Track document read receipts + +- GIVEN a meeting package distributed 5 days before the meeting +- WHEN the organizer checks preparation status +- THEN the system MUST show which attendees have opened each document +- AND a preparation compliance rate MUST be calculated as a KPI (user story #339) + +#### Scenario: Reminder for unprepared attendees + +- GIVEN a meeting in 24 hours with 3 attendees who have not read the documents +- WHEN the reminder threshold is reached +- THEN automatic reminders MUST be sent to unprepared attendees (user story #339) + +--- + +### Requirement: Quorum Tracking + +The system MUST provide real-time quorum tracking during meetings, showing present count versus required count, with automatic alerts when quorum is at risk. + +**Feature tier**: V1 +**Evidence**: Gemeentewet Art. 20 requires >50% of seated members present (insight #17). iBabs provides quorum tracking as a key differentiator (external source #97). + +#### Scenario: Real-time quorum display + +- GIVEN a council meeting requiring 16 of 31 members present +- WHEN 18 members are present and 1 leaves +- THEN the quorum display MUST update to 17/16 (quorum met) +- AND if another member leaves (16/16), the display MUST show a warning +- AND if quorum is lost (15/16), the display MUST show a critical alert (user story #342) + +#### Scenario: Attendance analytics per member + +- GIVEN 12 meetings over the past year +- WHEN the secretary views attendance analytics +- THEN attendance rate per member/faction MUST be displayed +- AND late arrivals and early departures MUST be tracked +- AND patterns (e.g., consistently absent on Thursdays) MUST be visible (user story #342) + --- ### Requirement: Meeting Analytics Dashboard -The system MUST provide analytics on meeting efficiency including: average meeting duration, decision throughput (decisions per meeting), time per agenda item vs. allocated time, attendance trends, and cost trends over time. +The system MUST provide analytics on meeting efficiency including: average meeting duration, decision throughput (decisions per meeting), time per agenda item vs. allocated time, attendance trends, cost trends over time, and meeting effectiveness scoring. **Feature tier**: V1 +**Evidence**: 15 essential meeting KPIs identified by Flowtrace (external source #323). 12 highest-impact manager KPIs benchmarked by Worklytics (external source #347). Flowtrace dashboard implementation guide provides reference architecture (external source #349). #### Scenario: View meeting duration trends @@ -110,22 +305,186 @@ The system MUST provide analytics on meeting efficiency including: average meeti - GIVEN analytics data from multiple meetings - WHEN the user views the "Time Allocation Accuracy" report - THEN the system MUST show average allocated vs. actual time grouped by item type (informational, discussion, decision) -- AND recommendations MUST be shown (e.g., "Decision items average 25 min actual vs. 15 min allocated — consider increasing default allocation") +- AND recommendations MUST be shown (e.g., "Decision items average 25 min actual vs. 15 min allocated -- consider increasing default allocation") + +#### Scenario: Personal meeting scorecard + +- GIVEN a manager with meeting history over the past month +- WHEN they view their personal scorecard +- THEN the following KPIs MUST be displayed (user story #331): + - Meetings per week with trend + - Average meeting duration + - Decision rate (decisions per meeting) + - Action item completion rate + - Focus time vs. meeting time ratio +- AND organizational benchmarks MUST be available for comparison (external source #347) + +#### Scenario: Meeting audit report + +- GIVEN a director requesting a quarterly meeting audit +- WHEN the audit report is generated (user story #333) +- THEN it MUST show: + - Agenda compliance rate (% of meetings with agenda) + - Goal achievement rate + - Cost per meeting + - Attendance vs. invited ratio + - Recurring meeting staleness detection +- AND recommendations for meetings to cancel or merge MUST be included + +#### Scenario: Decision throughput analytics + +- GIVEN analytics data across meetings for a governance body +- WHEN the user views decision throughput +- THEN decisions per meeting MUST be calculated +- AND time-to-decision (from proposal to adoption) MUST be tracked +- AND bottleneck states (where decisions stall longest) MUST be highlighted + +--- + +### Requirement: AI-Powered Meeting Transcription and Summaries + +The system SHOULD support automatic meeting transcription with AI-generated summaries, key decision extraction, and action item identification. All processing MUST be self-hosted for GDPR compliance. + +**Feature tier**: V2 +**Evidence**: AI meeting tool usage grew 17x (insight #5). No self-hosted alternative exists (insight #9). Otter.ai achieves 93-95% accuracy. Fireflies and Otter face lawsuits over privacy. + +#### Scenario: Real-time transcription + +- GIVEN a meeting with Talk integration enabled +- WHEN transcription is activated +- THEN the system MUST provide real-time speech-to-text with >90% accuracy (user story #345) +- AND speaker identification MUST be automatic +- AND multi-language support (NL/EN minimum) MUST be available +- AND all data MUST remain within the Nextcloud tenant + +#### Scenario: AI-generated meeting summary + +- GIVEN a completed meeting with transcription +- WHEN the meeting ends +- THEN an AI summary MUST be generated highlighting: key decisions, action items, discussion points (user story #345) +- AND the secretary MUST be able to edit the summary before finalizing +- AND the summary MUST be linked to the meeting record + +--- + +### Requirement: Consent-Based Decision Support + +The system COULD support structured consent-based decision processes for organizations using sociocracy or similar methodologies. + +**Feature tier**: V2 +**Evidence**: Sociocracy For All documents the full consent process (external source #256). Growing adoption in cooperatives and progressive organizations. + +#### Scenario: Run consent rounds with timer + +- GIVEN a proposal ready for consent-based decision +- WHEN the facilitator starts the consent process +- THEN the system MUST support structured rounds (user story #346): + - Proposal presentation (configurable time) + - Quick reactions round (2-3 min per participant) + - Objection harvesting round (timer per participant) + - Integration round (addressing objections) +- AND each participant's position MUST be visually tracked (no objection / objection / pending) +- AND the decision MUST be recorded when all objections are resolved or withdrawn ## User Stories -1. **Secretary tracking action items**: As a board secretary, I want to assign, track, and report on board action items with due dates and owners, so that nothing falls through the cracks between meetings. (Source: intelligence DB #19) +### Critical & Must-Have Stories (from Intelligence DB) + +1. **CEO viewing organizational meeting cost dashboard** (DB #330, priority: must): As a CEO/director, I want to see a real-time dashboard showing total organizational meeting costs, trends, and cost per department, so that I can make data-driven decisions about meeting culture. *AC: Total cost per week/month/quarter, breakdown by team, trend lines, benchmarks.* + +2. **Manager tracking personal meeting KPIs** (DB #331, priority: must): As a manager, I want a personal meeting scorecard showing my KPIs (meetings/week, avg duration, decision rate, action item completion rate, focus time ratio), so that I can optimize my meeting behavior. *AC: KPIs with trends, organizational benchmarks, focus time ratio.* + +3. **Meeting facilitator using agenda timers** (DB #334, priority: must): As a meeting facilitator, I want visible countdown timers per agenda item with configurable time allocations and audio/visual alerts, so that meetings stay on schedule. *AC: Per-item timer, 1-min warning, extend/pause/skip, sub-topic support.* + +4. **Meeting chair tracking speaking balance** (DB #336, priority: must): As a meeting chair, I want real-time visibility into speaking time per participant with balance indicators, so that I can ensure inclusive discussion. *AC: Duration + percentage, balance indicator, gender breakdown, interruption detection, historical trends.* + +5. **Secretary capturing action items** (DB #337, priority: must): As a secretary, I want to capture action items with owner and deadline, and automatically create follow-up tasks, so that meeting outcomes are actioned (currently 44% are not). *AC: Owner + deadline, AI suggestions, CalDAV VTODO, reminders, >90% completion target.* + +6. **Council clerk enforcing speaking time rules** (DB #340, priority: must): As a council clerk, I want configurable speaking time rules per debate type with visible countdown, so that debates stay within allocated time. *AC: Proportional faction allocation, max 2 terms, interruption tracking, post-debate report.* + +7. **Meeting secretary tracking quorum** (DB #342, priority: must): As a meeting secretary, I want real-time quorum tracking with automatic alerts, so that meetings are legally valid. *AC: Real-time present count, risk alerts, attendance history, configurable requirements.* + +8. **Board secretary tracking action items** (DB #19, priority: must): As a board secretary, I want to assign, track, and report on board action items with due dates and owners, so that nothing falls through the cracks. *AC: Assignment with notifications, status tracking, automatic rollover, overdue dashboard.* + +9. **Secretary auto-creating tasks from minutes** (DB #1834, priority: must): As a secretary, I want action items in meeting minutes to automatically become CalDAV VTODO tasks assigned to the responsible person. *AC: VTODO creation, linked to decision/meeting, assignee notification.* + +10. **Committee chair managing speaking order** (DB #159, priority: must): As a commissievoorzitter, I want to manage the speaking order for committee members and insprekers, so that everyone gets a fair opportunity. + +11. **Council chair managing debate speaking time** (DB #163, priority: must): As a voorzitter, I want to track and display remaining speaking time per faction during debates, so that all factions get fair representation. + +### Should-Have Stories + +12. **Director generating meeting audit reports** (DB #333, priority: should): As a director, I want periodic meeting audit reports showing agenda compliance, goal achievement, costs, and attendance, so I can eliminate waste. + +13. **Council secretary tracking BOB phases** (DB #341, priority: should): As a council secretary, I want to tag agenda items with BOB phases and track progression across meetings, so that decision-making is transparent. + +14. **Secretary generating AI transcription** (DB #345, priority: should): As a secretary, I want automatic meeting transcription with AI summaries, so that minutes creation is automated. + +15. **Meeting organizer tracking preparation compliance** (DB #339, priority: should): As a meeting organizer, I want to track whether attendees have read pre-meeting documents. + +16. **Meeting analytics as organizational capability** (DB #1201, priority: should): As an organizational leader, I want meeting analytics capabilities so that effectiveness can be measured and improved. + +### Could-Have Stories + +17. **Live meeting cost ticker display** (DB #335, priority: could): As a meeting organizer, I want a live cost ticker during meetings so participants are aware of the financial investment. + +18. **Consent-based decision support** (DB #346, priority: could): As a meeting facilitator, I want consent-based decision processes with structured rounds and timer per round. + +19. **Action item extraction from transcription** (DB #1170, priority: could): As a project manager, I want action item extraction capabilities from meeting recordings. + +### Related Integration Stories -2. **Secretary preparing meeting package**: As secretary, I want to prepare a digital meeting package with agenda, previous minutes, action items, and new documents so that all board members arrive prepared. (Source: intelligence DB #65) +20. **Secretary preparing digital meeting package** (DB #65, priority: high): As secretary, I want to prepare a digital meeting package with agenda, previous minutes, action items, and new documents. *AC: Digital package, read confirmations, distributed X days before.* -3. **Chair tracking decision implementation**: As chair, I want to track the implementation status of ALV decisions with responsible persons and deadlines so that I can report progress at the next ALV. (Source: intelligence DB #77) +21. **MT assistant assigning action items** (DB #91, priority: high): As a management assistant, I want to assign action items to specific MT members with deadlines and track completion. *AC: Linked to decision, acceptance notification, deadline reminders, status dashboard.* ## Acceptance Criteria -- Agenda item timers display countdown with visual alerts on expiry -- Chair can extend, pause, or skip timers -- Speaking time is tracked per participant with configurable limits +- Agenda item timers display countdown with visual alerts at 1-minute warning and on expiry +- Chair can extend (5/10 min), pause, or skip timers +- Sub-topic timeboxing is supported within parent item timers +- Speaking time is tracked per participant with duration, percentage, and balance indicators +- Gender breakdown of speaking time is available (65% improvement evidence) - Speaker queue supports request-to-speak and chair reordering -- Meeting cost calculator shows running cost based on participant rates -- Analytics dashboard shows duration trends, decision throughput, and cost breakdowns +- Speaking time rules are configurable per debate type (proportional, fixed, unlimited) +- Faction-based proportional allocation is supported for council debates +- BOB model phases are trackable per agenda item across meetings +- Meeting cost calculator shows running cost based on participant rates (updated per second) +- Cost threshold alerts warn when budget is exceeded +- Organizational meeting cost dashboard shows totals, trends, and team breakdowns +- Action items captured with owner, deadline, and linked to agenda item/decision +- CalDAV VTODO tasks auto-created from action items via _todos metadata +- Action item completion rate tracked per person, team, and meeting (target >90%) +- Incomplete action items automatically roll over to next meeting agenda +- Real-time quorum tracking with alerts when quorum is at risk +- Attendance analytics show per-member rates, late arrivals, and patterns +- Meeting preparation compliance tracked via document read receipts +- Analytics dashboard shows 15 KPIs: duration trends, decision throughput, cost, attendance, completion rates +- Personal meeting scorecard with organizational benchmarks +- Meeting audit reports identify staleness, waste, and merge opportunities - All timing data is recorded for post-meeting analytics +- AI transcription (V2) processes data self-hosted for GDPR compliance + +## External Sources + +| # | Type | Title | Key Insight | +|---|------|-------|-------------| +| 319 | research | State of Meetings Report 2024 (Fellow) | 78% too many meetings, AI grew 17x, only 37% use agendas | +| 321 | research | Microsoft Work Trend Index | Interrupted every 2 min, 60% time in communication, 60% ad hoc meetings | +| 325 | research | $37B/Year in Unnecessary Meetings | $25K/employee/year, $100M/year large companies | +| 320 | research | 45 Meeting Statistics 2025 (Fellow) | 67% say clear agenda most important, managers 13hrs/week | +| 342 | research | Action Item Completion Rate | 44% never completed, 71% meetings fail objectives | +| 323 | product | 15 Meeting KPIs (Flowtrace) | Decision rate, action item completion, attendance analytics | +| 347 | research | 12 Manager Scorecard KPIs (Worklytics) | Meeting hours/week, 1:1 frequency, focus time ratio | +| 349 | product | Meeting Analytics Dashboard Guide (Flowtrace) | Executive tiles, team investment view, meeting audit | +| 322 | product | Flowtrace Meeting Analytics | 2.2M meetings benchmarked, real-time cost, behavioral nudges | +| 337 | methodology | BOB-model: Beeldvorming/Oordeelsvorming/Besluitvorming | Dutch 3-phase decision model for municipalities | +| 339 | regulation | Reglement van Orde gemeenteraad 2023 | Max 5 min speaking, proportional allocation, max 2 terms | +| 256 | documentation | Consent Decision Making (Sociocracy For All) | Structured rounds: proposal, reactions, objections, integration | +| 292 | legal | Gemeentewet Quorum Art. 20/29/30 | Municipal quorum and voting rules | +| 273 | documentation | Gemeentewet Art. 32 | Rollcall voting, oral votes, tie-breaking | +| 51 | comparison | Best Meeting Software for Local Governments | OpenMeeting, Civica, OnBoard, CivicPlus, eScribe | +| 70 | blog | Civica Modern.Gov | 50-70% reduction in admin time, 300+ UK councils | +| 97 | case-study | iBabs for Local Government | Quorum tracking, RSVP, voting, ISO/GDPR certified | +| 106 | product | Decisions.com for Microsoft Teams | Smart timer, AI agenda, decision capture, engagement score | +| 372 | review | iBabs Reviews (Capterra) | 4.6/5, easy to use, system dependency risk during meetings | diff --git a/openspec/specs/meeting-management/spec.md b/openspec/specs/meeting-management/spec.md index 47f5fbf..a18d2bd 100644 --- a/openspec/specs/meeting-management/spec.md +++ b/openspec/specs/meeting-management/spec.md @@ -4,28 +4,35 @@ status: idea # Meeting Management Specification +**Status**: idea +**Standards**: Schema.org (`Event`, `EventAttendanceModeEnumeration`), Akoma Ntoso (`debate`, `session`), OpenRaadsinformatie (`Vergadering`, `Zitting`), Gemeentewet, BW Boek 2, Provinciewet, Waterschapswet, Woo, Digitoegankelijk (EN 301 549) +**Feature tier**: MVP + ## Purpose -Meeting management covers the full lifecycle of governance meetings: creation, scheduling, attendance tracking, quorum verification, and meeting conduct. Meetings are the primary container for agenda items, decisions, and minutes. The system supports physical, digital, and hybrid meeting formats for governance bodies, associations (ALV/ledenraad), corporate boards, and operational teams. +Meeting management covers the full lifecycle of governance meetings: creation, scheduling, attendance tracking, quorum verification, and meeting conduct. Meetings are the primary container for agenda items, decisions, and minutes. The system supports physical, digital, and hybrid meeting formats for governance bodies, associations (ALV/ledenraad), corporate boards, and operational teams. Market research shows $541B is wasted on meetings globally (insight #1), AI meeting tool usage grew 17x in 2024 (insight #5), and 78% of workers say they have too many meetings. No self-hosted AI meeting solution exists (insight #9). -**Standards**: Schema.org (`Event`, `EventAttendanceModeEnumeration`), Akoma Ntoso (`debate`, `session`), OpenRaadsinformatie (`Vergadering`, `Zitting`) -**Feature tier**: MVP -**Legal reference**: BW 2:38 (association ALV), Gemeentewet 17-20 (council meetings), BW 2:227 (BV shareholder meeting) +**Legal reference**: BW 2:38 (association ALV), Gemeentewet 17-20 (council meetings), BW 2:227 (BV shareholder meeting), Provinciewet (provincial meetings), Waterschapswet (water board meetings) ## Data Model -See [ARCHITECTURE.md](../../docs/ARCHITECTURE.md) for the full Meeting entity definition including property tables, Schema.org mappings, and OpenRaadsinformatie alignment. +See [ARCHITECTURE.md](../../architecture/README.md) for the full Meeting entity definition including property tables, Schema.org mappings, and OpenRaadsinformatie alignment. + +| Entity | Schema.org Type | Key Properties | +|--------|----------------|----------------| +| Meeting | `schema:Event` | title, startDate, endDate, location, virtualLocation, eventAttendanceMode, body, meetingType, status | +| Attendance | `schema:JoinAction` | participant, meeting, attendanceType (present/remote/proxy), checkInTime | +| Proxy | `schema:AuthorizeAction` | grantor, grantee, meeting, scope | +| MeetingRecording | `schema:VideoObject` | meeting, contentUrl, duration, captions | ## Requirements --- -### Requirement: Meeting Creation and Scheduling +### Requirement: Meeting Creation and Scheduling [MVP] The system MUST support creating meetings with a title, date/time, location (physical/digital/hybrid), governing body, and meeting type. Meetings MUST be stored as OpenRegister objects in the `decidesk` register using the `meeting` schema. The system MUST support scheduling recurring meetings. -**Feature tier**: MVP - #### Scenario: Create a board meeting with physical location - GIVEN a user with meeting management access @@ -47,15 +54,22 @@ The system MUST support creating meetings with a title, date/time, location (phy - WHEN they create a meeting with recurrence "monthly, every 2nd Tuesday at 14:00" - THEN the system MUST generate individual meeting instances for the specified period - AND each instance MUST be independently editable +- AND each instance MUST automatically get a new agenda object linked to it + +#### Scenario: Sync meetings to Nextcloud Calendar via CalDAV + +- GIVEN a meeting is created in Decidesk +- WHEN the meeting is saved +- THEN it MUST appear in the user's Nextcloud Calendar as a virtual calendar via OpenRegister _calendar metadata +- AND CalDAV sync MUST work to any device (insight #26) --- -### Requirement: Meeting Convocation and Notice +### Requirement: Meeting Convocation and Notice [MVP] The system MUST support sending meeting convocations (uitnodigingen) to all members of the governing body within configurable notice periods. The system MUST track delivery status per recipient. -**Feature tier**: MVP -**Legal reference**: BW 2:225 (42-day notice for NV, 15-day for BV), BW 2:38 (ALV notice per statutes) +**Legal reference**: BW 2:225 (42-day notice for NV, 15-day for BV), BW 2:38 (ALV notice per statutes), BW 2:41 (extraordinary ALV within 4 weeks) #### Scenario: Send ALV convocation within statutory deadline @@ -73,14 +87,29 @@ The system MUST support sending meeting convocations (uitnodigingen) to all memb - AND links to all supporting documents MUST be included - AND recipients MUST be able to access documents via the member portal +#### Scenario: Send AGM convocation with 42-day notice for NV + +- GIVEN an NV shareholder meeting scheduled for 2026-09-15 +- WHEN the secretary prepares the convocation +- THEN the system MUST enforce the 42-day minimum notice period (BW 2:225) +- AND the system MUST warn if the convocation is being sent too late +- AND the convocation MUST include all resolution proposals + +#### Scenario: Handle extraordinary ALV request from members + +- GIVEN 10%+ of members have signed a request for an extraordinary ALV +- WHEN the secretary receives the validated request +- THEN the system MUST create an extraordinary meeting within the 4-week deadline (BW 2:41) +- AND members who signed the request MUST be notified of the scheduled date +- AND if the board does not comply, the system MUST warn that members may convene themselves + --- -### Requirement: Attendance and Quorum Tracking +### Requirement: Attendance and Quorum Tracking [MVP] The system MUST track attendance for each meeting and automatically calculate quorum based on the governing body's rules. Proxy votes (volmachten) MUST count toward quorum. The system MUST prevent voting from starting until quorum is confirmed. -**Feature tier**: MVP -**Legal reference**: BW 2:38 (ALV quorum), Gemeentewet 20 (council quorum) +**Legal reference**: BW 2:38 (ALV quorum), Gemeentewet Art. 20 (council quorum >50% of seated members), Art. 29 (second meeting without quorum) #### Scenario: Register attendance and verify quorum is met @@ -89,7 +118,7 @@ The system MUST track attendance for each meeting and automatically calculate qu - THEN the system MUST show quorum status as "met" with 10/15 (67%) - AND voting MUST be enabled for the meeting -#### Scenario: Quorum not met — meeting cannot proceed to voting +#### Scenario: Quorum not met -- meeting cannot proceed to voting - GIVEN a meeting for a body with 15 members and quorum requirement of 50%+1 - WHEN only 5 members have checked in @@ -104,13 +133,57 @@ The system MUST track attendance for each meeting and automatically calculate qu - THEN both the proxy holder and the represented member MUST count toward quorum - AND the proxy relationship MUST be visible in the attendance list +#### Scenario: Second meeting proceeds without quorum (Gemeentewet Art. 29) + +- GIVEN a council meeting that was adjourned due to lack of quorum +- WHEN a second meeting is called for the same subject +- THEN the system MUST allow the meeting to proceed regardless of attendance count per Gemeentewet Art. 29 +- AND this exception MUST be explicitly flagged in the meeting record + +#### Scenario: Verify member voting rights + +- GIVEN an ALV with members of different categories +- WHEN members check in +- THEN the system MUST verify each member's voting rights (paid-up membership, correct category) +- AND only eligible members MUST count toward quorum +- AND non-voting members MUST be marked separately in the attendance list + +#### Scenario: Digital identity verification for remote participants + +- GIVEN a hybrid meeting with remote participants +- WHEN a remote member joins +- THEN the system MUST verify their identity through a configured authentication method +- AND their attendance MUST be recorded as "remote" with verification timestamp +- AND they MUST count toward quorum equally with physical attendees + --- -### Requirement: Meeting List and Calendar View +### Requirement: Proxy Vote Management [MVP] -The system MUST provide a list view and calendar view of meetings. Users MUST be able to filter by body, status, date range, and meeting type. +The system MUST support digital proxy (volmacht) management where members grant voting authority to another member or representative. -**Feature tier**: MVP +**Legal reference**: BW 2:38 (proxy allowed if statutes permit), statutes may limit proxies per person + +#### Scenario: Grant proxy vote digitally + +- GIVEN a member who cannot attend the ALV +- WHEN they grant a proxy to another member via the platform +- THEN the proxy MUST be digitally signed and recorded +- AND the proxy holder MUST receive notification of the granted proxy +- AND the system MUST enforce any statutory limits on proxies per person + +#### Scenario: Revoke proxy before meeting + +- GIVEN a member who previously granted a proxy +- WHEN they decide to attend the meeting themselves +- THEN they MUST be able to revoke the proxy before the meeting starts +- AND the former proxy holder MUST be notified of the revocation + +--- + +### Requirement: Meeting List and Calendar View [MVP] + +The system MUST provide a list view and calendar view of meetings. Users MUST be able to filter by body, status, date range, and meeting type. #### Scenario: View upcoming meetings in calendar format @@ -119,13 +192,20 @@ The system MUST provide a list view and calendar view of meetings. Users MUST be - THEN meetings MUST be displayed on their scheduled dates - AND each meeting MUST show title, time, body, and status indicator +#### Scenario: Filter meetings by body and type + +- GIVEN meetings exist for multiple bodies (council, committees, board) +- WHEN the user filters by body "Municipal Council" and type "regular" +- THEN only regular council meetings MUST be displayed +- AND the filter MUST persist across navigation + --- -### Requirement: Hybrid and Digital Meeting Support +### Requirement: Hybrid and Digital Meeting Support [MVP] The system MUST support fully digital meetings with identity verification, live participation (audio/video link), and real-time voting. Remote participants MUST have equal participation rights. -**Feature tier**: MVP +**Legal reference**: WDAV (Wet Digitale Algemene Vergadering) passed Tweede Kamer Dec 2025, enables fully digital meetings for associations if statutes permit. WBTR full compliance required by July 2026 (insight #20). #### Scenario: Join meeting remotely with full participation rights @@ -135,24 +215,600 @@ The system MUST support fully digital meetings with identity verification, live - AND their attendance MUST be recorded as "remote" - AND they MUST count toward quorum -## User Stories +#### Scenario: Configure meeting for fully digital mode + +- GIVEN an association whose statutes permit digital meetings (post-WDAV) +- WHEN the secretary creates a fully digital meeting +- THEN the `eventAttendanceMode` MUST be set to `schema:OnlineEventAttendanceMode` +- AND identity verification MUST be required for all participants +- AND the system MUST ensure all participants can follow debates, ask questions, and cast votes (BW 2:227a requirements) + +#### Scenario: Integrate with Nextcloud Talk for meeting audio/video + +- GIVEN a digital meeting +- WHEN the secretary configures the meeting +- THEN the system SHOULD offer Nextcloud Talk as the default video conference provider +- AND a Talk conversation MUST be auto-created and linked to the meeting (insight #27) + +--- + +### Requirement: Meeting Conduct and Speaking Order [MVP] + +The system MUST support managing meeting proceedings including speaking order, time tracking, and agenda item progression. + +**Legal reference**: Gemeentewet -- Reglement van Orde defines speaking rules. Standard rules: max 5 min speaking time, max 2 speaking terms per topic per faction (source #339). + +#### Scenario: Manage speaking order during committee meeting + +- GIVEN a committee meeting in progress on a discussion item +- WHEN members request to speak +- THEN the chair MUST be able to manage the speaking list +- AND the system MUST track speaking time per member +- AND time alerts MUST fire when the allocated time is exceeded + +#### Scenario: Register citizen to speak at committee meeting (inspreekrecht) + +- GIVEN an upcoming committee meeting with public agenda items +- WHEN a citizen registers online to speak about an agenda item +- THEN their registration MUST be recorded with name, topic, and contact details +- AND the committee secretary MUST be notified +- AND the citizen MUST receive a confirmation with time slot and instructions + +#### Scenario: Track speaking time for DEI insights + +- GIVEN a meeting in progress with speaking time tracking enabled +- WHEN the meeting concludes +- THEN the system MUST provide analytics on speaking time distribution +- AND the system SHOULD highlight imbalances (insight #24: tracking speaking time increased women's participation by 65%) + +--- + +### Requirement: Meeting Type Configuration and Seeding [MVP] + +The system MUST support configurable MeetingType entities that define the default structure for meetings. When a meeting is created from a MeetingType, the system MUST automatically seed the meeting with default agenda items, quorum rules, voting methods, and speaking time rules as defined by the type. MeetingTypes are stored as OpenRegister objects, not hardcoded enums. Administrators MUST be able to create, modify, and archive MeetingTypes. + +**Cross-reference**: See agenda-management spec -- MeetingType entity defines `defaultAgendaItems`, `quorumRule`, `votingMethod`, `speakingTimeRules`. + +#### Scenario: Create meeting from council meeting type + +- GIVEN a MeetingType "Raadsvergadering" with default agenda items (Opening, Vaststellen agenda, Vaststellen notulen, Hamerstukken, Bespreekstukken, Moties/Amendementen, Rondvraag, Sluiting), quorum >50%, and default open voting +- WHEN the griffier creates a new meeting from this type +- THEN the meeting MUST be pre-populated with all default agenda items from the MeetingType +- AND the quorum rule MUST be set to >50% of seated members +- AND the default voting method MUST be set to open vote +- AND the griffier MUST be able to add, remove, or reorder items after seeding + +#### Scenario: Create meeting from ALV meeting type + +- GIVEN a MeetingType "ALV" with default agenda items (Opening, Vaststellen notulen, Jaarverslag, Jaarrekening, Verslag kascommissie, Bestuursverkiezing, WVTTK, Sluiting), quorum per statutes, and default open voting with secret ballot for elections +- WHEN the secretary creates a new ALV meeting from this type +- THEN the meeting MUST be pre-populated with all statutory agenda items +- AND the quorum rule MUST be inherited from the MeetingType configuration +- AND agenda items marked as elections MUST default to secret ballot voting method +- AND removed required items MUST trigger a compliance warning + +#### Scenario: Administrator creates a custom meeting type + +- GIVEN an administrator who wants to create a new meeting type for steering committee meetings +- WHEN they define a MeetingType with name "Stuurgroep", default items (Opening, Projectstatus, Risico-overzicht, Beslispunten, Actiepunten, Sluiting), quorum 50%+1, and default open voting +- THEN the system MUST save the MeetingType as an OpenRegister object +- AND the type MUST be available in the "Create Meeting" dialog +- AND existing meetings MUST NOT be affected by changes to the MeetingType + +--- + +### Requirement: Live Meeting Page [MVP] + +The system MUST provide a real-time meeting page for all participants during an active meeting. The live meeting page MUST show the current agenda item, its documents, active vote (if any), the speaker queue, and meeting progress. The page MUST update in real-time without manual refresh. + +#### Scenario: Participant views live meeting page during session + +- GIVEN a meeting in progress with agenda item 4 of 8 active +- WHEN a participant opens the live meeting page +- THEN they MUST see the current agenda item title, description, and attached documents +- AND a progress indicator MUST show "Item 4 of 8" with time elapsed +- AND if a vote is active on the current item, the voting panel MUST be displayed +- AND the speaker queue for the current item MUST be visible + +#### Scenario: Live page updates when chair advances agenda + +- GIVEN a participant viewing the live meeting page +- WHEN the chair advances from agenda item 4 to agenda item 5 +- THEN the page MUST update in real-time to show item 5's details +- AND if item 5 has a decision point (linked motion/vote), the voting interface MUST activate automatically +- AND the speaker queue MUST reset to show speakers registered for item 5 + +#### Scenario: Remote participant follows meeting via live page + +- GIVEN a hybrid meeting with remote participants +- WHEN a remote member accesses the live meeting page +- THEN they MUST see the same real-time information as in-person attendees +- AND they MUST be able to register as a speaker, cast votes, and view documents +- AND their participation MUST be logged with "remote" attendance mode + +--- + +### Requirement: Calendar Integration (CalDAV) [MVP] + +The system MUST integrate meetings with Nextcloud Calendar via OpenRegister's RegisterCalendarProvider. Meetings MUST appear as CalDAV events in a virtual calendar. Recurring meeting series MUST generate individual CalDAV events. Meeting invitations MUST be sent as iCalendar invitations to all body members. + +**Cross-reference**: OpenRegister _calendar metadata provides the CalDAV virtual calendar backend. + +#### Scenario: Meeting appears in Nextcloud Calendar automatically + +- GIVEN a meeting "Board Meeting Q2" scheduled for 2026-07-10 14:00-16:00 +- WHEN the meeting is saved in Decidesk +- THEN it MUST appear in the Decidesk virtual calendar in Nextcloud Calendar +- AND the calendar event MUST include: title, start/end time, location/virtual link, and a link back to the Decidesk meeting page +- AND the event MUST sync to any CalDAV client (mobile, desktop) + +#### Scenario: Recurring meeting series creates individual calendar events + +- GIVEN a MeetingType "MT Weekly" with recurrence "every Tuesday at 10:00" +- WHEN the recurring series is created +- THEN each individual meeting instance MUST appear as a separate CalDAV event +- AND modifying one instance (e.g., rescheduling) MUST NOT affect other instances +- AND cancelling one instance MUST update the corresponding CalDAV event + +#### Scenario: Send meeting invitations as iCalendar + +- GIVEN a meeting with 12 body members +- WHEN the secretary sends the meeting convocation +- THEN each member MUST receive an iCalendar (.ics) invitation via Nextcloud notification +- AND accepting the invitation MUST update the member's attendance RSVP +- AND the system MUST track invitation delivery and RSVP status per member + +--- -1. **Secretary sending ALV convocation**: As secretary, I want to send the ALV convocation to all voting members via their preferred channel so that I can prove all members were properly notified within the statutory deadline. (Source: intelligence DB #46) +### Requirement: Speaker Queue Management [MVP] -2. **Member receiving invitation**: As a member, I want to receive the ALV invitation with the complete agenda and supporting documents so that I can prepare for the meeting and decide whether to attend. (Source: intelligence DB #47) +The system MUST support a speaker queue where participants can register to speak on the current agenda item. The chair MUST be able to grant the floor, skip speakers, and manage the queue order. Speaking time MUST be tracked per speaker with configurable time limits. -3. **Secretary registering attendance**: As secretary, I want to register member attendance (physical and digital) and automatically calculate quorum including proxy votes so that I can confirm the meeting is valid. (Source: intelligence DB #55) +#### Scenario: Member registers to speak on current agenda item -4. **Member joining remotely**: As a member, I want to join the ALV remotely via video/audio with the ability to speak, vote, and submit motions so that distance is not a barrier to participation. (Source: intelligence DB #64) +- GIVEN a meeting in progress on agenda item "Budget Discussion" +- WHEN a member clicks "Request to speak" +- THEN they MUST be added to the speaker queue for the current item +- AND the chair MUST see the updated queue with the member's name and registration time +- AND the member MUST see their position in the queue + +#### Scenario: Chair grants the floor and tracks speaking time + +- GIVEN a speaker queue with 3 registered speakers and a 5-minute time limit per speaker +- WHEN the chair grants the floor to the first speaker +- THEN a countdown timer MUST start (5:00) +- AND the current speaker MUST be highlighted in the queue +- AND when time expires, an alert MUST notify the chair and speaker +- AND the chair MUST be able to extend time or move to the next speaker + +#### Scenario: Chair reorders or removes speakers from the queue + +- GIVEN a speaker queue with 5 registered speakers +- WHEN the chair needs to prioritize a specific speaker (e.g., the motion proposer gets to speak first) +- THEN the chair MUST be able to drag-and-drop reorder the queue +- AND the chair MUST be able to remove a speaker who withdraws +- AND all participants MUST see the updated queue in real-time + +#### Scenario: Track speaking time analytics per meeting + +- GIVEN a completed meeting with speaking time tracked per participant +- WHEN the meeting analytics are generated +- THEN the system MUST show total speaking time per participant, average time per intervention, and number of interventions +- AND the system SHOULD highlight distribution imbalances for DEI insights + +--- + +### Requirement: Meeting Recording and Webcasting [V1] + +The system SHOULD support recording meetings (audio/video) and publishing them with searchable indexes linked to agenda items. + +**Evidence**: Citizens and journalists follow meetings via live webcast (journey #84). Meeting recordings must be captioned for accessibility (DB #185). + +#### Scenario: Record meeting and link to agenda items + +- GIVEN a council meeting with webcasting enabled +- WHEN the meeting is recorded +- THEN the recording MUST be segmented by agenda item with timestamp markers +- AND citizens MUST be able to jump to specific agenda items in the recording + +#### Scenario: Auto-transcribe meeting recordings + +- GIVEN a recorded meeting +- WHEN transcription is triggered +- THEN the system MUST use self-hosted speech-to-text (privacy-first) +- AND the transcript MUST be searchable and linked to agenda items +- AND captions MUST be generated for accessibility (WCAG AA compliance) + +--- + +### Requirement: Meeting Templates [V1] + +The system SHOULD support meeting templates for recurring meeting types (e.g., ALV template with required statutory items, MT template with standing items). + +#### Scenario: Create meeting from ALV template + +- GIVEN a meeting template "ALV" with required statutory items (opening, annual report, financial statements, kascommissie report, board elections, any other business, closing) +- WHEN the secretary creates a new ALV meeting from the template +- THEN the agenda MUST be pre-populated with all required items +- AND the secretary MUST be able to add additional items + +#### Scenario: Create meeting from MT template + +- GIVEN a meeting template "MT Weekly" with standing items (action item review, decisions pending, department updates) +- WHEN a new meeting instance is created from the recurring schedule +- THEN the standing items MUST be pre-populated +- AND open action items from previous meetings MUST be automatically carried over + +--- + +### Requirement: Meeting Minutes and Action Items [MVP] + +The system MUST support creating meeting minutes linked to agenda items and extracting action items with owners and deadlines. + +#### Scenario: Generate minutes from real-time notes + +- GIVEN a meeting in progress with notes captured per agenda item +- WHEN the secretary generates the meeting minutes +- THEN the minutes MUST be structured by agenda item +- AND decisions, voting results, and action items MUST be highlighted +- AND the minutes MUST be available for review within hours, not days + +#### Scenario: Auto-create tasks from action items + +- GIVEN minutes with action items assigned to specific people +- WHEN the minutes are finalized +- THEN each action item MUST automatically become a CalDAV VTODO task via OpenRegister _todos metadata +- AND the task MUST be assigned to the responsible person with the deadline +- AND completion status MUST sync back to the meeting record + +#### Scenario: Submit draft minutes for approval + +- GIVEN draft minutes prepared by the griffier +- WHEN submitted for approval at the next meeting +- THEN tracked corrections MUST be visible +- AND the approval process MUST be transparent with version history + +--- + +### Requirement: Meeting Notifications [MVP] + +The system MUST send notifications for meeting lifecycle events to relevant stakeholders. + +#### Scenario: Notify members of upcoming meeting + +- GIVEN a meeting scheduled for next week +- WHEN the configurable reminder period is reached (e.g., 7 days, 1 day, 1 hour before) +- THEN all body members MUST receive a Nextcloud notification +- AND the notification MUST include meeting title, date, location/link, and agenda link +- AND email notifications MUST be sent to external stakeholders (insight #28) + +#### Scenario: Notify when meeting documents are published + +- GIVEN a meeting with documents just published +- WHEN the documents are made available +- THEN all meeting participants MUST be notified +- AND the system SHOULD track which members have opened the documents (DB #1848) + +--- + +### Requirement: Meeting Cost and Efficiency Analytics [V1] + +The system SHOULD track meeting efficiency metrics based on evidence that $37B/year is wasted on unnecessary meetings (source #325). + +**Evidence**: 67% of meeting time is wasted (HBR), meeting decision rate and action item completion are key KPIs (source #323), 44% of action items are never completed (source #342). + +#### Scenario: Calculate meeting cost in real-time + +- GIVEN a meeting in progress with known attendee count +- WHEN the meeting is ongoing +- THEN the system SHOULD display a running cost estimate based on attendee count and configurable hourly rates +- AND historical meeting cost data MUST be available for analytics + +#### Scenario: Generate periodic meeting audit report + +- GIVEN a set of meetings over a quarter +- WHEN the director requests a meeting audit +- THEN the system MUST produce: meetings per week/person, average duration, decision rate, action item completion rate, attendance rate, agenda adherence +- AND meetings without agendas MUST be flagged (only 37% of meetings use agendas -- source #319) + +--- + +### Requirement: No-Meeting Days and Focus Time [V1] + +The system SHOULD support configurable no-meeting days and focus time blocks. + +#### Scenario: Configure and enforce no-meeting days + +- GIVEN an organization that designates Wednesdays as no-meeting days +- WHEN a user attempts to schedule a meeting on Wednesday +- THEN the system MUST display a warning +- AND compliance tracking MUST show whether no-meeting days are being respected + +--- + +### Requirement: Meeting Document Read Tracking [V1] + +The system SHOULD track whether meeting participants have read the distributed documents. + +**Evidence**: DB #1847, #1848, #1849 -- chairs want to know if members are prepared + +#### Scenario: Track document read confirmation + +- GIVEN a meeting with distributed documents +- WHEN members open and review the documents +- THEN the system MUST track read/unread status per member per document +- AND the chair MUST be able to see preparation compliance before the meeting + +--- + +### Requirement: Meeting Accessibility [MVP] + +The system MUST comply with Digitoegankelijk (EN 301 549 with WCAG 2.1) for all meeting interfaces. + +#### Scenario: Accessible meeting interface for screen readers + +- GIVEN a user with a screen reader accessing the meeting view +- WHEN they navigate the agenda, attendance list, and voting interface +- THEN all elements MUST be properly labeled with ARIA attributes +- AND keyboard navigation MUST be fully functional +- AND contrast ratios MUST meet WCAG AA standards + +#### Scenario: Add captions to meeting recordings + +- GIVEN a published meeting recording +- WHEN a hearing-impaired citizen accesses it +- THEN accurate captions MUST be available +- AND captions MUST be synchronised with the audio track + +--- + +### Requirement: Meeting Data Export and Interoperability [MVP] + +The system MUST export meetings in standardized formats for interoperability. + +#### Scenario: Export meeting as OpenRaadsinformatie Vergadering/Zitting + +- GIVEN a completed council meeting +- WHEN the system exports the meeting data +- THEN the export MUST conform to the OpenRaadsinformatie `Vergadering`/`Zitting` schema +- AND attendance, decisions, and linked documents MUST be included + +#### Scenario: Export meeting to iCalendar format + +- GIVEN a meeting with date, time, location, and agenda +- WHEN a user exports the meeting +- THEN the system MUST produce a valid .ics file with all meeting details +- AND the file MUST be importable into any calendar application + +--- -5. **Secretary handling extraordinary meeting request**: As secretary, I want to verify that an extraordinary ALV request is valid (signed by 10%+ of members) and convene the meeting within 4 weeks so that we comply with BW 2:41. (Source: intelligence DB #48) +## User Stories (from intelligence database) + +### Legislative Domain + +1. As a griffier, I want to create a meeting agenda by selecting and ordering proposals from the backlog so that council members and the public can see what will be discussed. (DB #136) +2. As a griffier, I want to publish the complete agenda with all accompanying documents in one action so that everyone can access everything they need. (DB #138) +3. As a voorzitter, I want to classify agenda items as hamerstuk or bespreekstuk so that meeting time is used efficiently. (DB #158) +4. As a burger, I want to register online to speak at a committee meeting about an agenda item that affects me so that my perspective is heard. (DB #160) +5. As a commissiegriffier, I want meetings to be automatically transcribed using speech-to-text so that I can focus on key points. (DB #173) +6. As a griffier, I want to submit draft minutes for approval at the next meeting with tracked corrections. (DB #177) +7. As an archivaris, I want to verify that all council meeting records are complete in the archive. (DB #183) +8. As a toegankelijkheidsmedewerker, I want meeting recordings to have accurate captions for hearing-impaired citizens. (DB #185) +9. As a dijkgraaf, I want to chair water board general assembly meetings with proper procedures. (DB #103, journey: Water Board General Assembly Meeting) +10. As a burger, I want to follow council meetings via live webcast and track which item is being discussed. (DB #84, journey: Live Meeting Following) + +### Association Domain + +11. As a secretary, I want to send the ALV convocation to all voting members via their preferred channel so that I can prove proper notification within the statutory deadline. (DB #46) +12. As a member, I want to receive the ALV invitation with the complete agenda and supporting documents so that I can prepare for the meeting. (DB #47) +13. As a secretary, I want to verify that an extraordinary ALV request is valid (signed by 10%+ of members) and convene within 4 weeks per BW 2:41. (DB #48) +14. As a secretary, I want to register member attendance (physical and digital) and automatically calculate quorum including proxy votes. (DB #55) +15. As a member, I want to join the ALV remotely via video/audio with ability to speak, vote, and submit motions. (DB #64) +16. As a secretary, I want to prepare a digital meeting package with agenda, previous minutes, action items, and new documents. (DB #65) +17. As a member who cannot attend, I want to grant a proxy to another member digitally. (DB #63) +18. As a cooperative member, I want to participate in the cooperative ALV with proper consideration of liability structure (UA/BA/WA). (DB #31, journey: Cooperative Member Meeting) +19. As a ledenraad member, I want to review the agenda and consult my constituency before the council meeting. (DB #82) + +### Corporate Governance Domain + +20. As a board secretary, I want to create and manage the AGM agenda with drag-and-drop resolution ordering within statutory deadlines. (DB #1) +21. As a board secretary, I want to distribute convocation notices to all shareholders via their preferred channel meeting the 42-day (NV) or 15-day (BV) deadline. (DB #2) +22. As a shareholder, I want to access all AGM documents through a secure online portal. (DB #3) +23. As a board secretary, I want to configure a hybrid or fully digital AGM with identity verification, live voting, and Q&A. (DB #13) +24. As a board secretary, I want to assemble board packs from multiple sources into a structured, indexed package. (DB #17) +25. As a supervisory board member, I want to access the board pack on my tablet with offline capability. (DB #18) +26. As a board secretary, I want to assign, track, and report on board action items with due dates and owners. (DB #19) +27. As a notary, I want secure access to the meeting agenda, attendee list, and voting results for accurate notarial minutes. (DB #12) + +### Corporate Operations Domain + +28. As a management assistant, I want to compile submitted agenda items into a structured agenda and distribute the complete package to all MT members. (DB #88) +29. As a secretary, I want to record decisions in real-time during the MT meeting with a structured format. (DB #89) +30. As a management assistant, I want to generate structured minutes from notes and decisions captured during the meeting. (DB #93) +31. As an MT member, I want to update the status of my action items directly from the platform. (DB #92) +32. As a project manager, I want to prepare a steering committee meeting with project status, decision items, and risk overview. (DB #108) +33. As a meeting organizer, I want visible countdown timers per agenda item with configurable time allocations. (DB #334) +34. As a meeting facilitator, I want to display a live cost ticker showing the running cost of the current meeting. (DB #335) +35. As a manager, I want to designate no-meeting days and focus time blocks with compliance tracking. (DB #344) + +### Citizen Participation Domain + +36. As a coordinator, I want to plan and manage the assembly meeting schedule including information sessions, expert hearings, and deliberation rounds. (DB #223) +37. As a neighbourhood council member, I want residents to submit agenda items digitally so meetings address what the neighbourhood cares about. (DB #247) + +### Cross-Domain (Nextcloud Integration) + +38. As a member, I want all meetings to appear in my Nextcloud Calendar via CalDAV sync. (DB #1824) +39. As a secretary, I want action items from meeting minutes to automatically become CalDAV VTODO tasks assigned to the responsible person. (DB #1836) +40. As any user, I want to search for meetings, minutes, and related documents from the Nextcloud unified search bar. (DB #1871) +41. As a chair, I want to know which members have opened and read the meeting documents. (DB #1847, #1848, #1849) + +## Evidence Sources + +### Legal Standards (Mandatory) + +| Standard | Scope | Key Requirements | +|----------|-------|-----------------| +| **Gemeentewet** | Municipal meetings | Art. 17-20: meeting rules; Art. 20: quorum >50%; Art. 29: second meeting without quorum | +| **BW Boek 2** | Legal entity meetings | Art. 2:38: ALV rules; Art. 2:225: 42/15-day notice; Art. 2:227: BV meetings; Art. 2:41: extraordinary ALV | +| **Provinciewet** | Provincial States | Similar structure to Gemeentewet for provincial level | +| **Waterschapswet** | Water board meetings | Oldest democratic institutions in NL with unique governance structure | +| **Woo** | Public transparency | Active publication of meeting documents, agendas, decision lists | +| **Digitoegankelijk** | Accessibility | EN 301 549 with WCAG 2.1 for all meeting interfaces | +| **WDAV** | Digital meetings | Wet Digitale Algemene Vergadering -- enables fully digital association meetings (pending Eerste Kamer, insight #20) | + +### Forum Standaardisatie Standards (Recommended) + +| Standard | Relevance | +|----------|-----------| +| **WebDAV en CalDAV** | Meeting calendar sync and document sharing | +| **PDF/UA** | Accessible meeting document publication | +| **ODF** | Editable meeting document format | +| **Akoma Ntoso** | XML representation of parliamentary sessions | + +### External Research & Market Evidence + +- **$541B wasted on meetings globally** -- 67% of meeting time is wasted, 23 hrs/week for executives (Doodle/HBR) -- insight #1 +- **AI meeting tool usage grew 17x in 2024** -- Otter.ai, Fireflies, Grain, Fathom leading -- insight #5 +- **No self-hosted AI meeting solution exists** -- class-action lawsuits over recording consent -- insight #9 +- **Women's speaking time increased 65% when tracked** -- DEI impact feature -- insight #24 +- **Only 37% of meetings use agendas** -- Fellow State of Meetings 2024 -- source #319 +- **US workers spend 20%+ of week in meetings** (35% for senior leaders) -- source #319 +- **$37B/year in US on unnecessary meetings** -- mid-level employee $25K/year meeting cost -- source #325 +- **44% of action items never completed** -- 71% of meetings fail objectives due to poor follow-through -- source #342 +- **67% of professionals say clear agenda is most important meeting element** -- source #320 + +### Competitor Analysis + +| Competitor | Key Meeting Features | Gap | +|-----------|---------------------|-----| +| **Notubiz** | Council meeting publication, webcasting | Called "a true maze" (doolhof) by citizens -- poor search, missing voting records (source #361) | +| **iBabs** | Board portal, document distribution | Rated 4.6/5 but large documents cause problems; limited AI/analytics (source #372) | +| **Parlaeus** | Council decision workflow, AI search (MAAT) | Legislative-only, no corporate/association | +| **Diligent** | Enterprise board governance, 700K+ directors | AI minutes generation; closed source, enterprise pricing | +| **ConveneAGM** | Virtual/hybrid AGM, live voting, Q&A | Corporate governance only | +| **Fellow** | AI meeting notes, agenda collaboration | No formal voting or governance compliance | +| **OpenSlides** | Open source assembly system, 4 voting modes | Assembly-focused, no broader governance | +| **Congressus** | Dutch association software, ALV support | Member administration focus, limited meeting management | +| **Sherpany** | Swiss enterprise meeting management, 45% productivity boost | Corporate boards only, ISO 27001 certified | +| **BoardEffect** | Board management, G2 4.5/5 rating | Limited meeting minutes, server downtime issues | + +### Tender Requirements + +- **W-BESL**: "Beschrijf ondersteuning bestuurlijk besluitvormingsproces inclusief agendabeheer, vergaderingen, publiceren en archiveren" (70 pts) +- **W9**: "Beschrijf hoe de Oplossing het proces van bestuurlijke besluitvorming ondersteunt" (68 pts) +- **SGC 3**: "Volgen en terugkijken van vergaderingen" (15 pts) -- RIS/BIS tender +- **W11**: "Bestuurlijk besluitvormingsproces in Oplossing. College en gemeenteraad. Paraferen. iBabs voor agendabeheer" (48 pts) +- **W13**: "Beschrijf ondersteuning voor het volledige BBV-proces (10 stappen) inclusief agendabeheer, vergaderbehandeling, publicatie" (56 pts) + +## Customer Journeys + +### Legislative Domain +- **Agenda Preparation & Setting** -- Griffier creates meeting agenda from proposal backlog +- **Document Package Review & Preparation** -- Council members review documents on tablet +- **Presidium Agenda Setting** -- Faction leaders set agenda, classify items +- **Committee Information Gathering (Beeldvorming)** -- Citizens speak at committee meetings +- **Plenary Debate & Decision-Making (Besluitvorming)** -- Full council meeting proceedings +- **Minute Taking & Recording** -- Secretary records proceedings +- **Minutes Finalization & Approval** -- Draft minutes approved at next meeting +- **Meeting Recording Publication** -- Video indexed by agenda item, captioned +- **Live Meeting Following & Webcasting** -- Real-time public access +- **Records Archiving & Compliance** -- Archiefwet-compliant archiving +- **Water Board General Assembly Meeting** -- Dijkgraaf-chaired, 6x/year minimum +- **Provincial States Meeting Cycle** -- CdK-chaired, larger scale + +### Association Domain +- **ALV Convocation & Scheduling** -- Statutory notice periods, member notification +- **ALV Attendance & Quorum Verification** -- Presentielijst, digital check-in, proxy counting +- **Digital/Hybrid ALV Participation** -- Remote participation with identity verification +- **Board Meeting Preparation** -- Agenda, documents, WBTR compliance +- **Board Action Item Tracking** -- Post-meeting follow-through +- **Written Board Resolution (Outside Meeting)** -- BW 2:40 written procedure +- **Meeting Minutes Preparation & Approval** -- Notulen within statutory timeframe +- **Cooperative Member Meeting (ALV)** -- UA/BA/WA liability considerations +- **Member Council Meeting** -- Ledenraad as representative body (KNVB, FNV, ANWB) +- **Extraordinary ALV Request by Members** -- BW 2:41, 10% threshold + +### Corporate Governance Domain +- **AGM Convocation & Agenda Setting** -- 42-day notice, resolution drafting +- **Digital / Hybrid AGM Execution** -- Identity verification, live voting, Q&A +- **Board Pack Preparation & Distribution** -- Structured, indexed package 5-7 days before +- **Board Minutes & Action Item Tracking** -- Decisions, action items, completion tracking +- **AGM Minutes & Legal Documentation** -- Notarial minutes for contentious meetings +- **Proxy Voting & Power of Attorney** -- Digital proxy management + +### Corporate Operations Domain +- **MT Agenda Preparation** -- Collect items, compile package, distribute +- **MT Decision Making During Meeting** -- Real-time structured decisions +- **MT Minutes and Decision Distribution** -- Minutes within hours, cascade to departments +- **MT Recurring Review Cycle** -- Monthly/quarterly/annual strategic reviews +- **Steering Committee Meeting** -- Project decisions and risk reviews +- **Urgent Escalation Between Meetings** -- Cannot wait for next meeting +- **Meeting Efficiency & Analytics** -- Cost tracking, DEI speaking time, KPIs + +### Cross-Domain +- **Hybrid & Virtual Meeting Facilitation** -- Applicable across all 5 domains +- **AI-Powered Meeting Intelligence** -- Transcription, summarization, action extraction +- **Smart Agenda & Meeting Scheduling** -- Templates and calendar integration +- **Secure Document Management & Distribution** -- Version control, annotations +- **Meeting Analytics & Performance Insights** -- Effectiveness, costs, patterns +- **Platform Integration & Interoperability** -- APIs, Nextcloud ecosystem +- **Open Source & Digital Sovereignty** -- Self-hosted, full data sovereignty ## Acceptance Criteria -- Meetings are stored as OpenRegister objects with `@type` of `schema:Event` -- Physical, digital, and hybrid meeting modes are supported with correct Schema.org attendance modes -- Convocation tracks delivery status and respects statutory notice periods -- Quorum is automatically calculated including proxy votes -- Voting is blocked when quorum is not met -- Meeting list supports search, filter, and calendar view -- OpenRaadsinformatie `Vergadering`/`Zitting` mapping is available +1. Meetings are stored as OpenRegister objects with `@type` of `schema:Event` +2. Physical, digital, and hybrid meeting modes are supported with correct Schema.org attendance modes +3. Convocation tracks delivery status per recipient and respects statutory notice periods +4. Statutory notice periods are configurable per body type (42 days NV, 15 days BV, custom for associations) +5. Quorum is automatically calculated including proxy votes +6. Quorum rules are configurable per body (>50%, 2/3, custom) +7. Voting is blocked when quorum is not met +8. Second meeting without quorum is supported per Gemeentewet Art. 29 +9. Proxy (volmacht) management supports granting, revoking, and limits per person +10. Meeting list supports search, filter, and calendar view +11. Meetings sync to Nextcloud Calendar via CalDAV +12. Recurring meetings auto-generate individual editable instances with linked agendas +13. Meeting templates pre-populate agendas with required items per meeting type +14. Real-time notes are captured per agenda item and structured into minutes +15. Action items auto-create CalDAV VTODO tasks with owners and deadlines +16. Speaking order and time tracking is supported with DEI analytics +17. Meeting recordings are segmented by agenda item with searchable transcripts +18. Captions are generated for accessibility (WCAG AA) +19. Meeting documents track read/unread status per participant +20. Meeting cost and efficiency KPIs are trackable +21. No-meeting days can be configured with compliance tracking +22. OpenRaadsinformatie `Vergadering`/`Zitting` mapping is available +23. Citizen registration for committee speaking (inspreekrecht) is supported +24. Extraordinary ALV request validation is supported (10% threshold, 4-week deadline) +25. All meeting interfaces comply with Digitoegankelijk (EN 301 549 with WCAG 2.1) +26. MeetingTypes are configurable OpenRegister objects that seed default agenda items, quorum rules, and voting methods when creating a meeting +27. A live meeting page provides real-time view of current agenda item, documents, votes, and speaker queue for all participants +28. Meetings appear as CalDAV events in Nextcloud Calendar via OpenRegister's RegisterCalendarProvider +29. Recurring meeting series generate individual CalDAV events that are independently editable +30. Meeting invitations are sent as iCalendar (.ics) with RSVP tracking +31. Speaker queue supports registration, floor granting, time tracking, and chair reordering +32. Speaking time analytics are available per participant per meeting with DEI distribution insights + +## Notes + +### Open Questions + +- Should we build video conferencing directly or integrate with Nextcloud Talk? Talk integration is recommended (insight #27) to avoid reinventing the wheel. +- How to handle the transition when WDAV passes Eerste Kamer? Expected July 2026 deadline for full WBTR compliance. +- What is the minimum viable AI transcription quality for meeting minutes? Self-hosted Whisper vs. external API? +- How to handle document annotation sync when iBabs reports losing annotations on document replacement (source #372)? + +### Legal Risks + +- Digital identity verification for remote meeting participants has no standardized approach -- each organization may have different requirements. +- WDAV is pending in Eerste Kamer -- build for it now but have fallback for hybrid-only mode. +- Archiefwet requires archiving meeting discussions when they occur on platform -- Talk integration must consider this (insight #27). + +### Technical Decisions + +- Use OpenRegister _calendar metadata for virtual calendar sync (no separate calendar backend needed) +- Use OpenRegister _todos metadata for action item CalDAV sync +- Use OpenRegister _talk metadata for auto-creating Talk conversations per meeting +- Integrate Nextcloud Contacts for stakeholder-aware meeting workflows (insight #29: 438 stories reference participants) +- Self-hosted AI for transcription and summarization to avoid privacy lawsuits (insight #9) diff --git a/openspec/specs/motion-amendment/spec.md b/openspec/specs/motion-amendment/spec.md index 60af41e..34af51a 100644 --- a/openspec/specs/motion-amendment/spec.md +++ b/openspec/specs/motion-amendment/spec.md @@ -6,16 +6,27 @@ status: idea ## Purpose -Motions and amendments are the formal mechanisms for proposing decisions and modifying proposals before a vote. A motion is a formal proposal submitted by a member for consideration by the governing body. An amendment is a proposed modification to a pending motion. The system supports motion submission, amendment drafting, amendment voting order (amendments voted before the main motion), and the parliamentary procedure for handling competing amendments. +Motions and amendments are the formal mechanisms for proposing decisions and modifying proposals before a vote. A motion is a formal proposal submitted by a member for consideration by the governing body. An amendment is a proposed modification to a pending motion. The system supports the full motion lifecycle (draft, submitted, seconded, debated, voted, adopted/rejected/withdrawn), amendment drafting with diff visualization, amendment voting order (most far-reaching first per parliamentary procedure), conflict detection for overlapping amendments, and Dutch-specific motion types (motie, motie van orde, motie van wantrouwen, initiatiefvoorstel). **Standards**: Akoma Ntoso (`bill`, `amendment`, `motion`), Schema.org (`Action`, `ReplaceAction`), OpenRaadsinformatie (`Motie`, `Amendement`) **Feature tier**: V1 -**Legal reference**: Gemeentewet 147a (right to submit motions), Reglement van Orde (rules of procedure) +**Legal reference**: Gemeentewet 147a (right to submit motions), Reglement van Orde (rules of procedure), BW 2:37 (counter-nomination), BW 2:42 (statute amendment process) ## Data Model See [ARCHITECTURE.md](../../docs/ARCHITECTURE.md) for the full Motion and Amendment entity definitions including property tables, Akoma Ntoso alignment, and OpenRaadsinformatie mapping. +## Evidence Base + +This specification is informed by **113 user stories**, **32 requirements** from Dutch government tenders, and **31 external sources** from the intelligence database. Key evidence clusters: + +- **Requirement cluster #43**: "Besluitvorming (decision process)" -- 271 requirements across 133 tenders include motion/amendment handling (Source: intelligence DB cluster #43) +- **Tender requirement #5572**: "De Oplossing ondersteunt de registratie, behandeling en archivering van raadsinstrumenten zoals moties, amendementen, initiatiefvoorstellen, toezeggingen" (Source: intelligence DB req #5572) +- **Tender requirement #5573**: "Moties en amendementen zijn koppelbaar aan specifieke agendapunten en vergaderingen" (Source: intelligence DB req #5573) +- **Tender requirement #131443**: "Het systeem kan besluitenlijsten, lijsten van openstaande moties en amendement enz. genereren" (Source: intelligence DB req #131443) +- **Competitor analysis**: OpenSlides (motion management + amendment workflow), Decidim (proposal system), Notubiz (council instruments), Parlaeus (BBV process) (Source: intelligence DB competitors) +- **ParlTech Framework**: Transformation framework for digital parliament covering motion digitization (Source: intelligence DB ext #82) + ## Requirements --- @@ -25,6 +36,7 @@ See [ARCHITECTURE.md](../../docs/ARCHITECTURE.md) for the full Motion and Amendm The system MUST support submitting motions with a title, body text, proposer, co-signers, and rationale. Motions MUST follow the governing body's rules for submission (e.g., minimum co-signers, submission deadline). Motions MUST be stored as OpenRegister objects in the `decidesk` register using the `motion` schema. **Feature tier**: V1 +**Evidence**: 18 tender requirements reference motion/amendment management in bestuurlijke besluitvorming (Source: intelligence DB reqs #5572, #5573, #131443) #### Scenario: Submit a motion with co-signers @@ -49,13 +61,79 @@ The system MUST support submitting motions with a title, body text, proposer, co - THEN the chair MUST receive a real-time notification - AND the chair MUST be able to add the motion to the current agenda or defer to next meeting +#### Scenario: Draft motion from standardized template + +- GIVEN a council member wanting to create a formal motion +- WHEN they select the motion template +- THEN the system MUST provide a structured form with required fields: title, dictum (requested action), rationale (overwegingen), and optional attachments +- AND the template MUST follow the Reglement van Orde format for the specific governing body (Source: intelligence DB story #144) + +--- + +### Requirement: Motion Co-Signature Collection + +The system MUST support digital collection of co-signatures for motions. Co-signers MUST be able to review the motion text and confirm their support digitally. The system MUST track co-signature status in real-time. + +**Feature tier**: V1 +**Evidence**: Digital co-signature collection is a key workflow improvement over paper-based processes (Source: intelligence DB story #145) + +#### Scenario: Collect co-signatures digitally + +- GIVEN a council member has drafted a motion requiring 3 co-signers +- WHEN they send co-signature requests to selected colleagues +- THEN each invitee MUST receive a notification with the motion text +- AND each invitee MUST be able to accept or decline the co-signature request +- AND the proposer MUST see real-time status of pending/accepted/declined requests +- AND upon reaching the required number, the motion MUST become submittable + +#### Scenario: Withdraw co-signature before submission + +- GIVEN a member has agreed to co-sign a motion that has not yet been submitted +- WHEN the co-signer reviews the final text and finds it changed +- THEN they MUST be able to withdraw their co-signature +- AND the proposer MUST be notified of the withdrawal + +--- + +### Requirement: Dutch Motion Types + +The system MUST support the following Dutch-specific motion types, each with its own procedural rules: (1) Motie -- a statement of opinion or request to the executive, (2) Motie van orde -- a procedural motion about the meeting process, (3) Motie van wantrouwen -- a motion of no confidence, (4) Amendement -- a proposed modification to a draft decision, (5) Initiatiefvoorstel -- a legislative proposal initiated by a council member. + +**Feature tier**: V1 +**Legal reference**: Gemeentewet 147a, Reglement van Orde +**Evidence**: Parlaeus supports the full BBV process including proposal routing through college and council (Source: intelligence DB competitor #601, ext #63). Tender requirements specify "registratie, behandeling en archivering van raadsinstrumenten" (Source: intelligence DB req #5572) + +#### Scenario: Submit a motie van orde (procedural motion) + +- GIVEN a meeting in progress with debate on an agenda item +- WHEN a council member raises a motie van orde (e.g., to limit speaking time) +- THEN the system MUST flag it as a procedural motion requiring immediate handling +- AND the chair MUST immediately put it to vote (no debate required) +- AND the result MUST be applied immediately to the meeting proceedings + +#### Scenario: Submit a motie van wantrouwen (motion of no confidence) + +- GIVEN a council meeting where a faction wants to express no confidence in a wethouder +- WHEN the motion of no confidence is submitted +- THEN the system MUST flag it as a special motion type with heightened visibility +- AND the system MUST enforce that the vote is nominal (hoofdelijke stemming) +- AND if adopted, the system MUST trigger the appropriate governance actions + +#### Scenario: Create an initiatiefvoorstel (council-initiated proposal) + +- GIVEN a council member wanting to propose new policy +- WHEN they create an initiatiefvoorstel +- THEN the system MUST route it through the standard proposal workflow: drafting -> legal review -> financial review -> committee discussion -> plenary vote +- AND the proposal MUST follow the same template as executive proposals (raadsvoorstel) + --- ### Requirement: Amendment Drafting and Submission -The system MUST support creating amendments to pending motions. Amendments MUST clearly show what text is being added, removed, or modified (diff view). Multiple amendments to the same motion MUST be supported. +The system MUST support creating amendments to pending motions or proposals. Amendments MUST clearly show what text is being added, removed, or modified (diff view). Multiple amendments to the same motion MUST be supported. The system MUST detect conflicting amendments that modify the same text. **Feature tier**: V1 +**Evidence**: Rapporteurs in European Parliament manage hundreds of amendments per file (Source: intelligence DB story #205). OpenSlides provides motion management with amendment workflow (Source: intelligence DB competitor #707) #### Scenario: Submit an amendment to a pending motion @@ -72,13 +150,30 @@ The system MUST support creating amendments to pending motions. Amendments MUST - THEN both amendments MUST be tracked independently - AND the system MUST detect if amendments conflict (modify the same text) +#### Scenario: Draft amendment with inline text selection + +- GIVEN a council member viewing a proposal text +- WHEN they select text in the proposal and choose "Create Amendment" +- THEN the system MUST pre-populate the amendment with the selected text as the target +- AND the member MUST be able to edit the replacement text inline +- AND the system MUST generate a clean diff showing exactly what changes (Source: intelligence DB story #148) + +#### Scenario: Preview resulting text after amendment + +- GIVEN a proposal with an amendment that modifies two paragraphs +- WHEN a member clicks "Preview Result" +- THEN the system MUST display the full proposal text as it would read if the amendment is adopted +- AND unchanged text MUST be shown normally, changed text MUST be highlighted (Source: intelligence DB story #149) + --- ### Requirement: Amendment Voting Order -The system MUST enforce the parliamentary rule that amendments are voted on before the main motion. When multiple amendments exist, the most far-reaching amendment MUST be voted on first. The chair MUST be able to set the voting order. +The system MUST enforce the parliamentary rule that amendments are voted on before the main motion. When multiple amendments exist, the most far-reaching amendment MUST be voted on first. The chair MUST be able to set the voting order. The system MUST suggest an order based on amendment scope. **Feature tier**: V1 +**Legal reference**: Reglement van Orde (standard parliamentary procedure: last-in-first-out or most radical first) +**Evidence**: Amendment ordering is a core parliamentary procedure requirement across all council tender requirements (Source: intelligence DB stories #150, #311) #### Scenario: Vote on amendments before the main motion @@ -94,14 +189,24 @@ The system MUST enforce the parliamentary rule that amendments are voted on befo - WHEN the chair reviews the amendments - THEN the chair MUST be able to reorder the amendments for voting - AND the system MUST suggest an order based on scope (most far-reaching first) +- AND the system MUST support LIFO (last-in-first-out) as the default ordering strategy + +#### Scenario: Detect conflicting amendments + +- GIVEN a motion with two amendments that both modify paragraph 3 +- WHEN the chair reviews the amendments for voting order +- THEN the system MUST alert: "Amendments A and B both modify paragraph 3 -- voting order determines precedence" +- AND the chair MUST be advised that if amendment A is adopted, amendment B may become moot +- AND the system MUST support marking an amendment as "fallen" (vervallen) if it conflicts with an adopted amendment (Source: intelligence DB story #150) --- -### Requirement: Motion Withdrawal and Status +### Requirement: Motion Lifecycle and Status Tracking -The system MUST support motion withdrawal by the proposer before voting. Motions MUST follow a status lifecycle: `draft`, `submitted`, `under_consideration`, `voting`, `adopted`, `rejected`, `withdrawn`. +The system MUST support motion withdrawal by the proposer before voting. Motions MUST follow a status lifecycle: `draft`, `submitted`, `under_consideration`, `voting`, `adopted`, `rejected`, `withdrawn`, `executed`. Adopted motions MUST be tracked through execution by the responsible party. **Feature tier**: V1 +**Evidence**: Motion lifecycle tracking from submission through execution is the most requested feature for council members; 271 requirements reference decision process (Source: intelligence DB story #146, cluster #43) #### Scenario: Withdraw a motion before voting @@ -111,20 +216,210 @@ The system MUST support motion withdrawal by the proposer before voting. Motions - AND the withdrawal MUST be recorded in the audit trail - AND the motion MUST remain visible in the meeting record but marked as withdrawn -## User Stories +#### Scenario: Track motion status throughout lifecycle + +- GIVEN a council member who has submitted multiple motions over the past year +- WHEN they view their motion dashboard +- THEN the system MUST display all their motions with current status (draft, submitted, debated, voted, adopted, rejected, executed) +- AND for adopted motions, the system MUST show: assigned executive, deadline, and execution progress (Source: intelligence DB story #146) + +#### Scenario: Track adopted motion execution + +- GIVEN an adopted motion with an assigned executive and deadline +- WHEN the griffier views the motion execution dashboard +- THEN the system MUST show all adopted motions with: motion text, adoption date, responsible wethouder, deadline, and execution status +- AND the wethouder MUST be able to update execution status with progress notes +- AND overdue motions MUST be flagged for follow-up (Source: intelligence DB stories #178, #179, #180) + +--- + +### Requirement: Proposal Routing and Approval Workflow + +The system MUST support routing proposals (voorstellen) through an internal review and approval chain before submission to the governing body. The chain MUST be configurable per organization and proposal type, and MUST support parallel and sequential review steps. + +**Feature tier**: V1 +**Evidence**: BBV process with 18 process steps from zaak to college to council is the most complex workflow in Dutch municipalities (Source: intelligence DB req #1479, #4183). Multiple tenders specify proposal routing through MT, college, and council (Source: intelligence DB reqs #2830, #3223, #5071) -1. **Member submitting a motion**: As a member, I want to submit a motion or proposal for the ALV agenda with supporting arguments so that my topic is formally discussed and voted on. (Source: intelligence DB #54) +#### Scenario: Route proposal for internal review -2. **Secretary recording board decisions with votes**: As secretary, I want to record each board decision with the vote distribution per board member so that we comply with WBTR documentation requirements. (Source: intelligence DB #66) +- GIVEN a beleidsadviseur has drafted a council proposal (raadsvoorstel) +- WHEN they submit it for internal review +- THEN the system MUST route it through the configured chain: legal review -> financial review -> management review -> wethouder approval +- AND each reviewer MUST be able to approve, reject, or request changes with comments +- AND the system MUST log who performed each step, when, and how (Source: intelligence DB req #27, #3597) + +#### Scenario: Approve proposal for council submission + +- GIVEN a proposal that has passed all internal review steps +- WHEN the wethouder approves it for submission to the council +- THEN the proposal MUST be forwarded to the griffie for agenda placement +- AND the proposal MUST include all review comments and approval trail +- AND the system MUST support the "parafencarrousel" (initials carousel) for multi-approver flow (Source: intelligence DB story #156, req #5071) + +#### Scenario: Multiple approvers on a single proposal + +- GIVEN a proposal requiring approval from both the head of legal and the financial controller +- WHEN both reviewers can review simultaneously (parallel routing) +- THEN the system MUST track both approval statuses independently +- AND the proposal MUST only proceed when all required approvals are obtained (Source: intelligence DB req #30, #3600) + +--- + +### Requirement: Motion Linking and Cross-Referencing + +The system MUST support linking motions and amendments to specific agenda items, meetings, and related documents. The system MUST maintain a searchable register of all motions and amendments across meetings. + +**Feature tier**: V1 +**Evidence**: Tender requirements specify that motions and amendments must be linkable to agenda items and meetings (Source: intelligence DB req #5573). Council members need to search across all documents, decisions, motions, and minutes (Source: intelligence DB story #186) + +#### Scenario: Link motion to agenda item + +- GIVEN a council member drafting a motion about environmental policy +- WHEN they link the motion to agenda item "Environmental Action Plan 2026" +- THEN the motion MUST appear under that agenda item in the meeting view +- AND when the agenda item is discussed, all linked motions MUST be visible to participants (Source: intelligence DB story #147) + +#### Scenario: Search across all motions and amendments + +- GIVEN a citizen or journalist wanting to find motions about housing policy +- WHEN they search using the term "woningbouw" +- THEN the system MUST return all motions and amendments containing that term across all meetings +- AND results MUST include: motion title, proposer, status, meeting date, and voting result +- AND the search MUST support filtering by faction, status, and date range + +#### Scenario: Export motion register for reporting + +- GIVEN a griffier preparing a periodic report on motion execution +- WHEN they request an export of all motions with status and execution data +- THEN the system MUST generate a report with: motion text, proposer, faction, adoption date, responsible executive, deadline, and current status +- AND the export MUST support filtering on status (e.g., all overdue motions) (Source: intelligence DB req #4724) + +--- + +### Requirement: Written Resolution Procedure (Schriftelijk Besluit) + +The system MUST support the written resolution procedure for decisions outside meetings. The system MUST enforce BW 2:238 requirements for BVs (unanimous consent to the method) and track all responses. + +**Feature tier**: V1 +**Legal reference**: BW 2:40 (board decision outside meeting), BW 2:238 (BV written procedure) +**Evidence**: Written resolutions are essential for urgent decisions between meetings (Source: intelligence DB story #68) + +#### Scenario: Circulate written resolution to board + +- GIVEN an urgent matter requiring board approval between meetings +- WHEN the chair creates a written resolution with text, rationale, and response deadline +- THEN all board members MUST receive a notification with the proposal +- AND each member MUST respond with for/against/abstain before the deadline +- AND for BVs, the system MUST first collect unanimous consent to the written procedure itself +- AND the result MUST be recorded with the same formality as an in-meeting decision + +--- + +### Requirement: Counter-Nomination and Board Election Process + +The system MUST support the statutory right of members to submit counter-nominations for board positions per BW 2:37. Counter-nominations MUST follow the same procedural requirements as regular nominations. + +**Feature tier**: V1 +**Legal reference**: BW 2:37 (right to counter-nomination) + +#### Scenario: Submit counter-nomination for board position + +- GIVEN a board has proposed a binding nomination for treasurer +- WHEN a member submits a counter-nomination with their own candidate +- THEN the system MUST verify the counter-nomination meets the statutory requirements (submitted within deadline, sufficient support) +- AND both the binding nomination and counter-nomination MUST be presented to voters +- AND the election MUST follow secret ballot rules (Source: intelligence DB story #74) + +--- + +### Requirement: BOB Model Phase Tracking + +The system MUST support tagging agenda items with their BOB phase (Beeldvorming/Oordeelsvorming/Besluitvorming) and tracking how topics progress through phases across multiple meetings. + +**Feature tier**: V1 +**Evidence**: The BOB model is a standard Dutch decision-making framework used in municipalities. Hollands Kroon uses separate BOB-phase meetings (Source: intelligence DB ext #337) + +#### Scenario: Track topic through BOB phases + +- GIVEN a policy topic "Zonnepanelen op gemeentelijk vastgoed" entering the council process +- WHEN the griffier tags the first meeting as "Beeldvorming" (image-forming) +- THEN the system MUST track the topic's progression: Beeldvorming -> Oordeelsvorming -> Besluitvorming +- AND each phase MUST be linked to the relevant committee/council meeting +- AND the dashboard MUST show all active topics with their current BOB phase (Source: intelligence DB story #341) + +## User Stories -3. **Secretary preparing structured approval request**: As a board secretary, I want to prepare structured approval requests with all required information, so that the supervisory board can make informed decisions efficiently. (Source: intelligence DB #26) +### Priority: Must Have + +1. **Council member drafting motion from template**: As a raadslid, I want to create a motion using a standard template so that my motion meets all procedural requirements without manual formatting. (Source: intelligence DB #144) +2. **Council member tracking motion status**: As a raadslid, I want to see the current status of all my motions (draft, submitted, debated, voted, adopted, rejected, executed) so that I can follow up on my initiatives. (Source: intelligence DB #146) +3. **Council member linking motion to agenda item**: As a raadslid, I want to link my motion to a specific agenda item so that it is automatically included in the debate on that topic. (Source: intelligence DB #147) +4. **Council member drafting amendment with inline changes**: As a raadslid, I want to select text in a proposal and draft an amendment showing the exact changes (deletions and additions) so that the proposed modification is unambiguous. (Source: intelligence DB #148) +5. **Griffier creating and publishing meeting agenda**: As a griffier, I want to create a meeting agenda by selecting and ordering proposals from the backlog so that council members and the public can see what will be discussed. (Source: intelligence DB #136) +6. **Beleidsadviseur creating standardized proposal**: As a beleidsadviseur, I want to create a council proposal using a standardized template with all required sections so that the griffie can process it efficiently. (Source: intelligence DB #154) +7. **Beleidsadviseur routing proposal for review**: As a beleidsadviseur, I want to route my proposal through the required internal review steps (legal, financial, management) so that it meets all quality requirements before submission to the council. (Source: intelligence DB #155) +8. **Wethouder approving proposal for council**: As a wethouder, I want to approve a prepared proposal for submission to the council so that it enters the formal decision-making process. (Source: intelligence DB #156) +9. **Griffier submitting draft minutes for approval**: As a griffier, I want to submit draft minutes for approval at the next meeting with tracked corrections so that the approval process is transparent. (Source: intelligence DB #177) +10. **Griffier tracking adopted motion execution**: As a griffier, I want to track all adopted motions with assigned deadlines and responsible executive members so that I can report on progress to the council. (Source: intelligence DB #178) +11. **Chair managing amendment voting order**: As a chair, I want to manage the correct voting order for amendments so that the most far-reaching amendment is voted on first per parliamentary procedure. (Source: intelligence DB #311) +12. **Secretary conducting qualified majority vote for statute amendment**: As a board secretary, I want to conduct a 2/3 qualified majority vote so that statute amendments meet the legal threshold per BW 2:42. (Source: intelligence DB #314) +13. **Clerk creating execution tasks for adopted motions**: As a clerk, I want the system to automatically create follow-up tasks when a motion or decision is adopted, assigned to the responsible executive, so that execution is tracked from day one. (Source: intelligence DB #1838) +14. **Auditor tracking decision lifecycle events**: As an auditor, I want every action on a decision (creation, state change, vote cast, document added, amendment submitted) to be logged in the Nextcloud Activity stream so that there is a tamper-evident audit trail. (Source: intelligence DB #1865) + +### Priority: Should Have + +15. **Council member collecting co-signatures digitally**: As a raadslid, I want to digitally request and collect co-signatures for my motion from other council members so that I can quickly gather the required support. (Source: intelligence DB #145) +16. **Council member previewing amendment result**: As a raadslid, I want to preview what the proposal text looks like after my amendment is applied so that I can verify my changes have the intended effect. (Source: intelligence DB #149) +17. **Griffier detecting conflicting amendments**: As a griffier, I want to be alerted when multiple amendments target the same text passage so that I can advise the chair on voting order. (Source: intelligence DB #150) +18. **Commissiegriffier collecting executive proposals**: As a commissiegriffier, I want to receive proposals from the college in a standardized format so that I can efficiently process them into the agenda. (Source: intelligence DB #139) +19. **Raadslid viewing motion dashboard**: As a raadslid, I want to see a dashboard showing all adopted motions with their current status so that I can hold the executive accountable for follow-up. (Source: intelligence DB #179) +20. **Wethouder updating motion execution status**: As a wethouder, I want to update the execution status of motions assigned to me so that the council has current information about progress. (Source: intelligence DB #180) +21. **Council secretary tracking BOB phases**: As a council secretary, I want to tag each meeting or agenda item with its BOB phase and track how topics progress through phases across multiple meetings. (Source: intelligence DB #341) +22. **Stakeholder receiving calendar entries for deadlines**: As a stakeholder, I want voting deadlines, amendment submission deadlines, and public comment periods to automatically appear in my calendar so that I never miss a deadline. (Source: intelligence DB #1829) +23. **Council member tracking amendment versions with diff**: As a council member, I want to see all versions of a proposal/amendment with clear diffs between versions so that I can understand what changed at each stage of the deliberation process. (Source: intelligence DB #1845) + +### Priority: Could Have + +24. **Rapporteur managing large amendment sets**: As a rapporteur, I want tools to manage and organize hundreds of amendments on a single file so that I can efficiently negotiate compromise amendments across political groups. (Source: intelligence DB #205) +25. **Lobbyist tracking policy proposals**: As a belangenbehartiger, I want to track specific policy proposals as they move through the decision-making process across multiple democratic bodies so that I can provide timely input at each stage. (Source: intelligence DB #211) +26. **Member submitting counter-nomination**: As a member, I want to submit a counter-nomination for a board position against the board's binding nomination so that I can exercise my democratic right per BW 2:37. (Source: intelligence DB #74) +27. **Member submitting motion for ALV agenda**: As a member, I want to submit a motion or proposal for the ALV agenda with supporting arguments so that my topic is formally discussed and voted on. (Source: intelligence DB #54) +28. **MT member submitting agenda item with documents**: As an MT member, I want to submit agenda items with supporting documents through a structured form so that the secretary can compile a complete and well-organized agenda. (Source: intelligence DB #87) +29. **Management assistant compiling MT agenda**: As a management assistant, I want to compile submitted agenda items into a structured agenda and distribute the complete package to all MT members so that everyone is prepared for the meeting. (Source: intelligence DB #88) +30. **User embedding decision references via Smart Picker**: As a user composing an email or document in Nextcloud, I want to use the Smart Picker to search and embed a reference to a specific decision, motion, or meeting so that recipients can click through to the full record. (Source: intelligence DB #1874) + +## Competitor Analysis + +| Competitor | Motion/Amendment Features | Strengths | Gaps | +|---|---|---|---| +| **OpenSlides** | Create, amend, discuss, and vote on motions; amendment workflow | Purpose-built for assemblies; strong motion-vote pipeline; drag-and-drop amendment ordering | No proposal routing; no BBV process; no execution tracking | +| **Notubiz** | Council instruments: motions, amendments, votes; NotuBiz minutes | Dominant Dutch council market; integrated with meeting recordings | Closed platform; poor search UX; limited amendment diff view | +| **Parlaeus** | Full BBV process; proposal routing; council member profiles | Strong integration with municipal workflow; Apeldoorn case study | Proprietary; limited to Dutch councils; no association/corporate support | +| **Decidim** | Proposals, versioned texts, participatory legislation | Citizen-facing proposal system; versioned collaborative texts | No formal parliamentary procedure; no amendment voting order; heavy platform | +| **Loomio** | Proposals with agree/disagree/abstain/block; threaded discussion | Good for collaborative deliberation; supports 30+ languages | No formal motion types; no amendment diff; no parliamentary procedure | +| **GO Raadsinformatie** | Document management; publish council documents and decisions | Market presence in Dutch councils; document-focused | No real-time motion submission; limited amendment workflow | + +(Sources: intelligence DB competitors #707, #601, #620, #699, #685, #585) ## Acceptance Criteria -- Motions are stored as OpenRegister objects with proposer, co-signers, and rationale -- Amendments show a diff view of proposed text changes +- Motions are stored as OpenRegister objects with proposer, co-signers, rationale, and type classification +- Dutch motion types are supported: motie, motie van orde, motie van wantrouwen, amendement, initiatiefvoorstel +- Motion templates follow Reglement van Orde format with required fields (title, dictum, overwegingen) +- Co-signature collection is digital with real-time status tracking +- Amendments show a diff view of proposed text changes (additions/removals) +- Amendment conflict detection alerts when multiple amendments target the same text - Amendment voting precedes main motion voting (parliamentary rule) -- Chair can set amendment voting order -- Motion lifecycle follows defined status transitions -- Motion withdrawal is supported and recorded +- Chair can set amendment voting order; system suggests most-far-reaching-first +- Proposal routing supports configurable review chains (legal, financial, management, wethouder) +- Multi-approver flows support both parallel and sequential routing +- Motion lifecycle follows defined status transitions (draft through executed) +- Adopted motion execution is tracked with assigned responsible party, deadline, and progress +- Motion withdrawal is supported and recorded in audit trail +- Motions and amendments are linkable to agenda items and meetings +- Searchable register of all motions with filtering by faction, status, and date +- BOB model phase tracking across multiple meetings - OpenRaadsinformatie `Motie`/`Amendement` mapping is available +- Every lifecycle event is logged in Nextcloud Activity stream +- Written resolution procedure supports BW 2:238 consent-to-method for BVs +- Counter-nominations are supported per BW 2:37 diff --git a/openspec/specs/nextcloud-integration/spec.md b/openspec/specs/nextcloud-integration/spec.md index bad3da5..55fee4e 100644 --- a/openspec/specs/nextcloud-integration/spec.md +++ b/openspec/specs/nextcloud-integration/spec.md @@ -6,18 +6,31 @@ status: idea ## Purpose -Decidesk leverages Nextcloud's platform capabilities to provide a seamless governance experience without reinventing existing functionality. This specification covers integration with Nextcloud Calendar (meeting scheduling), Files (document management), Mail (convocation delivery), Talk (meeting communication), Tasks (action item tracking), Activity (audit feed), Notifications (alerts), Search (universal search), and References (rich link previews). Each integration uses the appropriate OCP interface. +Decidesk leverages Nextcloud's platform capabilities to provide a seamless governance experience without reinventing existing functionality. This specification covers integration with 10 Nextcloud subsystems: Calendar (meeting scheduling), Files (document management), Mail (convocation delivery and vote-by-email), Talk (deliberation channels), Tasks (action item tracking), Contacts (participant matching), Activity (audit feed), Notifications (state-change alerts), Search (unified search), and References (Smart Picker rich link previews). Each integration uses the appropriate OCP interface and degrades gracefully when optional apps are not installed. -**Standards**: Nextcloud OCP interfaces, CalDAV (RFC 4791), WebDAV +**Standards**: Nextcloud OCP interfaces, CalDAV (RFC 4791), WebDAV, CardDAV **Feature tier**: V1 +**Evidence sources**: Intelligence DB user stories #1, #2, #3, #7, #8, #11, #12, #15, #17, #19, #20, #46, #47, #49, #50, #54, #57, #65, #67, #69, #75, #80, #87, #88, #91, #92, #93, #129, #136, #137, #138, #140, #141, #142, #143, #147, #151, #152, #164, #171, #172, #174, #176, #177, #182, #183, #184; Requirement clusters #34 (Notifications, 451 reqs/153 tenders), #44 (Teams integration, 315 reqs/133 tenders), #54 (e-Depot, 247 reqs/117 tenders), #55 (Document creation/generation, 298 reqs/116 tenders); Category features: calendar-integration, document-storage, document-linking, notifications, search-filter, full-text-search + +## Roadmap + +### Phase 1 - MVP Foundation (V1) +Calendar, Files, Notifications, Activity, Search + +### Phase 2 - Collaboration (V1.1) +Talk, Tasks, Contacts, References + +### Phase 3 - Advanced Communication (V2) +Mail (convocation delivery, vote-by-email), advanced file workflows (board pack assembly, document comparison) + ## Requirements --- -### Requirement: Calendar Integration +### REQ-NI-01: Calendar Integration -The system MUST create Nextcloud Calendar events for scheduled meetings via `OCP\Calendar\IManager`. Calendar events MUST include meeting title, date/time, location, body, and a link back to the Decidesk meeting. Changes to the meeting schedule MUST update the calendar event. +The system MUST create Nextcloud Calendar events for scheduled meetings via `OCP\Calendar\IManager`. Calendar events MUST include meeting title, date/time, location, body, and a link back to the Decidesk meeting. Changes to the meeting schedule MUST update the calendar event. Cancellations MUST cancel the calendar event. **Feature tier**: V1 @@ -26,8 +39,9 @@ The system MUST create Nextcloud Calendar events for scheduled meetings via `OCP - GIVEN a meeting "Board Meeting Q2" scheduled for 2026-07-15 14:00-16:00 in "Boardroom A" - WHEN the meeting is created in Decidesk - THEN a calendar event MUST be created in each attendee's Nextcloud Calendar -- AND the event MUST include the meeting link, agenda summary, and document links -- AND the event MUST have a reminder set to the user's configured preference +- AND the event MUST include the meeting link, agenda summary, and document links in the description +- AND the event MUST have a reminder set to the user's configured preference (default: 24h + 1h before) +- AND the event location MUST be set to the meeting location or video call URL #### Scenario: Update calendar event when meeting is rescheduled @@ -35,19 +49,29 @@ The system MUST create Nextcloud Calendar events for scheduled meetings via `OCP - WHEN the meeting date is changed from July 15 to July 22 - THEN all attendee calendar events MUST be updated to the new date - AND attendees MUST receive a notification about the schedule change +- AND the event description MUST reflect any updated agenda information #### Scenario: Cancel calendar event when meeting is cancelled - GIVEN a meeting with associated calendar events - WHEN the meeting is cancelled -- THEN all attendee calendar events MUST be cancelled +- THEN all attendee calendar events MUST be cancelled (status CANCELLED in CalDAV) - AND attendees MUST receive a cancellation notification +- AND the calendar event MUST NOT be deleted (preserved for history) + +#### Scenario: Add new participant to existing meeting + +- GIVEN a meeting with calendar events for 5 existing participants +- WHEN a 6th participant is added to the meeting +- THEN a calendar event MUST be created for the new participant +- AND existing participants' events MUST NOT be affected +- AND the new participant MUST receive a meeting invitation notification --- -### Requirement: Files Integration +### REQ-NI-02: Files Integration -The system MUST store and manage meeting documents using Nextcloud Files via `OCP\Files\IRootFolder`. Each meeting MUST have a dedicated folder in a configurable location. Agenda item attachments MUST be stored in the meeting folder. +The system MUST store and manage meeting documents using Nextcloud Files via `OCP\Files\IRootFolder`. Each meeting MUST have a dedicated folder in a configurable location. Document access controls MUST follow governance roles. **Feature tier**: V1 @@ -56,24 +80,40 @@ The system MUST store and manage meeting documents using Nextcloud Files via `OC - GIVEN a meeting "Board Meeting Q2 2026" for body "Board of Directors" - WHEN the meeting is created - THEN a folder MUST be created at the configured path (default: `Decidesk/Board of Directors/2026-07-15 Board Meeting Q2/`) -- AND subfolders MUST be created for "Agenda Documents" and "Minutes" +- AND subfolders MUST be created for "Agenda Documents", "Minutes", and "Resolutions" - AND all body members MUST have read access; secretary and chair MUST have write access #### Scenario: Attach document to agenda item via file picker - GIVEN a user editing an agenda item - WHEN they click "Attach Document" and select a file from Nextcloud Files -- THEN the file MUST be linked to the agenda item -- AND the file MUST be accessible to all meeting participants -- AND the file MUST appear in the meeting document package +- THEN the file MUST be linked to the agenda item in the OpenRegister object +- AND the file MUST be accessible to all meeting participants via the meeting folder +- AND the file MUST appear in the meeting document package (board pack) + +#### Scenario: Assemble board pack from multiple sources + +- GIVEN a secretary preparing documents for a board meeting with 8 agenda items +- WHEN they compile the board pack +- THEN the system MUST assemble all agenda item documents into a structured package +- AND the package MUST include a cover page with the agenda overview +- AND the package MUST be distributable as a single PDF or as individual files in the meeting folder + +#### Scenario: Compare document versions + +- GIVEN a document attached to an agenda item that has been updated +- WHEN a user views the document history +- THEN the system MUST show all versions of the document via Nextcloud Files versioning +- AND the user MUST be able to compare versions to see what changed +- AND the latest version MUST be clearly indicated --- -### Requirement: Talk Integration +### REQ-NI-03: Talk Integration -The system MUST create Nextcloud Talk conversations for meetings via `OCP\Talk\IBroker`. Meeting participants MUST be automatically added to the conversation. The conversation MUST serve as the communication channel for meeting preparation and follow-up. +The system MUST create Nextcloud Talk conversations for meetings via `OCP\Talk\IBroker`. Meeting participants MUST be automatically added. The conversation MUST serve as the communication channel for meeting preparation, deliberation, and follow-up. -**Feature tier**: V1 +**Feature tier**: V1.1 #### Scenario: Create Talk conversation for a meeting @@ -82,12 +122,30 @@ The system MUST create Nextcloud Talk conversations for meetings via `OCP\Talk\I - THEN a Talk conversation MUST be created with all participants - AND the conversation name MUST be "ALV 2026" - AND the conversation description MUST include the meeting date and agenda link +- AND the conversation type MUST be "group" (not public) + +#### Scenario: Create Talk channel for a governing body + +- GIVEN a body "Bestuur" with 5 members +- WHEN the body is created (or when Talk integration is first enabled) +- THEN a persistent Talk conversation MUST be created for the body +- AND all body members MUST be added as participants +- AND the channel MUST persist across meetings for ongoing governance communication +- AND member changes in the body MUST automatically update the Talk participant list + +#### Scenario: Link Talk messages to agenda items + +- GIVEN a meeting Talk conversation +- WHEN participants discuss specific agenda items before the meeting +- THEN the system SHOULD allow tagging messages with agenda item references +- AND tagged messages MUST be retrievable from the agenda item detail view +- AND this provides a discussion thread per agenda item --- -### Requirement: Activity Integration +### REQ-NI-04: Activity Integration -The system MUST publish Decidesk events to the Nextcloud Activity feed via `OCP\Activity\IManager`. Events MUST include: decision created/status changed, meeting scheduled/started/ended, vote initiated/completed, and resolution adopted. +The system MUST publish Decidesk events to the Nextcloud Activity feed via `OCP\Activity\IManager`. Events MUST provide a complete audit trail of governance actions. **Feature tier**: V1 @@ -99,11 +157,34 @@ The system MUST publish Decidesk events to the Nextcloud Activity feed via `OCP\ - AND the entry MUST be visible to all members of the governing body - AND clicking the activity MUST navigate to the decision in Decidesk +#### Scenario: Meeting lifecycle events in Activity feed + +- GIVEN a meeting progressing through its lifecycle +- WHEN the meeting is created, convoked, started, and completed +- THEN Activity entries MUST be created for each transition +- AND the entries MUST include: meeting title, body, date, and actor (who performed the action) +- AND the Activity provider MUST use Decidesk-specific icons and formatting + +#### Scenario: Vote completion appears in Activity feed + +- GIVEN a vote on "Policy Update" that has just closed +- WHEN the vote results are finalized +- THEN an Activity entry MUST be created: "Vote on 'Policy Update' completed: Adopted (12 for, 3 against, 1 abstain)" +- AND the entry MUST be visible to all body members +- AND for secret ballots, individual votes MUST NOT be included in the activity + +#### Scenario: Resolution adoption in Activity feed + +- GIVEN a resolution formally adopted +- WHEN the resolution status changes to "adopted" +- THEN an Activity entry MUST be created with the resolution title, sequence number, and adopting body +- AND the entry MUST include a link to the published resolution + --- -### Requirement: Notification Integration +### REQ-NI-05: Notification Integration -The system MUST send Nextcloud Notifications via `OCP\Notification\IManager` for time-sensitive governance events: upcoming meeting reminders, pending votes, voting deadlines approaching, and action item due dates. +The system MUST send Nextcloud Notifications via `OCP\Notification\IManager` for time-sensitive governance events. Notifications MUST respect user preferences configured in user settings. **Feature tier**: V1 @@ -112,7 +193,7 @@ The system MUST send Nextcloud Notifications via `OCP\Notification\IManager` for - GIVEN a new vote has been initiated for decision "Policy Update" - WHEN the vote opens - THEN all eligible voters MUST receive a Nextcloud notification -- AND the notification MUST include the decision title, body, and voting deadline +- AND the notification MUST include the decision title, body, voting method, and deadline - AND tapping the notification MUST open the voting interface #### Scenario: Send voting deadline reminder @@ -120,13 +201,35 @@ The system MUST send Nextcloud Notifications via `OCP\Notification\IManager` for - GIVEN a vote with deadline tomorrow and user has not yet voted - WHEN the reminder timing is triggered (24 hours before deadline) - THEN the user MUST receive a notification: "Reminder: Your vote on 'Policy Update' is due tomorrow" -- AND the notification MUST use `variant="warning"` +- AND the notification MUST be styled with warning priority + +#### Scenario: Send meeting convocation notification + +- GIVEN a meeting "ALV 2026" is being convoked +- WHEN the secretary sends the convocation +- THEN all body members MUST receive a notification with the meeting date, agenda link, and document package link +- AND the notification MUST include the statutory deadline information +- AND delivery MUST be tracked (notification read/dismissed) + +#### Scenario: Send action item due notification + +- GIVEN an action item "Submit financial report" assigned to the treasurer with due date tomorrow +- WHEN the reminder timing is triggered +- THEN the treasurer MUST receive a notification with the action item title, source decision, and due date +- AND overdue action items MUST generate escalating notifications (24h overdue, 72h overdue) + +#### Scenario: Send quorum-at-risk notification + +- GIVEN a meeting in progress with quorum currently met +- WHEN a member leaves and quorum drops to within 1 member of the threshold +- THEN the chair and secretary MUST receive an immediate notification: "Quorum at risk: 11/21 present (minimum 11 required)" +- AND the notification MUST be high priority --- -### Requirement: Search Integration +### REQ-NI-06: Search Integration -The system MUST register a search provider via `OCP\Search\IProvider` so that decisions, meetings, and resolutions are findable from Nextcloud's universal search. +The system MUST register a search provider via `OCP\Search\IProvider` so that decisions, meetings, resolutions, motions, and minutes are findable from Nextcloud's unified search. **Feature tier**: V1 @@ -135,28 +238,330 @@ The system MUST register a search provider via `OCP\Search\IProvider` so that de - GIVEN decisions exist including "Budget 2026 Approval" - WHEN the user searches for "budget" in Nextcloud's universal search - THEN the Decidesk search provider MUST return "Budget 2026 Approval" as a result -- AND the result MUST show the decision title, status, body, and a thumbnail icon +- AND the result MUST show the decision title, status, body, and date - AND clicking the result MUST navigate to the decision detail view in Decidesk +#### Scenario: Search across multiple entity types + +- GIVEN the user searches for "sustainability" +- WHEN results are returned +- THEN the search MUST find matches across decisions, meetings, resolutions, motions, and minutes +- AND results MUST be grouped by entity type with clear labels +- AND the search MUST cover both titles and full-text content + +#### Scenario: Search respects access controls + +- GIVEN a user who is a member of body "Bestuur" but not body "RvC" +- WHEN they search for a decision that exists in both bodies +- THEN only the "Bestuur" decision MUST appear in results +- AND "RvC" decisions MUST be filtered out based on body membership + +--- + +### REQ-NI-07: Tasks Integration + +The system MUST create Nextcloud Tasks for action items via `OCP\AppFramework\IAppContainer` or direct CalDAV VTODO. Action items from decisions MUST be trackable with owners, deadlines, and status updates. + +**Feature tier**: V1.1 + +#### Scenario: Create task from decision action item + +- GIVEN a decision "Approve Budget" with action item "Submit quarterly report" assigned to the treasurer, due 2026-09-30 +- WHEN the action item is created in Decidesk +- THEN a Nextcloud Task MUST be created in the treasurer's task list +- AND the task MUST include the action item title, description, due date, and a link back to the source decision +- AND completing the task in Nextcloud Tasks MUST update the action item status in Decidesk + +#### Scenario: Track action item completion across meetings + +- GIVEN 5 open action items from the previous board meeting +- WHEN the secretary prepares the agenda for the next meeting +- THEN a "Review action items" agenda item MUST show all open items with their current status +- AND overdue items MUST be highlighted +- AND the status MUST be synchronized from Nextcloud Tasks + +#### Scenario: Automatic rollover of incomplete action items + +- GIVEN a meeting has ended with 2 action items still open +- WHEN the next meeting is created for the same body +- THEN open action items MUST be automatically added to the new meeting agenda +- AND the items MUST show which meeting they originated from + +--- + +### REQ-NI-08: Contacts Integration + +The system MUST use Nextcloud Contacts via `OCP\Contacts\IManager` to match and enrich participant data. External participants (notaries, auditors, guests) MUST be resolvable from the address book. + +**Feature tier**: V1.1 + +#### Scenario: Match member to Nextcloud contact + +- GIVEN a body member "Jan de Vries" with email jan@example.nl +- WHEN the system resolves the member's contact information +- THEN it MUST search Nextcloud Contacts for a matching entry +- AND if found, the member profile MUST be enriched with contact photo, phone number, and organization +- AND the contact link MUST be maintained for ongoing synchronization + +#### Scenario: Add external participant from contacts + +- GIVEN a meeting that requires a notary's attendance +- WHEN the secretary adds an external participant +- THEN the system MUST offer a Nextcloud Contacts search to find the notary +- AND the notary MUST be added as a non-voting guest participant +- AND the notary MUST receive meeting notifications but NOT have access to confidential body documents + +--- + +### REQ-NI-09: References (Smart Picker) Integration + +The system MUST register a reference provider via `OCP\Collaboration\Reference\IReferenceProvider` so that Decidesk entities can be embedded as rich link previews in Nextcloud Text, Talk, and Mail. + +**Feature tier**: V1.1 + +#### Scenario: Embed decision reference in Talk message + +- GIVEN a user discussing a decision in a Talk conversation +- WHEN they paste a Decidesk decision URL +- THEN the URL MUST be rendered as a rich preview showing: decision title, status badge, body, date, and vote result summary +- AND clicking the preview MUST navigate to the decision in Decidesk + +#### Scenario: Embed meeting reference in Nextcloud Text + +- GIVEN a user writing meeting preparation notes in a Nextcloud Text document +- WHEN they use the Smart Picker to search for a Decidesk meeting +- THEN the picker MUST search Decidesk meetings by title and date +- AND the selected meeting MUST be embedded as a rich card with title, date, body, agenda summary, and status + +#### Scenario: Embed resolution in email + +- GIVEN a secretary drafting an email about an adopted resolution +- WHEN they paste a Decidesk resolution URL +- THEN the URL MUST be rendered as a rich preview with resolution title, sequence number, adoption date, and body + +--- + +### REQ-NI-10: Mail Integration + +The system MUST support sending governance communications via Nextcloud Mail or configured SMTP. This includes convocation delivery, meeting document distribution, and vote-by-email for authorized scenarios. + +**Feature tier**: V2 + +#### Scenario: Send convocation via email + +- GIVEN a meeting "ALV 2026" being convoked to 200 members +- WHEN the secretary triggers convocation delivery +- THEN each member MUST receive an email with: meeting title, date/time, location, agenda, document links, and RSVP link +- AND the email MUST be sent from the configured governance email address +- AND delivery status (sent, delivered, bounced) MUST be tracked per recipient +- AND the convocation MUST include the statutory deadline calculation + +#### Scenario: Distribute minutes via email + +- GIVEN approved minutes for "Board Meeting Q2 2026" +- WHEN the secretary distributes the minutes +- THEN all body members MUST receive an email with the minutes attached as PDF +- AND the email MUST include a link to the online version in Decidesk +- AND distribution MUST be logged in the Activity feed + +#### Scenario: Vote-by-email for circular resolution + +- GIVEN a circular resolution requiring unanimous board consent +- WHEN a board member receives the vote-by-email +- THEN they MUST be able to reply with "FOR", "AGAINST", or "ABSTAIN" +- AND the system MUST parse the reply and record the vote +- AND the member MUST receive confirmation of their recorded vote +- AND vote-by-email MUST only be available for bodies where the administrator has enabled it + +--- + +### REQ-NI-11: Graceful Degradation + +The system MUST detect which optional Nextcloud apps are installed and gracefully disable integrations for missing apps. Core Decidesk functionality MUST work without any optional apps installed. + +**Feature tier**: V1 + +#### Scenario: Talk app not installed + +- GIVEN a Nextcloud instance without the Talk app +- WHEN Decidesk creates a meeting +- THEN the Talk conversation creation MUST be silently skipped +- AND the meeting interface MUST NOT show "Open Talk channel" buttons +- AND no errors MUST be logged for the missing integration + +#### Scenario: Calendar app not installed + +- GIVEN a Nextcloud instance without the Calendar app +- WHEN Decidesk creates a meeting +- THEN calendar event creation MUST be silently skipped +- AND the meeting MUST still function for scheduling, agenda, and voting +- AND the admin settings MUST show which integrations are available vs. unavailable + +#### Scenario: Check integration availability at runtime + +- GIVEN an administrator in integration settings +- WHEN they view the integration configuration page +- THEN each integration MUST show its current status: "Available" (app installed), "Not available" (app not installed), or "Disabled" (manually disabled) +- AND a description MUST explain what each integration provides + +--- + +### REQ-NI-12: Audit Trail Completeness + +The system MUST ensure that all governance-critical actions are recorded in an immutable audit trail via the Activity integration. The audit trail MUST satisfy WBTR documentation requirements. + +**Feature tier**: V1 + +#### Scenario: Complete audit trail for a decision lifecycle + +- GIVEN a decision that progresses through its full lifecycle +- WHEN the decision is created, deliberated, voted on, adopted, and a resolution is published +- THEN the Activity feed MUST contain entries for every status transition +- AND each entry MUST include: timestamp, actor (who), action (what), and context (decision title, body) +- AND the audit trail MUST be exportable as a PDF report for compliance purposes + +#### Scenario: Vote audit trail preserves integrity + +- GIVEN a completed vote with 15 ballots +- WHEN the vote results are reviewed +- THEN the audit trail MUST show when the vote was opened, each ballot timestamp, and when the vote was closed +- AND for open/roll call votes, each voter's choice MUST be recorded +- AND for secret ballots, only aggregate results MUST be in the trail (not individual choices) + +--- + +### REQ-NI-13: Archive Integration + +The system MUST support archiving governance records to Nextcloud Files and optionally to e-Depot (digital archive) systems. Archived records MUST include complete metadata (MDTO where applicable). + +**Feature tier**: V2 + +#### Scenario: Auto-archive completed meeting records + +- GIVEN a meeting that has been completed with approved minutes +- WHEN the archival period triggers (configurable, e.g., 30 days after meeting) +- THEN all meeting records (agenda, documents, minutes, decisions, votes, resolutions) MUST be archived +- AND the archive MUST include complete metadata for each document +- AND archived records MUST remain searchable but marked as archived + +#### Scenario: Verify archive completeness + +- GIVEN a request to verify the archive for body "Gemeenteraad" year 2025 +- WHEN the archivist runs the completeness check +- THEN the system MUST verify that all meetings have: agenda, minutes, all decisions with vote results, and all resolutions +- AND missing records MUST be flagged with specific gaps identified +- AND a completeness report MUST be generated + +--- + +### REQ-NI-14: Video Recording Index + +The system MUST support linking video recordings of meetings and indexing them by agenda item for efficient navigation. + +**Feature tier**: V2 + +#### Scenario: Index video recording by agenda item + +- GIVEN a recorded council meeting with 12 agenda items +- WHEN the secretary adds timestamp markers for each agenda item +- THEN viewers MUST be able to jump directly to the discussion of any agenda item +- AND the video timeline MUST show agenda item markers +- AND the meeting detail page MUST link each agenda item to its video segment + ## User Stories -1. **Board member accessing board pack on mobile**: As a supervisory board member, I want to access the board pack on my tablet or smartphone with offline capability, so that I can prepare for meetings while traveling. (Source: intelligence DB #18) +1. **Board secretary creating AGM agenda**: As a board secretary, I want to create and manage the AGM agenda with drag-and-drop ordering, so that I can efficiently prepare a compliant meeting agenda. (Source: intelligence DB #1, priority: must) + +2. **Board secretary distributing convocation notices**: As a board secretary, I want to distribute convocation notices via email with delivery tracking, so that I meet statutory notice requirements. (Source: intelligence DB #2, priority: must) + +3. **Shareholder accessing AGM documents online**: As a shareholder, I want to access all AGM documents through a secure online portal, so that I can prepare for the meeting. (Source: intelligence DB #3, priority: must) + +4. **Board secretary conducting live voting**: As a board secretary, I want to conduct live voting during the AGM with real-time results. (Source: intelligence DB #7, priority: must) + +5. **Shareholder tracking resolution outcomes**: As a shareholder, I want to see voting results for each resolution immediately after the vote. (Source: intelligence DB #8, priority: must) + +6. **Board secretary taking digital minutes**: As a board secretary, I want to take structured minutes during the AGM using a digital template. (Source: intelligence DB #11, priority: must) + +7. **Notary accessing meeting information**: As a notary, I want secure read-only access to meeting agenda, attendee list, and voting results for notarial minutes. (Source: intelligence DB #12, priority: should) + +8. **CEO creating structured decision proposal**: As a CEO, I want to create a structured decision proposal with options analysis and risk assessment. (Source: intelligence DB #15, priority: must) + +9. **Board secretary assembling board pack**: As a board secretary, I want to assemble board packs by combining documents from multiple sources into a structured package. (Source: intelligence DB #17, priority: should) + +10. **Board secretary tracking action items**: As a board secretary, I want to assign, track, and report on board action items with due dates and owners. (Source: intelligence DB #19, priority: must) + +11. **CEO approving board minutes digitally**: As a CEO, I want to review and approve board minutes digitally with tracked changes. (Source: intelligence DB #20, priority: should) + +12. **Secretary sending ALV convocation**: As secretary, I want to send the ALV convocation to all voting members with delivery confirmation. (Source: intelligence DB #46, priority: critical) + +13. **Member receiving ALV invitation with agenda**: As a member, I want to receive the ALV invitation with complete agenda and supporting documents. (Source: intelligence DB #47, priority: high) + +14. **Chair composing ALV agenda with required items**: As chair, I want to compose the ALV agenda ensuring all legally required items are included. (Source: intelligence DB #49, priority: critical) + +15. **Treasurer attaching financial documents**: As treasurer, I want to upload financial statements and budget proposal to the ALV agenda. (Source: intelligence DB #50, priority: critical) + +16. **Member submitting motion for ALV agenda**: As a member, I want to submit a motion for the ALV agenda with supporting arguments. (Source: intelligence DB #54, priority: high) + +17. **Secretary preparing digital meeting package**: As secretary, I want to prepare a digital meeting package with agenda, previous minutes, and action items. (Source: intelligence DB #65, priority: high) + +18. **Secretary tracking action items from decisions**: As secretary, I want to assign action items with owners and deadlines from meeting decisions. (Source: intelligence DB #67, priority: medium) + +19. **Board member declaring conflict of interest**: As a board member, I want to formally declare a conflict of interest for a specific agenda item. (Source: intelligence DB #69, priority: high) + +20. **Secretary drafting and distributing ALV minutes**: As secretary, I want to draft the ALV minutes and distribute them to members within the statutory timeframe. (Source: intelligence DB #75, priority: high) + +21. **Member accessing documents and decision history**: As a member, I want to access meeting minutes, financial reports, and decision history through a self-service portal. (Source: intelligence DB #80, priority: medium) + +22. **MT member submitting agenda item with documents**: As an MT member, I want to submit agenda items with supporting documents through a structured form. (Source: intelligence DB #87, priority: high) + +23. **Management assistant compiling MT agenda package**: As a management assistant, I want to compile agenda items into a structured agenda and distribute to all MT members. (Source: intelligence DB #88, priority: high) + +24. **Management assistant assigning action items**: As a management assistant, I want to assign action items to MT members with deadlines and track completion. (Source: intelligence DB #91, priority: high) + +25. **MT member updating action item status**: As an MT member, I want to update the status of my action items directly from the platform. (Source: intelligence DB #92, priority: medium) + +26. **Management assistant generating minutes**: As a management assistant, I want to generate structured minutes from notes and decisions captured during the meeting. (Source: intelligence DB #93, priority: high) + +27. **Employee searching decision register**: As an employee, I want to search a central decision register by topic, date, meeting, or decision-maker. (Source: intelligence DB #129, priority: high) + +28. **Griffier creating and publishing meeting agenda**: As a griffier, I want to create a meeting agenda and publish the complete package. (Source: intelligence DB #136, #138, priority: must) + +29. **Raadslid annotating meeting documents**: As a raadslid, I want to highlight text and add notes to meeting documents on my tablet. (Source: intelligence DB #140, priority: must) + +30. **Citizen subscribing to decision notifications**: As a burger, I want to receive notifications when the council makes decisions on topics I follow. (Source: intelligence DB #176, priority: could) -2. **Shareholder accessing AGM documents online**: As a shareholder, I want to access all AGM documents (agenda, annual report, resolution proposals) through a secure online portal, so that I can prepare for the meeting at my convenience. (Source: intelligence DB #3) +31. **Griffier submitting draft minutes for approval**: As a griffier, I want to submit draft minutes with tracked corrections for approval at the next meeting. (Source: intelligence DB #177, priority: must) -3. **Secretary assembling board pack**: As a board secretary, I want to assemble board packs by combining documents from multiple sources into a structured, indexed package, so that board members receive a complete, well-organized set of meeting materials. (Source: intelligence DB #17) +32. **Archivaris auto-archiving council decisions**: As an archivaris, I want council decisions to be automatically archived with complete metadata. (Source: intelligence DB #182, priority: must) -4. **Board member declaring conflict of interest**: As a board member, I want to formally declare a conflict of interest for a specific agenda item so that I am properly excluded from the decision and this is recorded per WBTR. (Source: intelligence DB #69) +33. **Archivaris verifying archive completeness**: As an archivaris, I want to verify that all council meeting records are complete in the archive. (Source: intelligence DB #183, priority: must) -5. **Member accessing decision history**: As a member, I want to access meeting minutes, financial reports, and decision history through a self-service portal so that I can stay informed about association governance. (Source: intelligence DB #80) +34. **Raadsadviseur indexing video by agenda item**: As a raadsadviseur, I want video recordings to be indexed by agenda item for direct navigation. (Source: intelligence DB #184, priority: should) ## Acceptance Criteria -- Calendar events are created/updated/cancelled for meetings via OCP\Calendar\IManager -- Meeting folders are created in Nextcloud Files with correct access controls -- Talk conversations are created for meetings with participant auto-enrollment -- Activity feed entries are published for all major governance events -- Notifications are sent for pending votes, meeting reminders, and deadlines -- Search provider returns decisions, meetings, and resolutions from universal search -- All integrations use OCP interfaces (not direct database access or internal APIs) -- Integrations degrade gracefully when optional apps (Talk, Mail) are not installed +1. Calendar events are created/updated/cancelled for meetings via `OCP\Calendar\IManager` +2. Calendar events include meeting link, agenda summary, document links, and configured reminders +3. Meeting folders are created in Nextcloud Files with correct access controls (read for members, write for secretary/chair) +4. Board pack assembly compiles agenda documents into a structured package +5. Document version comparison is supported via Nextcloud Files versioning +6. Talk conversations are created for meetings with participant auto-enrollment +7. Persistent body Talk channels are maintained with automatic membership sync +8. Activity feed entries are published for all governance lifecycle events (decision, meeting, vote, resolution) +9. Activity entries include actor, action, timestamp, and navigable link to the entity +10. Notifications are sent for pending votes, meeting reminders, action item due dates, and quorum-at-risk +11. Notification priority and timing respect user preferences from user settings +12. Search provider returns decisions, meetings, resolutions, motions, and minutes from unified search +13. Search respects body membership access controls +14. Tasks are created for action items with bidirectional status sync +15. Open action items automatically roll over to next meeting agenda +16. Contacts integration enriches member profiles and supports external participant lookup +17. Reference provider renders rich previews for decisions, meetings, and resolutions in Talk, Text, and Mail +18. Mail integration supports convocation delivery with delivery tracking and statutory deadline calculation +19. Vote-by-email is supported for circular resolutions with configurable per-body enablement +20. All integrations degrade gracefully when optional apps are not installed +21. Admin settings show integration availability status (available/not available/disabled) +22. Audit trail satisfies WBTR documentation requirements with exportable reports +23. Archive completeness verification checks all meeting record types +24. Video recording indexing by agenda item is supported with timestamp markers +25. All integrations use OCP interfaces (not direct database access or internal APIs) diff --git a/openspec/specs/openregister-integration/spec.md b/openspec/specs/openregister-integration/spec.md index 63f42db..8bc0532 100644 --- a/openspec/specs/openregister-integration/spec.md +++ b/openspec/specs/openregister-integration/spec.md @@ -6,22 +6,57 @@ status: idea ## Purpose -OpenRegister is the data layer for Decidesk. All Decidesk entities (meetings, decisions, agenda items, votes, resolutions, bodies, process templates) are stored as OpenRegister objects with schema validation. This specification covers the register and schema definitions, the repair step that imports them, the JSON-based register configuration file, and the data access patterns used by the frontend and backend. +OpenRegister is the data layer for Decidesk. All Decidesk entities are stored as OpenRegister objects with schema validation. This specification covers the 12 entity schemas, the register configuration file, the repair step that imports them, the JSON-based register configuration, the `useObjectStore` data access pattern on the frontend, the `ObjectService`/mapper data access pattern on the backend, and the `ConfigurationService` import mechanism. -**Standards**: OpenAPI 3.0.0 (register config format), JSON Schema (validation), Schema.org (type annotations) +**Standards**: OpenAPI 3.0.0 (register config format), JSON Schema (validation), Schema.org (type annotations), Akoma Ntoso (legislative document types) **Feature tier**: MVP +**Evidence sources**: Intelligence DB user stories #6, #23, #29, #38, #43, #55, #56, #62, #66, #71, #73, #126, #129, #160, #181, #189, #206, #207, #262, #263, #264, #272, #280, #281, #286; Requirement clusters #43 (Besluitvorming, 271 reqs/133 tenders), #54 (e-Depot digital archive, 247 reqs/117 tenders), #55 (Document creation/generation, 298 reqs/116 tenders); Category features: document-storage, search-filter, document-linking, full-text-search + ## Data Model -The register configuration file `lib/Settings/decidesk_register.json` defines all schemas in OpenAPI 3.0.0 format. See [ARCHITECTURE.md](../../docs/ARCHITECTURE.md) for entity property tables and type mappings. +The register configuration file `lib/Settings/decidesk_register.json` defines all 12 schemas in OpenAPI 3.0.0 format. The schemas form a connected graph of governance entities: + +``` +Organization + └── Body (1:N) + ├── Member (N:M via membership) + ├── ProcessTemplate (1:N) + └── Meeting (1:N) + ├── AgendaItem (1:N, ordered) + │ ├── Motion (0:N) + │ │ └── Amendment (0:N) + │ └── Decision (0:1) + │ ├── Vote (1:N per VotingRound) + │ │ └── Ballot (1:N) + │ └── Resolution (0:1) + └── Minutes (0:1) +``` + +### Schema Overview + +| Schema | @type | Purpose | Key Properties | +|--------|-------|---------|----------------| +| Organization | schema:Organization | Top-level entity | name, legalForm, logo, language, timezone | +| Body | schema:GovernmentOrganization | Governing body | name, type, members, quorumRules, defaultTemplate | +| Meeting | schema:Event | Scheduled meeting | title, dateTime, location, body, status, agenda | +| AgendaItem | schema:ListItem | Ordered agenda entry | title, position, type, documents, decision | +| Motion | akomaNtoso:motion | Formal proposal | title, text, proposer, status, linkedAgendaItem | +| Amendment | akomaNtoso:amendment | Motion modification | text, proposer, parentMotion, status | +| Decision | schema:ChooseAction | Outcome of deliberation | title, status, votingRound, resolution, body | +| Vote | schema:VoteAction | Voting round | method, majorityRule, status, deadline, ballots | +| Ballot | schema:ChooseAction | Individual vote cast | voter, choice, timestamp, proxy | +| Resolution | akomaNtoso:act | Formal adopted decision | title, text, decisionDate, body, status | +| Minutes | schema:DigitalDocument | Meeting record | meeting, text, status, approvedBy, approvedDate | +| ProcessTemplate | schema:HowTo | Workflow template | name, steps, mandatoryAgendaItems, bodyType | ## Requirements --- -### Requirement: Register Configuration File +### REQ-OR-01: Register Configuration File -The system MUST define all Decidesk schemas in a single `lib/Settings/decidesk_register.json` file using OpenAPI 3.0.0 format. The file MUST define schemas for: `meeting`, `agendaItem`, `decision`, `vote`, `votingRound`, `motion`, `amendment`, `resolution`, `minutes`, `body`, `processTemplate`, `actionItem`, and `member`. +The system MUST define all Decidesk schemas in a single `lib/Settings/decidesk_register.json` file using OpenAPI 3.0.0 format. The file MUST define schemas for all 12 entity types listed above with proper `@type` annotations, required properties, property types, and validation rules. **Feature tier**: MVP @@ -29,16 +64,17 @@ The system MUST define all Decidesk schemas in a single `lib/Settings/decidesk_r - GIVEN the `decidesk_register.json` file - WHEN it is parsed by OpenRegister's ConfigurationService -- THEN it MUST contain a valid OpenAPI 3.0.0 document with `components.schemas` for all entity types +- THEN it MUST contain a valid OpenAPI 3.0.0 document with `components.schemas` for all 12 entity types - AND each schema MUST include `@type` with the appropriate Schema.org or Akoma Ntoso type annotation -- AND each schema MUST define required properties, property types, and validation rules +- AND each schema MUST define required properties, property types, and validation rules (format, minLength, maxLength, enum) -#### Scenario: Schema properties match ARCHITECTURE.md definitions +#### Scenario: Schema properties match data model definitions -- GIVEN the entity definitions in ARCHITECTURE.md +- GIVEN the entity definitions in the data model section - WHEN comparing with the register config schemas -- THEN all properties defined in ARCHITECTURE.md MUST be present in the corresponding schema +- THEN all properties defined in the data model MUST be present in the corresponding schema - AND property types and validation rules MUST match +- AND cross-references between schemas MUST use `$ref` or UUID string references #### Scenario: Register config includes cross-references between schemas @@ -46,10 +82,11 @@ The system MUST define all Decidesk schemas in a single `lib/Settings/decidesk_r - WHEN the register is imported - THEN OpenRegister MUST validate referential integrity between objects - AND the frontend MUST be able to resolve references for display +- AND cascade behavior (e.g., deleting a meeting soft-deletes its agenda items) MUST be defined --- -### Requirement: Repair Step Import +### REQ-OR-02: Repair Step Import The system MUST import the register configuration during app installation and upgrade via a Nextcloud repair step. The repair step MUST use `ConfigurationService::importFromApp()` to create or update the `decidesk` register and all schemas. @@ -60,22 +97,31 @@ The system MUST import the register configuration during app installation and up - GIVEN a fresh Nextcloud installation with Decidesk enabled - WHEN the repair step runs - THEN a register named `decidesk` MUST be created in OpenRegister -- AND all schemas from `decidesk_register.json` MUST be imported -- AND the register MUST be ready for data storage +- AND all 12 schemas from `decidesk_register.json` MUST be imported +- AND the register MUST be ready for data storage immediately #### Scenario: App upgrade updates schemas without data loss -- GIVEN an existing Decidesk installation with data +- GIVEN an existing Decidesk installation with data (meetings, decisions, votes) - WHEN the app is upgraded and the repair step runs - THEN schema changes MUST be applied to the `decidesk` register - AND existing data MUST be preserved - AND new properties MUST have default values where applicable +- AND removed properties MUST NOT cause data corruption + +#### Scenario: Repair step is idempotent + +- GIVEN a Decidesk installation where the repair step has already run +- WHEN the repair step runs again (e.g., via `occ maintenance:repair`) +- THEN the register and schemas MUST remain unchanged if no config changes exist +- AND no duplicate schemas MUST be created +- AND existing data MUST NOT be affected --- -### Requirement: Frontend Data Access Pattern +### REQ-OR-03: Frontend Data Access via useObjectStore -The frontend MUST access Decidesk data via the OpenRegister API using `useObjectStore` from `@conduction/nextcloud-vue`. The frontend MUST NOT make direct API calls to a Decidesk backend for CRUD operations. +The frontend MUST access Decidesk data via the OpenRegister API using `useObjectStore` from `@conduction/nextcloud-vue`. The frontend MUST NOT make direct API calls to a Decidesk backend for CRUD operations. Each entity type MUST have its own store instance configured with the correct register and schema. **Feature tier**: MVP @@ -93,13 +139,29 @@ The frontend MUST access Decidesk data via the OpenRegister API using `useObject - WHEN they submit the form - THEN the frontend MUST use `useObjectStore.save()` to create the object in OpenRegister - AND the object MUST be validated against the `meeting` schema by OpenRegister -- AND validation errors MUST be displayed to the user +- AND validation errors MUST be displayed to the user with field-level messages + +#### Scenario: Update an existing agenda item + +- GIVEN a user editing an agenda item's position or title +- WHEN they save the changes +- THEN the frontend MUST use `useObjectStore.save()` with the existing object UUID +- AND OpenRegister MUST validate the update against the `agendaItem` schema +- AND optimistic locking MUST prevent concurrent edit conflicts + +#### Scenario: Delete a motion with cascade + +- GIVEN a motion with 2 amendments +- WHEN the user deletes the motion +- THEN `useObjectStore.delete()` MUST remove the motion from OpenRegister +- AND all linked amendments MUST be handled according to cascade rules (soft-delete or orphan) +- AND the UI MUST update reactively to reflect the deletion --- -### Requirement: Backend Service Access +### REQ-OR-04: Backend Service Access -Backend services (VotingService, WorkflowService) MUST access OpenRegister data via the ObjectService or mapper classes. The backend MUST NOT maintain its own database tables for Decidesk entities. +Backend services (VotingService, WorkflowService, ConvocationService) MUST access OpenRegister data via the `ObjectService` or mapper classes (`ObjectMapper`). The backend MUST NOT maintain its own database tables for Decidesk entities. **Feature tier**: MVP @@ -107,10 +169,209 @@ Backend services (VotingService, WorkflowService) MUST access OpenRegister data - GIVEN a voting round in progress - WHEN the VotingService needs to calculate results -- THEN it MUST query OpenRegister for all vote objects linked to the voting round -- AND it MUST use the ObjectService or VoteMapper to retrieve the data +- THEN it MUST query OpenRegister for all ballot objects linked to the voting round +- AND it MUST use the `ObjectService` or `ObjectMapper` to retrieve the data - AND calculations MUST be performed on the retrieved data without caching in a separate table +#### Scenario: WorkflowService advances decision status + +- GIVEN a decision in "deliberating" status +- WHEN the WorkflowService processes a status transition to "voting" +- THEN it MUST update the decision object in OpenRegister via `ObjectService::saveObject()` +- AND the status change MUST be validated against the `processTemplate` workflow steps +- AND the transition MUST be logged in the Nextcloud Activity feed + +#### Scenario: ConvocationService generates member list + +- GIVEN a meeting being convoked for body "ALV" with 200 members +- WHEN the ConvocationService retrieves the member list +- THEN it MUST query OpenRegister for all member objects linked to the body +- AND it MUST filter by active membership status and voting rights +- AND it MUST resolve Nextcloud user accounts for email delivery + +--- + +### REQ-OR-05: Organization Schema + +The `organization` schema MUST store the top-level organization configuration with properties for identity, localization, and governance defaults. + +**Feature tier**: MVP + +#### Scenario: Store organization with full configuration + +- GIVEN an administrator configuring the organization +- WHEN they save the organization settings +- THEN the object MUST be stored with properties: name (required, string), legalForm (required, enum: vereniging/stichting/cooperatie/nv/bv), logo (string, file reference), defaultLanguage (enum: nl/en), timezone (string), currency (string, default: EUR), retentionPeriodYears (integer) +- AND the `@type` MUST be `schema:Organization` +- AND only one organization object MUST exist per Decidesk installation + +--- + +### REQ-OR-06: Body Schema + +The `body` schema MUST store governing body definitions including membership, roles, quorum rules, and template assignments. + +**Feature tier**: MVP + +#### Scenario: Store body with members and quorum rules + +- GIVEN a body "Bestuur" with 5 members +- WHEN the body is saved to OpenRegister +- THEN the object MUST include: name (required), type (required, enum: council/board/assembly/committee/team/ledenraad), members (array of member references), quorumRules (object with type, threshold, proxyLimit), defaultTemplate (processTemplate reference), parentBody (optional body reference) +- AND the `@type` MUST be `schema:GovernmentOrganization` + +--- + +### REQ-OR-07: Meeting and AgendaItem Schemas + +The `meeting` schema MUST store meeting metadata and link to agenda items. The `agendaItem` schema MUST store ordered agenda entries with document references and decision links. + +**Feature tier**: MVP + +#### Scenario: Store meeting with ordered agenda + +- GIVEN a meeting with 8 agenda items +- WHEN the meeting is saved +- THEN the meeting object MUST include: title, dateTime (ISO 8601), endDateTime, location, body (reference), status (enum: draft/convoked/in_progress/completed/cancelled), agendaItems (ordered array of references) +- AND each agendaItem MUST include: title, position (integer), type (enum: decision/information/discussion/procedural), documents (array of file references), timeAllocation (minutes), decision (optional reference) + +--- + +### REQ-OR-08: Motion and Amendment Schemas + +The `motion` schema MUST store formal proposals. The `amendment` schema MUST store modifications to motions with parent references. + +**Feature tier**: MVP + +#### Scenario: Store motion with amendments + +- GIVEN a motion "Approve Budget 2026" with 2 amendments +- WHEN the motion and amendments are saved +- THEN the motion MUST include: title, text (rich text), proposer (member reference), coSigners (array), linkedAgendaItem (reference), status (enum: submitted/under_debate/voted/adopted/rejected/withdrawn) +- AND each amendment MUST include: text, proposer, parentMotion (reference), status, type (enum: addition/deletion/replacement) +- AND amendments MUST be votable independently before the main motion + +--- + +### REQ-OR-09: Decision, Vote, and Ballot Schemas + +The `decision` schema MUST store deliberation outcomes. The `vote` schema MUST store voting round configuration. The `ballot` schema MUST store individual votes cast. + +**Feature tier**: MVP + +#### Scenario: Store decision with voting round and ballots + +- GIVEN a decision that has been voted on +- WHEN the full decision record is stored +- THEN the decision MUST include: title, description, status (enum: proposed/deliberating/voting/adopted/rejected/deferred/withdrawn), body (reference), meeting (reference), agendaItem (reference), resolution (optional reference) +- AND the vote MUST include: method (enum: open/roll_call/secret_ballot/digital), majorityRule (enum: simple/absolute/qualified_two_thirds/unanimous), status (enum: pending/open/closed), deadline (ISO 8601), ballots (array of references), result (object with forCount, againstCount, abstainCount, absentCount) +- AND each ballot MUST include: voter (member reference, nullable for secret ballot), choice (enum: for/against/abstain/blank), timestamp, isProxy (boolean), proxyFor (optional member reference) + +--- + +### REQ-OR-10: Resolution and Minutes Schemas + +The `resolution` schema MUST store formally adopted decisions. The `minutes` schema MUST store meeting records. + +**Feature tier**: MVP + +#### Scenario: Store resolution with full provenance + +- GIVEN a resolution adopted by the ALV +- WHEN the resolution is stored +- THEN the resolution MUST include: title, text (rich text), decisionDate (ISO date), body (reference), meeting (reference), decision (reference), sequenceNumber (integer, auto-increment per body per year), status (enum: draft/adopted/published/archived), effectiveDate (optional), expiryDate (optional) +- AND the `@type` MUST be `akomaNtoso:act` + +#### Scenario: Store minutes with approval workflow + +- GIVEN minutes drafted after a board meeting +- WHEN the minutes are stored +- THEN the minutes MUST include: meeting (reference), text (rich text), status (enum: draft/submitted/approved/published), author (member reference), approvedBy (array of member references), approvedDate (optional), corrections (array of text changes with submitter) +- AND the `@type` MUST be `schema:DigitalDocument` + +--- + +### REQ-OR-11: ProcessTemplate Schema + +The `processTemplate` schema MUST store workflow definitions that govern how decisions progress through stages. + +**Feature tier**: MVP + +#### Scenario: Store process template with workflow steps + +- GIVEN a template "ALV Standard Decision" +- WHEN the template is stored +- THEN the template MUST include: name, description, bodyType (enum matching body types), steps (ordered array with name, type, requiredRole, duration), mandatoryAgendaItems (array of agenda item definitions), votingDefaults (object with method, majorityRule), quorumDefaults (object with type, threshold) +- AND steps MUST define valid transitions between statuses + +--- + +### REQ-OR-12: Data Integrity and Validation + +The system MUST ensure data integrity across all schemas through OpenRegister's validation layer. Cross-references MUST be validated, required fields MUST be enforced, and enum values MUST be constrained. + +**Feature tier**: MVP + +#### Scenario: Reject invalid cross-reference + +- GIVEN a decision referencing a non-existent meeting UUID +- WHEN the decision is saved via the API +- THEN OpenRegister MUST reject the save with a 422 validation error +- AND the error MUST identify the invalid reference field and the missing UUID + +#### Scenario: Enforce required fields on meeting creation + +- GIVEN a meeting creation request missing the required `body` field +- WHEN the request is processed +- THEN OpenRegister MUST reject the request with a 422 error +- AND the error MUST list all missing required fields + +#### Scenario: Validate enum values for decision status + +- GIVEN a decision update with status "invalid_status" +- WHEN the update is processed +- THEN OpenRegister MUST reject the update with a 422 error specifying the allowed enum values +- AND the decision MUST remain unchanged + +--- + +### REQ-OR-13: Query Patterns and Performance + +The system MUST support efficient query patterns for common governance operations: meetings by body, decisions by status, votes by voting round, action items by assignee, and resolutions by date range. + +**Feature tier**: MVP + +#### Scenario: Query upcoming meetings for a body + +- GIVEN a body "Bestuur" with 20 past and 3 upcoming meetings +- WHEN the frontend queries meetings with filter `body=&dateTime[gte]=now&_order[dateTime]=ASC` +- THEN OpenRegister MUST return only the 3 upcoming meetings in chronological order +- AND the response MUST include pagination metadata (total, page, limit) + +#### Scenario: Query voting results for a decision + +- GIVEN a decision with a completed voting round containing 50 ballots +- WHEN the backend queries ballots with filter `vote=` +- THEN OpenRegister MUST return all 50 ballot objects +- AND the response MUST be efficient (indexed query, not full table scan) + +--- + +### REQ-OR-14: Seed Data + +The system MUST provide optional seed data for demonstration and testing. Seed data MUST include sample organizations, bodies, meetings, decisions, and process templates representing common governance scenarios. + +**Feature tier**: V1 + +#### Scenario: Install seed data for demo environment + +- GIVEN a fresh Decidesk installation with OpenRegister +- WHEN the administrator runs the seed data import (via admin setting or CLI) +- THEN the system MUST create a sample organization "Demo Vereniging" with bodies (Bestuur, ALV, Kascommissie) +- AND sample process templates MUST be created for standard decision, statute amendment, and board election +- AND 3 sample meetings with agenda items and decisions MUST be created +- AND seed data MUST be clearly marked as sample data and easily removable + ## User Stories 1. **Administrator setting up Decidesk**: As an administrator, I want Decidesk to automatically create its data schemas when installed so that the app is ready to use without manual database configuration. (Source: OpenRegister integration pattern) @@ -119,12 +380,71 @@ Backend services (VotingService, WorkflowService) MUST access OpenRegister data 3. **Frontend developer querying decisions**: As a frontend developer, I want to use the standard useObjectStore composable to query decisions so that I do not need to implement custom API clients or state management. (Source: @conduction/nextcloud-vue pattern) +4. **Secretary recording board decisions with vote distribution**: As a secretary, I want to record each board decision with the vote distribution per board member so that we comply with WBTR documentation requirements. (Source: intelligence DB #66, priority: high) + +5. **Secretary maintaining digital conflict of interest register**: As a board secretary, I want to maintain a digital conflict of interest register with audit trail, so that potential conflicts are proactively identified. (Source: intelligence DB #23, priority: must) + +6. **Audit committee tracking findings**: As an audit committee member, I want to review audit findings and track management remediation across committee meetings. (Source: intelligence DB #29, priority: must) + +7. **Secretary maintaining shareholder register**: As a board secretary, I want to maintain a digital shareholder register with automatic updates for share transfers. (Source: intelligence DB #38, priority: must) + +8. **Secretary organizing document archive**: As a board secretary, I want a structured, searchable governance document archive with access controls and retention enforcement. (Source: intelligence DB #43, priority: must) + +9. **Secretary registering attendance and verifying quorum**: As secretary, I want to register attendance and automatically calculate quorum including proxy votes. (Source: intelligence DB #55, priority: critical) + +10. **Secretary verifying voting rights**: As secretary, I want to verify each attendee's voting rights so that only eligible members participate. (Source: intelligence DB #56, priority: critical) + +11. **Kascommissie performing financial audit**: As a kascommissie member, I want a structured audit checklist and access to all financial records. (Source: intelligence DB #71, priority: critical) + +12. **Committee member submitting report**: As a committee member, I want to submit reports using a standard template so the board can act on our advice. (Source: intelligence DB #73, priority: medium) + +13. **Employee searching decision register**: As an employee, I want to search a central decision register by topic, date, meeting, or decision-maker. (Source: intelligence DB #129, priority: high) + +14. **Citizen registering to speak**: As a burger, I want to register online to speak at a committee meeting about an agenda item that affects me. (Source: intelligence DB #160, priority: must) + +15. **Wethouder reporting on decision implementation**: As a wethouder, I want to report on the implementation progress of council decisions. (Source: intelligence DB #181, priority: should) + +16. **ICT beheerder publishing council data via ORI API**: As an ICT beheerder, I want council meeting data to be published via the Open Raadsinformatie API. (Source: intelligence DB #189, priority: should) + +17. **ICT beheerder migrating historical data**: As an ICT beheerder, I want to migrate all historical council data from the old RIS to the new system. (Source: intelligence DB #206, priority: must) + +18. **ICT beheerder validating migrated data**: As an ICT beheerder, I want to validate that all migrated data is complete and correctly structured. (Source: intelligence DB #207, priority: must) + +19. **Records manager auto-populating MDTO metadata**: As a records manager, I want the system to auto-populate metadata fields from context. (Source: intelligence DB #262, priority: critical) + +20. **Information manager validating MDTO metadata**: As an information manager, I want to validate records against the MDTO schema for eDepot transfer. (Source: intelligence DB #263, priority: critical) + +21. **Records manager inheriting metadata from dossier**: As a records manager, I want records to inherit metadata from their parent dossier. (Source: intelligence DB #264, priority: high) + +22. **Compliance officer verifying destruction**: As a compliance officer, I want to verify destruction completeness and generate compliance reports. (Source: intelligence DB #272, priority: high) + +23. **Compliance officer maintaining tamper-evident audit log**: As a compliance officer, I want a tamper-evident audit log recording every action on every record. (Source: intelligence DB #281, priority: critical) + +24. **Records manager performing faceted search**: As a records manager, I want to filter search results using metadata facets. (Source: intelligence DB #286, priority: high) + +25. **Proxy advisor accessing standardized resolution data**: As a proxy advisor, I want machine-readable resolution data via API. (Source: intelligence DB #6, priority: could) + ## Acceptance Criteria -- All Decidesk schemas are defined in `lib/Settings/decidesk_register.json` (OpenAPI 3.0.0 format) -- Repair step creates/updates the `decidesk` register via ConfigurationService::importFromApp() -- Frontend uses useObjectStore from @conduction/nextcloud-vue for all CRUD -- Backend uses ObjectService/mappers for data access (no own DB tables) -- Schema.org type annotations are set on all entities -- Cross-references between entities are validated by OpenRegister -- App upgrade preserves existing data while applying schema changes +1. All 12 Decidesk schemas are defined in `lib/Settings/decidesk_register.json` using OpenAPI 3.0.0 format +2. Each schema has a `@type` annotation (Schema.org or Akoma Ntoso) +3. Repair step creates/updates the `decidesk` register via `ConfigurationService::importFromApp()` +4. Repair step is idempotent (safe to run multiple times) +5. App upgrade preserves existing data while applying schema changes +6. Frontend uses `useObjectStore` from `@conduction/nextcloud-vue` for all CRUD operations +7. Each entity type has its own store instance with correct register and schema configuration +8. Backend uses `ObjectService`/`ObjectMapper` for data access (no own DB tables) +9. Cross-references between entities are validated by OpenRegister +10. Required fields are enforced at the schema level +11. Enum values are constrained for all status fields +12. Decision status follows the workflow: proposed -> deliberating -> voting -> adopted/rejected/deferred/withdrawn +13. Ballot choices are constrained to: for, against, abstain, blank +14. Body types are constrained to: council, board, assembly, committee, team, ledenraad +15. Meeting statuses are constrained to: draft, convoked, in_progress, completed, cancelled +16. Resolution sequence numbers auto-increment per body per year +17. Minutes approval workflow tracks corrections, approvers, and approval date +18. ProcessTemplate defines valid status transitions and mandatory agenda items +19. Query patterns support efficient filtering by body, status, date range, and assignee +20. Seed data is available for demonstration with clearly marked sample data +21. All validation errors return 422 with field-level error messages +22. Cascade behavior is defined for parent-child relationships (e.g., meeting -> agendaItems) diff --git a/openspec/specs/process-configuration/spec.md b/openspec/specs/process-configuration/spec.md index 1fc8c87..1670629 100644 --- a/openspec/specs/process-configuration/spec.md +++ b/openspec/specs/process-configuration/spec.md @@ -8,9 +8,52 @@ status: idea Process configuration enables administrators to define and customize decision-making workflows for different governance contexts. A process template defines the state machine, voting rules, quorum requirements, and procedural rules for a specific type of decision or meeting. The system uses YAML-based Symfony Workflow definitions for state machines and DMN-inspired decision tables for voting rules. This allows Decidesk to serve municipal councils, corporate boards, associations, and operational teams with their own procedural rules. -**Standards**: Symfony Workflow Component (YAML config), DMN (Decision Model and Notation) for voting rules, Schema.org (`HowTo`, `HowToStep`) +**Standards**: Symfony Workflow Component (YAML config), DMN (Decision Model and Notation) for voting rules, XState (frontend visualization), Schema.org (`HowTo`, `HowToStep`) **Feature tier**: V1 +## Evidence Base + +### Market Research + +| Statistic | Source | +|-----------|--------| +| No competitor covers all 5 decision-making domains (legislative, association, corporate governance, operations, citizen participation) | Intelligence DB insight #7 | +| Diligent Boards costs $48K-$155K/year, creating massive market gap for open-source alternative | Intelligence DB insight #8 | +| Board portal market growing at 11-20% CAGR, expected $5-7B by 2030 | Intelligence DB insight #3 | +| 74% of nonprofits want digital transformation but only 12% are digitally mature | Intelligence DB insight #4 (IEEE) | +| Only 45% of boards deemed effective (Gartner benchmark) | External source #172 (Gartner Peer Insights) | + +### Technology Evaluation + +| Technology | Verdict | Evidence | +|------------|---------|----------| +| Symfony Workflow Component | **Selected** -- PHP-native state machine with YAML config, guards, event-driven audit trail | External source #301; Intelligence DB insight #11 | +| XState 5 | **Selected for frontend** -- serializable JSON machine definitions, visual statechart diagrams, @xstate/vue integration | External source #300, #318; Intelligence DB insight #12 | +| DMN decision tables | **Adapted** -- DMN-inspired decision tables in PHP for configurable voting rules (not full engine) | External source #283; Intelligence DB insight #13 | +| Full BPMN engines (Camunda, Flowable) | **Rejected** -- Java-based, significant infrastructure overhead, overkill for this use case | External source #282; Intelligence DB insight #14 | +| UML Harel Statecharts | **Informed design** -- hierarchical states, parallel regions, guard conditions inform our state machine design | External source #286 | + +### Legal Requirements + +| Requirement | Source | Impact | +|-------------|--------|--------| +| Gemeentewet Art. 20/29/30 -- quorum >50%, absolute majority, secret ballot for appointments | Intelligence DB insight #17 | Non-negotiable system requirements for municipal templates | +| BW 2:230/238 -- statutes can specify custom majority/quorum; written procedure requires unanimous consent to METHOD | Intelligence DB insight #18 | Templates must support configurable majority types | +| Awb Art. 1:3 -- decisions must be written with motivation | Intelligence DB insight #16 | Every decision record must capture motivation | +| WDAV -- digital ALV law pending (July 2026 deadline) | Intelligence DB insight #20 | Association templates must comply with WDAV | +| Dutch Corporate Governance Code 2025 -- digitalisation knowledge required | External source #197 | Corporate templates must support comply-or-explain | + +### Competitor Analysis + +| Competitor | Relevant Features | Gap | +|------------|-------------------|-----| +| Diligent Boards | Action item tracking, compliance automation, AI analytics | No configurable process templates, $48K-$155K/year | +| iBabs | Quorum tracking, digital voting, ISO-certified | Fixed workflow, no state machine configuration | +| Fellow.app | Action item tracking, meeting templates | No formal voting, no governance workflows | +| Loomio | Consent-based decisions, discuss-vote-record | No state machine, limited process customization | +| OpenSlides | Legislative workflow, motion management | Known security vulnerabilities (X41 advisory 2025) | +| Decisions.com | Smart timer, AI agenda, decision capture | Microsoft Teams only, no self-hosted | + ## Data Model See [ARCHITECTURE.md](../../docs/ARCHITECTURE.md) for the full ProcessTemplate entity definition. @@ -33,6 +76,7 @@ The system MUST support creating, editing, and managing process templates. Each - AND the template MUST specify voting rule: simple majority (50%+1 of votes cast) - AND the template MUST specify quorum: 50%+1 of total members present or represented - AND the template MUST be assignable to the "ALV" body +- AND the template MUST comply with WDAV requirements for digital meetings (intelligence DB insight #20) #### Scenario: Create a process template for statute amendments @@ -41,6 +85,7 @@ The system MUST support creating, editing, and managing process templates. Each - THEN the template MUST specify voting rule: qualified majority (2/3 of votes cast) - AND the template MUST specify quorum: 2/3 of total members present - AND the template MUST include a required legal review step before voting +- AND the template MUST reference BW 2:230 requirements (intelligence DB insight #18) #### Scenario: Duplicate and customize an existing template @@ -50,36 +95,95 @@ The system MUST support creating, editing, and managing process templates. Each - AND the administrator MUST be able to modify states, transitions, and rules independently - AND the original template MUST remain unchanged +#### Scenario: Import template from YAML definition + +- GIVEN an administrator with a Symfony Workflow YAML configuration file +- WHEN they import the YAML into Decidesk +- THEN the system MUST validate the YAML syntax against Symfony Workflow Component schema +- AND the system MUST create a process template with the defined states, transitions, and guards +- AND the imported template MUST be editable through the admin UI + --- -### Requirement: State Machine Configuration +### Requirement: Symfony Workflow State Machine Configuration -The system MUST support defining state machines as YAML-based Symfony Workflow configurations. Each state MUST have a name, optional description, and optional metadata (e.g., required approvers, time limits). Transitions MUST define from-state, to-state, guard conditions, and triggered actions. +The system MUST support defining state machines as YAML-based Symfony Workflow configurations. Each state MUST have a name, optional description, and optional metadata (e.g., required approvers, time limits). Transitions MUST define from-state, to-state, guard conditions, and triggered actions. The backend MUST use the Symfony Workflow Component (PHP) for state machine execution. **Feature tier**: V1 +**Evidence**: Symfony Workflow provides native state machine with parallel states, guards, event-driven audit trail, and YAML configuration. Best fit for Nextcloud because PHP-native (external source #301; insight #11). #### Scenario: Define a custom state machine with guard conditions - GIVEN an administrator editing a process template -- WHEN they add a transition "start_voting" from "debating" to "voting" with guard condition "quorum_met AND all_amendments_resolved" +- WHEN they add a transition "start_voting" from "debating" to "voting" with guard condition `quorum_met AND all_amendments_resolved` - THEN the system MUST validate the YAML syntax -- AND the guard condition MUST be enforced at runtime +- AND the guard condition MUST be enforced at runtime via Symfony Workflow guards - AND the transition MUST only be allowed when both conditions are true +- AND the guard evaluation MUST be logged in the audit trail (external source #311) + +#### Scenario: Configure parallel states for committee and plenary tracks + +- GIVEN a municipal council process template +- WHEN the administrator defines parallel states for committee review and legal review +- THEN both reviews MUST be able to proceed simultaneously +- AND the transition to plenary debate MUST require both reviews to be completed +- AND this MUST use Symfony Workflow's marking store for multiple active places (external source #301) -#### Scenario: Visualize the state machine +#### Scenario: Define timed transitions with automatic escalation + +- GIVEN a process template with a "review" state +- WHEN the administrator sets a 7-day timeout on the "review" state +- THEN the system MUST automatically trigger an escalation transition after 7 days without action +- AND stakeholders MUST receive notifications at configurable intervals before the deadline (insight #31) + +#### Scenario: Audit trail for every state transition + +- GIVEN a decision object moving through a process template +- WHEN any state transition occurs +- THEN the system MUST record: WHO (actor), WHAT (transition name), WHEN (timestamp), WHY (guard conditions met), and HOW (manual/automatic) (external source #311) +- AND the audit trail MUST be immutable and linked to the decision object + +--- + +### Requirement: XState Frontend Visualization + +The system MUST provide a visual state machine diagram on the frontend using XState. The diagram MUST show all states and transitions from the process template and highlight the current state when viewing a specific decision. + +**Feature tier**: V1 +**Evidence**: XState implements Harel statecharts in JS/TS with serializable JSON machine definitions, @xstate/vue integration, and visual statechart diagrams (external source #300, #318; insight #12). + +#### Scenario: Visualize the state machine in the admin UI - GIVEN a process template with a defined state machine - WHEN the administrator views the template -- THEN the system MUST display a visual state machine diagram showing all states and transitions -- AND the current state MUST be highlighted when viewing a specific decision +- THEN the system MUST display a visual state machine diagram using XState rendering +- AND states MUST be shown as nodes with transition arrows between them +- AND guard conditions MUST be visible on transition labels + +#### Scenario: Highlight current state for a specific decision + +- GIVEN a decision in the "debating" state using a process template +- WHEN a user views the decision detail +- THEN the state machine diagram MUST highlight the "debating" state +- AND available transitions MUST be visually distinguished from unavailable ones +- AND completed transitions MUST show completion timestamps + +#### Scenario: Backend-frontend state synchronization + +- GIVEN a Symfony Workflow YAML definition on the backend +- WHEN the process template is loaded on the frontend +- THEN the system MUST generate an XState-compatible JSON definition from the Symfony YAML +- AND the frontend state machine MUST mirror the backend state machine exactly +- AND the frontend MUST NOT be authoritative -- all transitions MUST be validated server-side --- -### Requirement: Voting Rule Configuration +### Requirement: DMN-Inspired Voting Rule Configuration -The system MUST support configurable voting rules using DMN-inspired decision tables. Rules MUST specify: majority type (simple, qualified, unanimous), quorum threshold, abstention handling (counted or excluded), tie-breaking method, and secret ballot requirement. +The system MUST support configurable voting rules using DMN-inspired decision tables. Rules MUST specify: majority type (simple, qualified, unanimous), quorum threshold, abstention handling (counted or excluded), tie-breaking method, and secret ballot requirement. The decision table approach allows complex voting rules to be configured without code changes. **Feature tier**: V1 +**Evidence**: DMN provides standard notation for decision tables with hit policies (Unique, Any, Priority, Collect). Can model voting rules as decision tables with conditions and outcomes (external source #283; insight #13). #### Scenario: Configure a voting rule with abstention handling @@ -95,14 +199,93 @@ The system MUST support configurable voting rules using DMN-inspired decision ta - WHEN the administrator configures weighted voting based on share ownership - THEN each member's vote weight MUST be proportional to their shares - AND the system MUST calculate results based on weighted totals, not headcount +- AND split votes MUST be supported (e.g., 60% for, 40% against on same shareholding) per Lumi Global pattern (external source #264) + +#### Scenario: Configure consent-based decision rules + +- GIVEN an organization using sociocracy +- WHEN the administrator configures a consent-based voting rule +- THEN the rule MUST define: proposal round, reaction round, objection round, integration round (external source #256) +- AND the decision MUST be adopted when no objections remain (not requiring explicit approval) +- AND each round MUST support configurable time limits + +#### Scenario: Configure quadratic voting for prioritization + +- GIVEN an organization wanting intensity-of-preference voting +- WHEN the administrator configures quadratic voting +- THEN voters MUST be allocated a vote budget (credits) +- AND the cost of votes MUST follow quadratic scaling (1 vote = 1 credit, 2 votes = 4, 3 votes = 9) +- AND this prevents tyranny of the majority while allowing preference signaling (external source #254) + +#### Scenario: Configure silence/written procedure + +- GIVEN a board using written decision procedures (besluitvorming buiten vergadering) +- WHEN the administrator configures a silence procedure +- THEN a draft decision MUST be circulated to all members with a deadline (24-72 hours) +- AND the decision MUST be automatically adopted if no objections within the deadline (external source #308) +- AND BW 2:238 unanimous consent to the METHOD MUST be tracked separately from consent to the decision (insight #18) + +#### Scenario: Secret ballot enforcement for appointments + +- GIVEN a municipal council template for appointments (Gemeentewet Art. 31) +- WHEN a vote concerns appointment or dismissal of persons +- THEN the voting rule MUST enforce secret ballot automatically +- AND individual votes MUST NOT be recorded or attributable (external source #273; insight #17) --- ### Requirement: Built-in Process Templates -The system MUST ship with built-in process templates for common governance contexts: association ALV, association board, corporate board (BV), municipal council, and operational team meeting. Built-in templates MUST be read-only but duplicable for customization. +The system MUST ship with built-in process templates for common governance contexts. Built-in templates MUST be read-only but duplicable for customization. Templates MUST encode domain-specific legal requirements. **Feature tier**: V1 +**Evidence**: 5 governance domains identified in intelligence DB, each with distinct procedural requirements. Market is completely siloed -- no competitor covers all 5 (insight #7). + +#### Built-in template: Association ALV (Algemene Ledenvergadering) + +- States: draft, proposed, agenda_published, debating, voting, adopted, rejected, enacted +- Quorum: >50% of members present or represented (configurable per statutes) +- Voting: simple majority (50%+1 of votes cast); 2/3 for statute amendments +- Legal basis: BW Book 2, WBTR, WDAV +- Special rules: proxy voting, written procedure option (BW 2:238) + +#### Built-in template: Association Board Meeting + +- States: draft, proposed, discussed, decided, enacted +- Quorum: >50% of board members +- Voting: simple majority (configurable) +- Special rules: unanimous written decisions allowed, conflict of interest abstention + +#### Built-in template: Corporate Board (BV/NV) + +- States: draft, proposed, management_review, supervisory_approval, enacted, archived +- Quorum: configurable per statutes +- Voting: depends on statutes (simple, qualified, or unanimous) +- Legal basis: BW Book 2, Dutch Corporate Governance Code +- Special rules: comply-or-explain tracking (external source #197), weighted voting by shares + +#### Built-in template: Municipal Council (Gemeenteraad) + +- States: draft, commission_review, BOB_beeldvorming, BOB_oordeelsvorming, BOB_besluitvorming, voting, adopted, rejected, enacted +- Quorum: >50% of seated members (Gemeentewet Art. 20); second meeting can proceed without quorum (Art. 29) +- Voting: absolute majority of votes cast; secret ballot for appointments +- Legal basis: Gemeentewet Art. 20/29/30/31/32 +- Special rules: tie in non-full meeting = postpone; tie in full meeting = rejected (external source #292) +- BOB phases: Beeldvorming, Oordeelsvorming, Besluitvorming tracked per agenda item (external source #337) + +#### Built-in template: Operational Team Meeting (MT) + +- States: proposed, discussing, decided, action_assigned, completed +- Quorum: none required (configurable) +- Voting: consensus or simple majority +- Special rules: DACI framework integration (Driver, Approver, Contributor, Informed) per Atlassian pattern (external source #112) + +#### Built-in template: Citizen Participation (Burgerberaad) + +- States: intake, moderation_review, published, discussion_open, synthesis, response_pending, responded, archived +- Quorum: none (participation-based) +- Decision method: advisory (non-binding), results synthesized by themes (user story #258) +- Special rules: anonymous contributions, representative sampling #### Scenario: Use built-in ALV template without customization @@ -110,22 +293,147 @@ The system MUST ship with built-in process templates for common governance conte - WHEN the administrator selects the built-in "Association ALV" template - THEN the template MUST include all legally required states and voting rules for Dutch associations (BW Book 2) - AND the template MUST be immediately usable without further configuration +- AND the template MUST display a summary of applicable legal requirements + +#### Scenario: Customize a built-in template + +- GIVEN the built-in "Municipal Council" template +- WHEN the administrator duplicates it for their specific municipality +- THEN they MUST be able to add custom commission states (e.g., "finance_commission", "audit_commission") +- AND they MUST be able to customize speaking time rules per their Reglement van Orde +- AND legal requirements from Gemeentewet MUST NOT be removable (enforced as read-only guards) + +--- + +### Requirement: Admin UI for Process Template Management + +The system MUST provide an administrative interface for creating, editing, and managing process templates. The UI MUST support visual editing of state machines, voting rules, and template metadata. + +**Feature tier**: V1 + +#### Scenario: Visual state machine editor + +- GIVEN an administrator creating a new process template +- WHEN they open the state machine editor +- THEN they MUST be able to add states by clicking on a canvas +- AND they MUST be able to draw transitions between states by connecting them +- AND guard conditions MUST be configurable via a form on each transition +- AND the editor MUST validate the state machine for reachability (no orphan states) + +#### Scenario: Voting rule editor with decision table + +- GIVEN an administrator configuring voting rules +- WHEN they open the voting rule editor +- THEN a decision table MUST be displayed with columns for conditions and outcomes +- AND conditions MUST include: vote type, majority threshold, quorum requirement, abstention handling +- AND the administrator MUST be able to add, remove, and reorder rows +- AND the table MUST preview results with sample vote inputs + +#### Scenario: Template testing mode + +- GIVEN a completed process template +- WHEN the administrator clicks "Test Template" +- THEN the system MUST create a sandbox decision using the template +- AND the administrator MUST be able to walk through all states and transitions +- AND the test MUST verify that all guard conditions are evaluable +- AND the test decision MUST be automatically deleted after testing + +--- + +### Requirement: Multi-step Authorization Workflows + +The system MUST support multi-step authorization workflows where different roles are required at different stages of the decision process. This is critical for destruction authorization, supervisory approvals, and committee-to-plenary escalation. + +**Feature tier**: V1 +**Evidence**: User story #271 (critical) requires multi-step destruction authorization. User story #25 (must) requires digital approval workflow for supervisory board decisions. + +#### Scenario: Supervisory board approval workflow + +- GIVEN a management decision requiring supervisory board approval +- WHEN the decision reaches the "supervisory_approval" state +- THEN only users with the "supervisory_board" role MUST be able to approve +- AND the approval MUST require a configurable number of approvers (e.g., 2 of 5) +- AND the workflow MUST support delegation with audit trail (user story #25) + +#### Scenario: Committee recommendation to plenary + +- GIVEN a council proposal in the "commission_review" state +- WHEN the commission completes its review +- THEN a recommendation (positive, negative, or amended) MUST be attached to the proposal +- AND the proposal MUST automatically transition to the plenary track +- AND the commission's findings MUST be linked to the decision record (user story #73) ## User Stories -1. **Legal counsel tracking governance code compliance**: As legal counsel, I want to track compliance with each provision of the Corporate Governance Code, so that I can prepare the comply-or-explain statement for the annual report. (Source: intelligence DB #39) +### High-Priority Stories (from Intelligence DB) + +1. **Supervisory board chair managing approval workflow** (DB #25, priority: must): As a supervisory board chair, I want a digital workflow for approving major management decisions, so that approvals can be obtained efficiently even outside scheduled meetings. *AC: Circular resolution capability, voting with deadline and reminders, supporting document attachment, audit trail of all votes and comments.* + +2. **Secretary verifying voting requirements** (DB #59, priority: must): As secretary, I want to verify that a statute amendment vote meets the required quorum and qualified majority so that the notary can confirm proper adoption. + +3. **Council member drafting motion from template** (DB #144, priority: must): As a raadslid, I want to create a motion using a standard template, so that my motion meets all procedural requirements without manual formatting. + +4. **Policy advisor creating standardized council proposal** (DB #154, priority: must): As a beleidsadviseur, I want to create a council proposal using a standardized template with all required sections, so that the griffie can process it efficiently. + +5. **Board secretary taking digital minutes with template** (DB #11, priority: must): As a board secretary, I want to take structured minutes during the AGM using a digital template, so that all resolutions, votes, and key discussions are accurately captured. *AC: Pre-populated template with agenda items, resolution outcomes auto-filled from voting, action item tagging.* + +6. **Archivist requiring multi-step destruction authorization** (DB #271, priority: critical): As an Archivist, I want destruction to require multi-step authorization (records manager proposes, archivist approves, system executes), so that no unauthorized destruction occurs. *AC: Multi-step propose-approve-execute, destruction certificate with audit trail.* + +### Medium-Priority Stories + +7. **Committee member submitting report with template** (DB #73, priority: medium): As a committee member, I want to submit our committee report with findings and recommendations using a standard template so that the board can act on our advice. + +8. **MT member initiating policy with template** (DB #102, priority: medium): As an MT member, I want to initiate a policy draft using a standardized template that guides me through required sections and identifies stakeholders, so that the policy is complete and ready for review. + +9. **Citizen initiative leader drafting proposal** (DB #212, priority: high): As a citizen initiative leader, I want to draft my proposal using a guided template so that it meets all formal municipal requirements. + +10. **Community leader drafting Right to Challenge proposal** (DB #233, priority: high): As a community leader, I want a guided template for my Right to Challenge proposal covering task description, capacity demonstration, budget, and community support. + +### Capability Stories (from external source clustering) + +11. **PHP state machine capabilities** (DB #365): Platform requires PHP state machine capabilities -- addressed by Symfony Workflow Component. -2. **Supervisory board chair managing approval workflow**: As a supervisory board chair, I want a digital workflow for approving major management decisions, so that approvals can be obtained efficiently even outside scheduled meetings. (Source: intelligence DB #25) +12. **BPMN/DMN engine capabilities** (DB #549, #550, #553, #554): Platform requires BPMN/DMN capabilities -- addressed by DMN-inspired decision tables (not full BPMN, per insight #14). -3. **Secretary verifying voting requirements**: As secretary, I want to verify that a statute amendment vote meets the required quorum and qualified majority so that the notary can confirm proper adoption. (Source: intelligence DB #59) +13. **Decision workflow capabilities** (DB #388): Platform requires configurable decision workflow -- core purpose of this spec. ## Acceptance Criteria - Process templates are stored as OpenRegister objects with YAML state machine definitions -- State machines use Symfony Workflow Component YAML format -- Voting rules support simple, qualified, unanimous, and weighted majority +- State machines use Symfony Workflow Component YAML format on the backend +- State machine visualization uses XState on the frontend with Vue integration +- Backend-frontend state synchronization generates XState JSON from Symfony YAML +- Voting rules support simple, qualified, unanimous, weighted, consent-based, and quadratic majority - Abstention handling is configurable (counted or excluded) -- Tie-breaking methods are configurable per template -- Built-in templates ship for ALV, board, council, and operational contexts +- Tie-breaking methods are configurable per template (chair's casting vote, rejection, postponement) +- Secret ballot is automatically enforced for appointment votes +- Silence/written procedure is supported with configurable deadlines +- Built-in templates ship for ALV, board, corporate, municipal council, MT, and citizen participation contexts +- Built-in templates encode non-removable legal requirements as read-only guards - Templates are duplicable for customization -- State machine visualization is available in the admin UI +- Admin UI provides visual state machine editor and decision table editor +- Template testing mode validates all guard conditions +- Multi-step authorization workflows are configurable per template +- Every state transition is recorded in an immutable audit trail with WHO/WHAT/WHEN/WHY/HOW +- All templates comply with applicable Dutch legal requirements (BW, Gemeentewet, WBTR, WDAV) + +## External Sources + +| # | Type | Title | Key Insight | +|---|------|-------|-------------| +| 301 | tool | Symfony Workflow Component | PHP-native state machine, YAML config, guards, events, marking store | +| 300 | tool | XState 5 | JS/TS statecharts, serializable JSON, @xstate/vue, visual editor | +| 318 | documentation | XState Actor Model Patterns | Delayed transitions, parallel states, Vue integration | +| 283 | standard | DMN Decision Model and Notation | Decision tables with hit policies for voting rules | +| 282 | standard | BPMN 2.0 | Process modeling standard (informed design, not implemented) | +| 286 | standard | UML State Machine Diagrams | Hierarchical states, parallel regions, guards | +| 311 | analysis | Decision Audit Trails | WHO/WHAT/WHEN/WHY/HOW metadata per transition | +| 308 | analysis | Silence/Written Procedure | Tacit approval pattern with deadline-based adoption | +| 256 | documentation | Consent Decision Making (Sociocracy) | Proposal-reaction-objection-integration rounds | +| 254 | scientific | Quadratic Voting (SSRN) | Intensity-of-preference voting, prevents tyranny of majority | +| 273 | documentation | Gemeentewet Art. 32 | Rollcall voting, oral votes, tie-breaking rules | +| 292 | legal | Gemeentewet Quorum Art. 20/29/30 | Municipal quorum and voting rules | +| 293 | legal | BW 2:230/238 | Configurable majority, written procedure rules | +| 112 | blog | DACI Framework (Atlassian) | Driver-Approver-Contributor-Informed decision model | +| 317 | analysis | EU Council Decision Procedures | QMV, simple majority, unanimity patterns | +| 284 | standard | CMMN 1.1 | Case management notation for less structured processes | diff --git a/openspec/specs/resolution-minutes/spec.md b/openspec/specs/resolution-minutes/spec.md index caafe02..fe10edc 100644 --- a/openspec/specs/resolution-minutes/spec.md +++ b/openspec/specs/resolution-minutes/spec.md @@ -6,25 +6,40 @@ status: idea ## Purpose -Resolutions and minutes are the formal output of the decision-making process. A resolution is the legal text of an adopted decision, suitable for archival and external communication. Minutes (notulen) are the structured record of a meeting including attendance, discussions, decisions, votes, and action items. The system supports real-time minute-taking during meetings, automated generation from meeting data, review/approval workflows, and integration with Docudesk for professional document rendering. +Resolutions and minutes are the formal output of the decision-making process. A resolution is the legal text of an adopted decision, suitable for archival and external communication. Minutes (notulen) are the structured record of a meeting including attendance, discussions, decisions, votes, and action items. The system supports real-time minute-taking during meetings, automated generation from meeting data, review/approval workflows, action item extraction and tracking, integration with Docudesk for professional document rendering, Archiefwet/MDTO compliance for archival, and Akoma Ntoso for resolution document structure. **Standards**: Akoma Ntoso (`act`, `minutes`), Schema.org (`CreativeWork`, `DigitalDocument`), OpenRaadsinformatie (`Besluit`, `Verslag`), MDTO (metadata for archival) **Feature tier**: V1 -**Legal reference**: BW 2:10 (minutes of board meetings), Gemeentewet 23 (council minutes), Awb 3:46-3:47 (formal decision documentation) +**Legal reference**: BW 2:10 (minutes of board meetings), Gemeentewet 23 (council minutes), Awb 1:3 (formal decision definition), Awb 3:46-3:47 (formal decision documentation and motivation), Archiefwet 2021 (10-year transfer, expanded scope), Woo Art. 3.3 (active publication obligation) ## Data Model See [ARCHITECTURE.md](../../docs/ARCHITECTURE.md) for the full Resolution and Minutes entity definitions including property tables and standards mappings. +## Evidence Base + +This specification is informed by **53 user stories**, **20 requirements** from Dutch government tenders, and **26 external sources** from the intelligence database. Key evidence clusters: + +- **Requirement cluster #22**: "Archival destruction" -- 685 requirements across 189 tenders (Source: intelligence DB cluster #22) +- **Requirement cluster #37**: "Digital archiving" -- 379 requirements across 143 tenders (Source: intelligence DB cluster #37) +- **Requirement cluster #54**: "e-Depot (digital archive)" -- 247 requirements across 117 tenders (Source: intelligence DB cluster #54) +- **Awb Art. 1:3**: Defines "besluit" as a written decision containing a public law legal act; requires formal motivation (Source: intelligence DB ext #291) +- **Archiefwet 2021**: 10-year transfer to permanent archive (was 20), expanded scope to ALL government information including email and chat (Source: intelligence DB insight #19) +- **Akoma Ntoso 1.0 (OASIS)**: Standard for XML representation of legislative/parliamentary documents including debates, amendments, voting records (Source: intelligence DB ext #289) +- **Competitor analysis**: Diligent (AI Smart Minutes), OnBoard (AI minutes builder), Fellow.app (AI meeting notes), iBabs (AI minutes), Meeting Decisions (one-click minutes), Sherpany (signed minutes), BoardPro (decision register) (Source: intelligence DB competitors) +- **Market evidence**: AI meeting minutes market is rapidly expanding; 44% of action items never completed (Source: intelligence DB ext #342); Diligent processes minutes for 700K+ directors (Source: intelligence DB ext #180) + ## Requirements --- ### Requirement: Resolution Generation -The system MUST support generating formal resolution texts from adopted decisions. Resolutions MUST include the decision text, voting results, legal basis, date of adoption, and governing body. Resolutions MUST be stored as OpenRegister objects and optionally rendered as documents via Docudesk. +The system MUST support generating formal resolution texts from adopted decisions. Resolutions MUST include the decision text, voting results, legal basis, date of adoption, and governing body. Resolutions MUST be stored as OpenRegister objects and optionally rendered as documents via Docudesk. Resolutions MUST follow the Awb definition of "besluit" (written decision containing a public law legal act with formal motivation). **Feature tier**: V1 +**Legal reference**: Awb 1:3 (besluit definition), Awb 3:46-3:47 (motivation requirement) +**Evidence**: Automated decision list generation from voting results is a top-priority council requirement (Source: intelligence DB story #175). Diligent and BoardPro both feature automated resolution tracking (Source: intelligence DB competitors #642, ext #114) #### Scenario: Generate a resolution from an adopted decision @@ -40,6 +55,7 @@ The system MUST support generating formal resolution texts from adopted decision - WHEN the resolution is generated - THEN the resolution MUST include the legal basis ("Gelet op artikel 160 van de Gemeentewet") - AND the resolution text MUST follow Akoma Ntoso structure (preface, body, conclusions) +- AND the resolution MUST include the formal motivation (overwegingen) per Awb 3:46 (Source: intelligence DB ext #289) #### Scenario: Provide proof of proper adoption for notarial deed @@ -47,6 +63,14 @@ The system MUST support generating formal resolution texts from adopted decision - WHEN the notary requests proof of proper adoption - THEN the system MUST generate a complete package including: convocation proof, quorum verification, voting results, and the resolution text - AND the package MUST be verifiable and tamper-evident +- AND the package MUST be exportable as a single PDF/A document (Source: intelligence DB story #78) + +#### Scenario: Auto-generate decision list from voting results + +- GIVEN a council meeting has concluded with 12 agenda items voted on +- WHEN the clerk requests the decision list (besluitenlijst) +- THEN the system MUST automatically generate a list of all decisions with: agenda item number, subject, vote result, and outcome (adopted/rejected) +- AND the list MUST be publishable on the council website per Woo Art. 3.3 (Source: intelligence DB story #175, req #131443) --- @@ -55,6 +79,7 @@ The system MUST support generating formal resolution texts from adopted decision The system MUST support structured minute-taking during meetings using a digital template. Minutes MUST be pre-populated with meeting metadata (date, body, attendees, agenda). The secretary MUST be able to record notes, decisions, and action items per agenda item in real-time. **Feature tier**: V1 +**Evidence**: AI-powered minutes generation saves up to 60% of minuting work (Source: intelligence DB ext #179). Sherpany reports 45% productivity boost from end-to-end meeting lifecycle management (Source: intelligence DB ext #108). Dutch "notulen software" market offers 33% meeting time reduction with AI transcription (Source: intelligence DB ext #137) #### Scenario: Take structured minutes during a meeting @@ -63,6 +88,7 @@ The system MUST support structured minute-taking during meetings using a digital - THEN the template MUST be pre-populated with meeting date, body name, attendees, and agenda items - AND for each agenda item, the secretary MUST be able to enter discussion notes, decisions, and action items - AND voting results MUST be automatically inserted from the voting system +- AND the minutes MUST be structured by agenda item for easy navigation (Source: intelligence DB story #174) #### Scenario: Record action items during minute-taking @@ -70,6 +96,39 @@ The system MUST support structured minute-taking during meetings using a digital - WHEN they add an action item "Prepare budget proposal" with owner "CFO" and deadline "2026-05-01" - THEN the action item MUST be linked to the agenda item and meeting - AND the action item MUST appear in the action tracking system (see decision-management spec) +- AND the action item MUST automatically become a CalDAV VTODO task assigned to the responsible person (Source: intelligence DB stories #1834-1837) + +#### Scenario: Auto-create structured folder for meeting dossier + +- GIVEN a meeting has concluded with decisions, minutes, and related documents +- WHEN the meeting is finalized +- THEN the system MUST automatically create a folder structure in Nextcloud Files containing: agenda, minutes, all proposals, amendments, voting results, and attachments +- AND the folder MUST be linked to the meeting via _files metadata in OpenRegister (Source: intelligence DB stories #1841-1844) + +--- + +### Requirement: AI-Assisted Minutes Generation + +The system SHOULD support AI-assisted meeting transcription and minutes generation. The AI MUST produce structured output (decisions, action items, discussion summaries) that the secretary can review and edit. + +**Feature tier**: V2 +**Evidence**: Diligent AI auto-generates minutes from agendas, notes, and transcripts (Source: intelligence DB ext #180). Otter.ai achieves 93-95% transcription accuracy with real-time summaries (Source: intelligence DB ext #328). Board Intelligence Minute Writer produces governance-ready minutes from notes/transcripts (Source: intelligence DB ext #178) + +#### Scenario: Generate AI-powered meeting transcription and summary + +- GIVEN a meeting that was recorded or transcribed +- WHEN the secretary triggers AI-assisted minutes generation +- THEN the system MUST produce a draft with: (1) per-agenda-item discussion summary, (2) extracted decisions, (3) extracted action items with suggested owners +- AND the secretary MUST be able to review, edit, and approve the AI-generated draft +- AND the system MUST clearly mark AI-generated content for review (Source: intelligence DB story #345) + +#### Scenario: AI extraction of action items from transcription + +- GIVEN a meeting transcript containing phrases like "Jan will prepare the budget report by next Friday" +- WHEN the AI processes the transcript +- THEN the system MUST extract: action ("prepare budget report"), owner ("Jan"), deadline ("next Friday" resolved to date) +- AND present the extracted items for secretary confirmation before creating formal action items +- AND track action item completion rate over time (44% of action items are never completed per research) (Source: intelligence DB ext #342) --- @@ -78,13 +137,15 @@ The system MUST support structured minute-taking during meetings using a digital The system MUST support a review and approval workflow for minutes. Draft minutes MUST be distributed to participants for review. Participants MUST be able to suggest corrections. The chair or designated approver MUST formally approve the minutes. **Feature tier**: V1 +**Evidence**: Digital minutes approval eliminates "email ping-pong" (Source: intelligence DB story #20). 71% of Dutch municipal clerks want digital meeting tools to remain permanent (Source: intelligence DB ext #140) #### Scenario: Distribute draft minutes for review - GIVEN minutes have been drafted for a completed meeting - WHEN the secretary marks the minutes as "ready for review" - THEN all meeting participants MUST receive a notification with a link to the draft minutes -- AND participants MUST be able to submit correction suggestions +- AND participants MUST be able to submit correction suggestions with tracked changes +- AND the review period MUST have a configurable deadline #### Scenario: Approve board minutes digitally @@ -93,14 +154,24 @@ The system MUST support a review and approval workflow for minutes. Draft minute - THEN the minutes status MUST change to "approved" - AND the approved minutes MUST be locked against further editing - AND the approval MUST be recorded with timestamp and approver identity +- AND the approved minutes MUST be available for the next meeting's consent agenda + +#### Scenario: Approve council minutes at next meeting + +- GIVEN draft council minutes from the previous meeting +- WHEN the minutes are placed on the consent agenda of the next meeting +- WHEN council members have submitted no corrections or all corrections are processed +- THEN the chair puts the minutes to a formal adoption vote +- AND if adopted, the minutes MUST be marked as "vastgesteld" (adopted) with the adoption date (Source: intelligence DB story #177) --- -### Requirement: Minutes Document Generation +### Requirement: Minutes Document Generation via Docudesk The system MUST support generating professional minutes documents via Docudesk. The minutes MUST include all meeting metadata, attendance, per-item discussions, decisions with voting results, and action items. **Feature tier**: V1 +**Evidence**: Document generation is a core integration point; competitors Diligent and Sherpany offer professionally formatted governance documents (Source: intelligence DB competitors #632, ext #108) #### Scenario: Generate minutes document from meeting data @@ -108,29 +179,265 @@ The system MUST support generating professional minutes documents via Docudesk. - WHEN the secretary triggers "Generate Document" - THEN the system MUST send the minutes data to Docudesk for rendering - AND the generated document MUST be stored in Nextcloud Files linked to the meeting -- AND the document MUST be available in PDF and ODT formats +- AND the document MUST be available in PDF/A and ODT formats +- AND the document MUST include the organizational logo and styling per NL Design System tokens -## User Stories +#### Scenario: Generate resolution document with Akoma Ntoso structure + +- GIVEN an adopted resolution with legal basis, motivation, and decision text +- WHEN the secretary triggers resolution document generation +- THEN the system MUST produce a document following Akoma Ntoso structure: (1) preface (header, parties), (2) preamble (considerations, legal basis), (3) body (articles/decision points), (4) conclusions (date, signature block) +- AND the document MUST include MDTO metadata for archival compliance (Source: intelligence DB ext #289) + +--- + +### Requirement: Action Item Tracking and Follow-Up + +The system MUST support capturing, assigning, and tracking action items from meetings. Each action item MUST have an owner, deadline, status, and link to the originating meeting and agenda item. The system MUST support automatic follow-up workflows. + +**Feature tier**: V1 +**Evidence**: 44% of action items never completed; 71% of meetings fail objectives due to poor follow-through (Source: intelligence DB ext #342). Named owner, realistic deadline, and clear verb-based description are essential (Source: intelligence DB ext #142). Fellow.app and Decisions both offer centralized action item tracking (Source: intelligence DB competitors #672, ext #106) + +#### Scenario: Capture action items during meeting + +- GIVEN the secretary is recording minutes for a meeting +- WHEN they capture an action item: "Prepare quarterly report" assigned to the CFO with deadline 2026-06-01 +- THEN the action item MUST be stored as a CalDAV VTODO task via _todos metadata +- AND the task MUST be assigned to the responsible person +- AND the task MUST have a reminder set before the deadline +- AND the action item MUST appear in both the minutes and the action item dashboard (Source: intelligence DB story #337) + +#### Scenario: Track action item completion across meetings + +- GIVEN multiple meetings have produced 25 action items over the past quarter +- WHEN the secretary views the action item dashboard +- THEN the system MUST show: total items, completed, overdue, completion rate +- AND items MUST be filterable by owner, meeting, deadline, and status +- AND overdue items MUST be automatically highlighted and optionally escalated (Source: intelligence DB story #91) + +#### Scenario: Report action item completion rate + +- GIVEN historical action item data for a governing body +- WHEN the manager views the meeting effectiveness scorecard +- THEN the system MUST calculate: completion rate (completed/total x 100), average time-to-completion, overdue rate +- AND these KPIs MUST be displayed per person and per meeting body (Source: intelligence DB story #331, ext #323) + +--- + +### Requirement: Archival Compliance (Archiefwet/MDTO) + +The system MUST support automatic archival of decisions and minutes with MDTO-compliant metadata. The system MUST support generation of Submission Information Packages (SIPs) for eDepot transfer. Records MUST have configurable retention periods based on the selectielijst. + +**Feature tier**: V1 +**Legal reference**: Archiefwet 2021 (10-year transfer, expanded scope), MDTO metadata standard +**Evidence**: 685 requirements across 189 tenders reference archival destruction processes; 379 reference digital archiving; 247 reference eDepot (Source: intelligence DB clusters #22, #37, #54). Notubiz Schiedam case study shows archiving from within the political portal preserves political context (Source: intelligence DB ext #100) + +#### Scenario: Auto-archive council decisions with MDTO metadata + +- GIVEN a council decision has been adopted and the resolution generated +- WHEN the archival process is triggered +- THEN the system MUST automatically populate MDTO metadata fields: creator, date, classification, decision type, retention period (from selectielijst), and governing body +- AND the record MUST be linked to its parent dossier (zaakdossier) +- AND the system MUST validate metadata completeness before archiving (Source: intelligence DB stories #182, #259, #262) + +#### Scenario: Generate SIP package for eDepot transfer -1. **Secretary taking digital minutes during AGM**: As a board secretary, I want to take structured minutes during the AGM using a digital template, so that all resolutions, votes, and key discussions are accurately captured. (Source: intelligence DB #11) +- GIVEN a set of council records whose retention period triggers transfer to permanent archive +- WHEN the archivist initiates eDepot transfer +- THEN the system MUST generate a SIP (Submission Information Package) conforming to eDepot specifications +- AND the SIP MUST include: the documents (in PDF/A or ODF format), MDTO metadata XML, file checksums for integrity verification +- AND pre-transfer validation MUST check metadata completeness, format compliance, and integrity (Source: intelligence DB stories #273, #274) -2. **CEO approving board minutes digitally**: As a CEO, I want to review and approve board minutes digitally with tracked changes, so that minutes are finalized quickly without email ping-pong. (Source: intelligence DB #20) +#### Scenario: Verify archive completeness for council meeting -3. **Secretary drafting and distributing ALV minutes**: As secretary, I want to draft the ALV minutes including all decisions, voting results, and attendance and distribute them to members so that there is a formal record of the meeting. (Source: intelligence DB #75) +- GIVEN a council meeting has concluded 4 weeks ago +- WHEN the archivist runs a completeness check +- THEN the system MUST verify that all required records exist: agenda, minutes, all proposals, amendments, voting results, recordings, and attachments +- AND any missing items MUST be flagged with the responsible party for remediation (Source: intelligence DB story #183) -4. **Notary receiving proof of proper adoption**: As notary, I want to receive complete proof that the statute amendment was properly decided (quorum, qualified majority, proper convocation) so that I can execute the notarial deed. (Source: intelligence DB #78) +--- + +### Requirement: Record Retention and Destruction + +The system MUST support configurable retention periods per record type based on the VNG selectielijst. The system MUST generate destruction lists when retention periods expire and enforce multi-step authorization for destruction. + +**Feature tier**: V1 +**Legal reference**: Archiefwet 2021, VNG selectielijst +**Evidence**: Archival destruction is the largest requirement cluster in Dutch government tenders (685 requirements, 189 tenders) (Source: intelligence DB cluster #22) + +#### Scenario: Import selectielijst and map to classification scheme + +- GIVEN the archivist wants to configure retention periods +- WHEN they import the VNG selectielijst +- THEN the system MUST map selectielijst categories to the organizational classification scheme (ordeningsplan) +- AND retention periods MUST be automatically applied to new records based on their classification (Source: intelligence DB story #268) + +#### Scenario: Multi-step destruction authorization + +- GIVEN records whose retention period has expired +- WHEN the system generates a destruction list +- THEN the records manager MUST first propose destruction +- AND the archivist MUST review and approve the destruction list +- AND only after both approvals MUST the system execute destruction +- AND a tamper-evident log of the destruction MUST be retained (Source: intelligence DB story #271) + +#### Scenario: Legal hold preventing destruction + +- GIVEN records involved in ongoing litigation +- WHEN the legal department places a legal hold +- THEN the system MUST prevent destruction of those records even if the retention period has expired +- AND the legal hold MUST be visible in the record's metadata and audit trail (Source: intelligence DB story #306) + +--- + +### Requirement: Active Publication (Woo Compliance) + +The system MUST support active publication of meeting documents, decisions, and minutes per Woo Art. 3.3. Published documents MUST be accessible to the public and maintained in a publication register. + +**Feature tier**: V1 +**Legal reference**: Wet open overheid (Woo) Art. 3.3 +**Evidence**: Woo requires government organizations to actively publish 17 categories of information including meeting documents of councils and provincial states (Source: intelligence DB ext #296). Nearly half of Dutch council information systems are inadequate for public access (Source: intelligence DB ext #73) + +#### Scenario: Publish council meeting documents automatically + +- GIVEN a council meeting has been finalized with approved minutes and decision list +- WHEN the clerk triggers publication +- THEN the system MUST publish: the agenda, all proposals, voting results, decision list, and approved minutes +- AND each document MUST be added to the publication register with publication date +- AND published documents MUST be accessible via a public-facing search interface +- AND the system MUST track which documents have been published and which are pending (Source: intelligence DB story #280) + +--- + +### Requirement: Cross-System Search and Linking + +The system MUST provide unified search across decisions, motions, minutes, and related documents. The system MUST support cross-domain record linking for related cases. + +**Feature tier**: V1 +**Evidence**: Council members and citizens need natural language search across all council information (Source: intelligence DB story #186). Nextcloud unified search integration provides zero-effort discoverability (Source: intelligence DB stories #1869-1873) + +#### Scenario: Search across all council information + +- GIVEN a citizen wanting to find information about housing policy decisions +- WHEN they search for "woningbouw" in the public interface +- THEN the system MUST return matching: decisions, motions, minutes, proposals, and related documents +- AND results MUST be faceted by: document type, date range, governing body, and status +- AND each result MUST show a preview with highlighted matching text (Source: intelligence DB story #186) + +#### Scenario: Search from Nextcloud unified search bar + +- GIVEN a staff member working in Nextcloud +- WHEN they use the unified search bar to search for a decision reference +- THEN the system MUST return matching decisions, motions, and meeting minutes +- AND clicking a result MUST navigate to the Decidesk detail view (Source: intelligence DB stories #1869-1873) + +--- + +### Requirement: Meeting Recording Integration + +The system SHOULD support linking audio/video recordings to agenda items and indexing them for search. The system SHOULD support automatic captioning for accessibility. + +**Feature tier**: V2 +**Evidence**: Notubiz and GO Raadsinformatie both offer webcasting with speaker indexing (Source: intelligence DB competitors #596, #586). WCAG accessibility requires captions on meeting recordings (Source: intelligence DB story #185) + +#### Scenario: Index video recording by agenda item + +- GIVEN a council meeting that was video-recorded +- WHEN the recording is processed +- THEN the system MUST create index points at each agenda item transition +- AND viewers MUST be able to jump directly to a specific agenda item in the recording +- AND the system SHOULD integrate with the AV/webcast system for automatic speaker identification (Source: intelligence DB stories #184, #200) + +#### Scenario: Add captions to meeting recordings + +- GIVEN a council meeting recording +- WHEN the recording is post-processed +- THEN the system MUST generate accurate captions (via speech-to-text) +- AND captions MUST be reviewable and editable by the secretary +- AND the captioned recording MUST be accessible to hearing-impaired citizens (Source: intelligence DB story #185) + +## User Stories -5. **Management assistant generating minutes from notes**: As a management assistant, I want to generate structured minutes from the notes and decisions captured during the meeting, so that minutes are available for review within hours instead of days. (Source: intelligence DB #93) +### Priority: Must Have + +1. **Secretary taking structured minutes during AGM**: As a board secretary, I want to take structured minutes during the AGM using a digital template so that all resolutions, votes, and key discussions are accurately captured. (Source: intelligence DB #11) +2. **Raadsadviseur auto-generating decision list**: As a raadsadviseur, I want the decision list to be automatically generated from the recorded voting results so that publication is faster and more accurate. (Source: intelligence DB #175) +3. **Griffier linking minutes to agenda items**: As a commissiegriffier, I want minutes to be automatically structured by agenda item so that they are easy to navigate and search. (Source: intelligence DB #174) +4. **Griffier submitting draft minutes for approval**: As a griffier, I want to submit draft minutes for approval at the next meeting with tracked corrections so that the approval process is transparent. (Source: intelligence DB #177) +5. **Archivaris auto-archiving council decisions**: As an archivaris, I want council decisions to be automatically archived with complete metadata according to the retention schedule so that compliance is ensured without manual intervention. (Source: intelligence DB #182) +6. **Archivaris verifying archive completeness**: As an archivaris, I want to verify that all council meeting records (agenda, minutes, decisions, recordings, documents) are complete in the archive so that no gaps exist in the democratic record. (Source: intelligence DB #183) +7. **Secretary capturing action items with owner and deadline**: As a secretary, I want to capture action items during the meeting with an assigned owner and deadline and automatically create follow-up tasks. (Source: intelligence DB #337) +8. **Secretary auto-creating tasks from action items**: As a secretary, I want action items recorded in meeting minutes to automatically become CalDAV VTODO tasks assigned to the responsible person so that nothing falls through the cracks. (Source: intelligence DB #1834) +9. **Records manager creating automatic dossier folders**: As a records manager, I want each decision to have an automatically structured folder in Nextcloud Files containing all related documents. (Source: intelligence DB #1841) +10. **Any user searching across decisions and minutes**: As any user, I want to search for decisions, motions, meeting minutes, and related documents from the Nextcloud unified search bar. (Source: intelligence DB #1869) +11. **Records manager creating archival records automatically**: As a Records Manager, I want the system to automatically create an archival record when a formal decision is registered so that no decision goes unarchived. (Source: intelligence DB #259) +12. **Records manager auto-populating MDTO metadata**: As a Records Manager, I want the system to auto-populate as many MDTO metadata fields as possible from context so that manual entry is minimized. (Source: intelligence DB #262) + +### Priority: Should Have + +13. **CEO approving board minutes digitally**: As a CEO, I want to review and approve board minutes digitally with tracked changes so that minutes are finalized quickly without email ping-pong. (Source: intelligence DB #20) +14. **Notary accessing meeting information**: As a notary, I want secure access to the meeting agenda, attendee list, and voting results so that I can prepare accurate notarial minutes for contentious meetings. (Source: intelligence DB #12) +15. **Notary receiving finalized resolution texts**: As a notary, I want to receive finalized resolution texts and supporting documents digitally so that I can prepare and execute the notarial deed efficiently. (Source: intelligence DB #34) +16. **Management assistant generating minutes from notes**: As a management assistant, I want to generate structured minutes from the notes and decisions captured during the meeting so that minutes are available for review within hours instead of days. (Source: intelligence DB #93) +17. **Secretary generating AI-powered transcription and summaries**: As a secretary, I want automatic meeting transcription with AI-generated summaries (key decisions, action items, discussion points) so that minutes creation is automated and nothing is missed. (Source: intelligence DB #345) +18. **Raadsadviseur indexing video by agenda item**: As a raadsadviseur, I want video recordings to be automatically indexed by agenda item so that viewers can jump directly to specific topics. (Source: intelligence DB #184) +19. **Accessibility officer adding captions to recordings**: As a toegankelijkheidsmedewerker, I want meeting recordings to have accurate captions so that hearing-impaired citizens can follow council proceedings. (Source: intelligence DB #185) +20. **Records manager tracking archival backlog KPIs**: As an Archivist, I want KPIs tracking the archival backlog (unclassified records, overdue transfers, pending destructions) so that I can report to management. (Source: intelligence DB #301) +21. **Council secretary tracking BOB phases in minutes**: As a council secretary, I want to tag each meeting with its BOB phase and track how topics progress through phases so that the decision-making process is transparent. (Source: intelligence DB #341) +22. **Records manager archiving Talk conversations**: As a records manager, I want Talk conversations linked to decisions to be exportable and archivable as part of the decision record so that we comply with Archiefwet requirements. (Source: intelligence DB #1854) + +### Priority: Could Have + +23. **Secretary drafting and distributing ALV minutes**: As secretary, I want to draft the ALV minutes including all decisions, voting results, and attendance and distribute them to members so that there is a formal record of the meeting. (Source: intelligence DB #75) +24. **Notary receiving proof of proper adoption**: As notary, I want to receive complete proof that the statute amendment was properly decided (quorum, qualified majority, proper convocation) so that I can execute the notarial deed. (Source: intelligence DB #78) +25. **New board member accessing decision history**: As a new board member, I want to access all historical decisions, current action items, financial status, and governance documents so that I can quickly become effective in my role. (Source: intelligence DB #84) +26. **Member accessing association documents**: As a member, I want to access meeting minutes, financial reports, and decision history through a self-service portal so that I can stay informed about association governance. (Source: intelligence DB #80) +27. **Hearing secretary producing structured report**: As a hearing secretary, I want to produce a structured hearing report from minutes so that the decision-maker has a clear overview of all arguments. (Source: intelligence DB #239) +28. **Journalist accessing meeting recordings immediately**: As a journalist, I want to access meeting recordings as soon as possible after the meeting ends so that I can report accurately with direct quotes. (Source: intelligence DB #194) +29. **Journalist searching voting history**: As a journalist, I want to search voting records by topic, member name, or faction so that I can research political positions for my reporting. (Source: intelligence DB #187) +30. **Archivist generating SIP packages for eDepot**: As an Archivist, I want to generate Submission Information Packages (SIPs) conforming to eDepot specifications so that records can be transferred digitally. (Source: intelligence DB #273) + +## Competitor Analysis + +| Competitor | Minutes/Resolution Features | Strengths | Gaps | +|---|---|---|---| +| **Diligent Boards** | AI Smart Minutes from agendas/notes/transcripts; action item tracking; voting & resolutions | Enterprise leader (700K+ directors); AI-powered governance-grade output | Expensive; no legislative features; no archival compliance; closed platform | +| **OnBoard** | AI meeting minutes; shared annotation; minutes builder; analytics | Strong board governance UX; SOC 2/ISO 27001 certified | No council/municipal features; no MDTO/eDepot; no public-facing publication | +| **iBabs** | AI minutes; decision tracking with action items; document management | Strong Dutch municipal presence; ISO certified; affordable | Limited AI capabilities; no Akoma Ntoso; no resolution document generation | +| **Meeting Decisions** | AI notetaker; one-click minutes; secure voting with audit trail | Good for Microsoft Teams integration; fast minute generation | No governance-grade formatting; no archival compliance; no legislative features | +| **Fellow.app** | AI transcription; action item tracking; collaborative notes | Best action item workflow; centralized tracking across meetings | No formal decision/resolution handling; no voting; no archival compliance | +| **Notubiz** | Minutes creation/publication; audio/video recording and archiving; speech-to-text | Dominant Dutch council market; video+agenda item indexing | Poor search UX; limited document generation; closed platform | +| **Sherpany** | End-to-end meeting lifecycle; digitally signed minutes; 45% productivity boost | Swiss quality; strong security; covers prep through follow-up | No Dutch market presence; no legislative features; expensive | +| **BoardPro** | Automated decision register from meetings, votes, and flying minutes | Searchable by keyword/date; automatic categorization and audit trail | Limited to board governance; no council features; no archival | +| **GO Raadsinformatie** | Document management; webcasting; search and archive | Council document publishing; video integration | Aging platform; limited automation; no AI capabilities | + +(Sources: intelligence DB competitors #632, #659, #607, #678, #683, #668, #594, #585, ext #108, #180, #114) ## Acceptance Criteria -- Resolutions are generated from adopted decisions with sequential numbering -- Resolutions include decision text, voting results, legal basis, and adoption date -- Real-time minute-taking is pre-populated from meeting metadata +- Resolutions are generated from adopted decisions with sequential numbering per body +- Resolutions include decision text, voting results, legal basis, formal motivation (overwegingen), and adoption date +- Decision lists (besluitenlijsten) are auto-generated from voting results +- Resolution documents follow Akoma Ntoso structure (preface, preamble, body, conclusions) +- Real-time minute-taking is pre-populated from meeting metadata and structured by agenda item - Voting results are automatically inserted into minutes from the voting system -- Minutes follow a review/approval workflow with tracked changes -- Approved minutes are locked against further editing -- Document generation is delegated to Docudesk (PDF/ODT) +- Action items are captured with owner, deadline, and automatically created as CalDAV VTODO tasks +- Action item completion rate is tracked and reportable as a KPI +- AI-assisted minutes generation produces reviewable drafts with extracted decisions and action items +- Minutes follow a review/approval workflow with tracked changes and configurable deadline +- Approved minutes are locked against further editing with timestamp and approver identity +- Document generation is delegated to Docudesk (PDF/A and ODT formats) +- Automatic dossier folder structure per decision in Nextcloud Files via _files metadata +- MDTO metadata is auto-populated and validated for archival compliance +- SIP packages are generated for eDepot transfer with pre-transfer validation +- Selectielijst-based retention periods are configurable with automated destruction lists +- Multi-step destruction authorization (propose, review, approve, execute) is enforced +- Legal holds prevent destruction during litigation +- Active publication of meeting documents per Woo Art. 3.3 with publication register +- Unified search across decisions, motions, and minutes via Nextcloud Search +- Faceted search on MDTO metadata fields (date, creator, classification, type, status) +- Video recordings are indexed by agenda item with caption support - Notarial proof packages include convocation, quorum, votes, and resolution -- MDTO metadata is attached for archival compliance +- Archive completeness checks verify all required meeting records exist - OpenRaadsinformatie `Besluit`/`Verslag` mapping is available +- Every lifecycle event is logged in Nextcloud Activity stream diff --git a/openspec/specs/user-settings/spec.md b/openspec/specs/user-settings/spec.md index 7ae7433..dde208e 100644 --- a/openspec/specs/user-settings/spec.md +++ b/openspec/specs/user-settings/spec.md @@ -6,18 +6,20 @@ status: idea ## Purpose -User settings allow individual Decidesk users to configure their personal preferences for notifications, display, and participation. These settings control how and when users receive alerts about meetings, votes, and decisions, as well as display preferences for the dashboard and meeting interface. +User settings allow individual Decidesk users to configure their personal preferences for notifications, display, participation, delegation, and communication. These settings control how and when users receive alerts about meetings, votes, and decisions, display preferences for the dashboard and meeting interface, and delegation/absence management for governance roles. Settings are rendered using `NcAppSettingsDialog` within the Decidesk app context. -**Standards**: Nextcloud Settings API (`OCP\Settings\ISettings`), Nextcloud Notification API +**Standards**: Nextcloud Settings API (`OCP\Settings\ISettings`), Nextcloud Notification API (`OCP\Notification\IManager`), NcAppSettingsDialog component **Feature tier**: MVP +**Evidence sources**: Intelligence DB user stories #4, #5, #18, #27, #63, #80, #82, #97, #142, #179, #197, #208, #255, #313, #318, #328, #330, #331, #335; Requirement clusters #34 (Notifications, 451 reqs/153 tenders), #18 (Authorization/RBAC, 876 reqs/205 tenders); Category features: notifications, role-based-views, calendar-integration + ## Requirements --- -### Requirement: Notification Preferences +### REQ-US-01: Notification Preferences -The system MUST allow users to configure their notification preferences for Decidesk events. Users MUST be able to enable or disable notifications per event type and choose delivery channels (Nextcloud notification, email, or both). +The system MUST allow users to configure their notification preferences for Decidesk events. Users MUST be able to enable or disable notifications per event type and choose delivery channels (Nextcloud notification, email, or both). Event types MUST include: pending vote, meeting reminder, decision status change, action item assignment, action item due, convocation received, minute approval request, quorum at risk, and proxy request. **Feature tier**: MVP @@ -42,11 +44,18 @@ The system MUST allow users to configure their notification preferences for Deci - THEN the user MUST receive reminders at both configured times - AND the default MUST be "24 hours before" and "1 hour before" +#### Scenario: Configure quorum-at-risk alerts + +- GIVEN a chair who needs to monitor quorum during meetings +- WHEN they enable "Quorum at risk" notifications +- THEN the user MUST receive an immediate notification when a member leaves and quorum drops below threshold +- AND the notification MUST show current attendance count vs. required quorum + --- -### Requirement: Display Preferences +### REQ-US-02: Display Preferences -The system MUST allow users to configure display preferences for the Decidesk interface including: default view (dashboard, meetings, decisions), items per page in list views, date/time format, and preferred language. +The system MUST allow users to configure display preferences for the Decidesk interface including: default view (dashboard, meetings, decisions, action items), items per page in list views, date/time format, preferred language (nl/en), and compact/comfortable list density. **Feature tier**: MVP @@ -63,11 +72,25 @@ The system MUST allow users to configure display preferences for the Decidesk in - THEN all dates in the Decidesk interface MUST use this format - AND the default MUST follow the Nextcloud locale setting +#### Scenario: Set preferred language + +- GIVEN a user in a bilingual organization (nl/en) +- WHEN they set their preferred language to English +- THEN all Decidesk interface labels, menu items, and system messages MUST render in English +- AND generated documents (minutes, resolutions) MUST use the meeting's language setting, not the user's preference + +#### Scenario: Configure list density + +- GIVEN a user who prefers seeing more items at once +- WHEN they set list density to "compact" +- THEN list views (meetings, decisions, action items) MUST show more rows with reduced spacing +- AND the default MUST be "comfortable" + --- -### Requirement: Delegation and Absence +### REQ-US-03: Delegation and Absence Management -The system MUST allow users to configure a delegate who receives their notifications and can act on their behalf during a configured absence period. This supports vacation coverage for governance roles. +The system MUST allow users to configure a delegate who receives their notifications and can act on their behalf during a configured absence period. Delegation MUST NOT automatically include voting rights; formal proxy (volmacht) is a separate process. **Feature tier**: MVP @@ -86,9 +109,26 @@ The system MUST allow users to configure a delegate who receives their notificat - THEN the system MUST block the vote with a message: "Delegation does not include voting rights. A formal proxy (volmacht) is required for voting." - AND the system MUST provide a link to the proxy granting process +#### Scenario: Grant formal proxy for voting + +- GIVEN a member who cannot attend the ALV +- WHEN they grant a formal proxy (volmacht) to another member +- THEN the proxy holder MUST be able to cast votes on behalf of the grantor +- AND the proxy MUST specify whether it is general (all items) or item-specific +- AND the system MUST enforce the maximum number of proxies per person as configured on the body +- AND both parties MUST receive confirmation of the proxy arrangement + +#### Scenario: Cancel or modify delegation + +- GIVEN an active delegation to member B +- WHEN member A returns early and cancels the delegation +- THEN member B MUST immediately lose delegate access +- AND member A MUST resume receiving their own notifications +- AND any pending action items viewed by the delegate MUST be logged in the audit trail + --- -### Requirement: Communication Preferences +### REQ-US-04: Communication Preferences The system MUST allow users to set their preferred communication channel for governance matters: email address, phone number for urgent matters, and preferred language for communications. @@ -101,20 +141,217 @@ The system MUST allow users to set their preferred communication channel for gov - THEN all Decidesk-related emails (convocations, minutes, reminders) MUST be sent to the work address - AND the default MUST be the Nextcloud account email +#### Scenario: Configure urgent contact method + +- GIVEN a chair who needs to be reachable for quorum emergencies +- WHEN they add a phone number for urgent governance matters +- THEN the system MUST store the phone number securely +- AND the phone number MUST only be visible to secretaries and chairs within the same body +- AND the system MAY use this for future SMS notification integration + +--- + +### REQ-US-05: Speaking Time and Meeting Participation + +The system MUST allow users to configure their participation preferences for meetings, including speaking time alerts, preparation reminders, and preferred participation mode (physical, digital, hybrid). + +**Feature tier**: V1 + +#### Scenario: Configure speaking time alerts + +- GIVEN a council member who wants to manage their speaking time +- WHEN they set speaking time alert at "30 seconds remaining" +- THEN the user MUST receive a visual alert when their remaining speaking time reaches 30 seconds +- AND the alert MUST be visible on both desktop and mobile interfaces +- AND the default alert timing MUST be "1 minute remaining" + +#### Scenario: Set preferred participation mode + +- GIVEN a board member who usually attends remotely +- WHEN they set preferred participation mode to "digital" +- THEN new meeting invitations MUST default to digital attendance for this user +- AND the meeting organizer MUST see the preference when viewing the participant list +- AND the user MAY override this per individual meeting + +#### Scenario: Configure preparation reminder timing + +- GIVEN a member who needs extra preparation time +- WHEN they set preparation reminders to "72 hours before meeting" +- THEN the user MUST receive a reminder to review meeting documents 72 hours before each meeting +- AND the reminder MUST include links to unread meeting documents +- AND the default MUST be "48 hours before meeting" + +--- + +### REQ-US-06: Dashboard Customization + +The system MUST allow users to customize their personal dashboard view with configurable widgets showing relevant governance information. + +**Feature tier**: V1 + +#### Scenario: Configure dashboard widgets + +- GIVEN a secretary opening their dashboard settings +- WHEN they enable widgets for "Upcoming meetings", "Pending action items", "Open votes", and "Recent decisions" +- THEN the dashboard MUST display these widgets in the user's configured order +- AND each widget MUST show a configurable number of items (default: 5) +- AND widgets MUST be collapsible and reorderable via drag-and-drop + +#### Scenario: Configure action item dashboard + +- GIVEN a board member with multiple body memberships +- WHEN they filter the action items widget to show only "Bestuur" items +- THEN the widget MUST show only action items from the "Bestuur" body +- AND overdue items MUST be highlighted with a warning indicator +- AND the filter MUST persist across sessions + +--- + +### REQ-US-07: Mobile and Offline Preferences + +The system MUST allow users to configure mobile-specific settings for accessing governance materials on tablets and smartphones. + +**Feature tier**: V1 + +#### Scenario: Configure offline document sync + +- GIVEN a supervisory board member who prepares on their tablet during travel +- WHEN they enable "Offline sync" for meeting documents +- THEN upcoming meeting documents (within 7 days) MUST be cached for offline access +- AND annotations made offline MUST sync when connectivity is restored +- AND the sync MUST respect data limits (configurable max download size) + +#### Scenario: Configure mobile notification behavior + +- GIVEN a user on a mobile device +- WHEN they configure "Do not disturb" hours for Decidesk notifications +- THEN notifications MUST be silenced during configured hours (e.g., 22:00-07:00) +- AND critical notifications (quorum at risk, voting deadline imminent) MUST still be delivered + +--- + +### REQ-US-08: Keyword Alerts and Topic Following + +The system MUST allow users to set up keyword-based alerts for governance topics they want to follow across all bodies they are a member of. + +**Feature tier**: V2 + +#### Scenario: Set alerts for topics of interest + +- GIVEN a member interested in financial matters +- WHEN they add keywords "budget", "begroting", "financial", "kosten" to their alert configuration +- THEN the user MUST receive a notification when new agenda items, decisions, or motions match any of these keywords +- AND the notification MUST include the matching item title, body, and meeting date +- AND keyword matches MUST search across titles, descriptions, and attached document names + +#### Scenario: Follow specific decision topics + +- GIVEN a citizen or member who wants to track a specific topic +- WHEN they subscribe to notifications for the topic "Sustainability policy" +- THEN they MUST receive notifications when new decisions, motions, or agenda items reference this topic +- AND they MUST be able to unsubscribe at any time + +--- + +### REQ-US-09: Meeting Scorecard Preferences + +The system MUST allow users to configure their personal meeting efficiency scorecard showing KPIs for their meeting behavior. + +**Feature tier**: V2 + +#### Scenario: Configure personal meeting scorecard + +- GIVEN a manager who wants to optimize meeting time +- WHEN they enable the personal meeting scorecard +- THEN the scorecard MUST show: meetings per week (with trend), average meeting duration, decision rate (decisions per meeting), action item completion rate, and focus time ratio +- AND all metrics MUST be calculated from the user's actual meeting data +- AND the scorecard MUST be visible only to the user (private by default) + +--- + +### REQ-US-10: Accessibility Preferences + +The system MUST respect Nextcloud's accessibility settings and allow users to configure Decidesk-specific accessibility options. + +**Feature tier**: V1 + +#### Scenario: Configure high-contrast mode + +- GIVEN a user with visual accessibility needs +- WHEN Nextcloud's high-contrast theme is enabled +- THEN all Decidesk interfaces MUST render with sufficient contrast ratios (WCAG AA minimum) +- AND voting buttons MUST use both color and icon indicators (not color alone) +- AND the speaking time indicator MUST use both visual and optional audio alerts + +#### Scenario: Configure keyboard navigation preferences + +- GIVEN a user who navigates primarily via keyboard +- WHEN they are on the voting interface +- THEN all vote options (for, against, abstain) MUST be reachable via Tab key +- AND the current focus MUST be clearly indicated +- AND keyboard shortcuts MUST be documented and customizable + ## User Stories -1. **Member accessing documents and decision history**: As a member, I want to access meeting minutes, financial reports, and decision history through a self-service portal so that I can stay informed about association governance. (Source: intelligence DB #80) +1. **Member accessing documents and decision history**: As a member, I want to access meeting minutes, financial reports, and decision history through a self-service portal so that I can stay informed about association governance. (Source: intelligence DB #80, priority: medium) + +2. **Supervisory board member accessing secure workspace**: As a supervisory board member, I want a secure digital workspace where I can access management reports, governance documents, and communicate with fellow board members between meetings. (Source: intelligence DB #27, priority: must) + +3. **Board member accessing board pack on mobile**: As a supervisory board member, I want to access the board pack on my tablet or smartphone with offline capability, so that I can prepare for meetings while traveling. (Source: intelligence DB #18, priority: must) + +4. **Shareholder submitting proxy vote digitally**: As a shareholder, I want to submit my proxy vote digitally for each resolution item, so that my vote is counted even though I cannot attend the AGM in person. (Source: intelligence DB #4, priority: must) + +5. **Member granting proxy vote digitally**: As a member who cannot attend the ALV, I want to grant a proxy to another member digitally so that my vote is represented without paper forms. (Source: intelligence DB #63, priority: high) + +6. **Member delegating vote via proxy**: As a member, I want to delegate my vote to another member via proxy so that my voice is counted even when I cannot attend. (Source: intelligence DB #313, priority: must) + +7. **Shareholder submitting proxy before AGM**: As a shareholder, I want to submit my proxy vote before the AGM so that my shares are voted even if I cannot attend. (Source: intelligence DB #318, priority: must) + +8. **Council member accessing documents offline**: As a raadslid, I want to download meeting documents for offline reading on my tablet, so that I can prepare even without internet access. (Source: intelligence DB #142, priority: should) + +9. **Council member viewing motions dashboard**: As a raadslid, I want to see a dashboard showing all adopted motions with their current status, so that I can hold the executive accountable. (Source: intelligence DB #179, priority: should) + +10. **Citizen setting alerts for topics of interest**: As a burger, I want to set up keyword-based alerts for council agenda items and decisions, so that I am notified when topics that affect me are being discussed. (Source: intelligence DB #208, priority: could) + +11. **Department head approving within delegation**: As a department head, I want to see budget requests alongside my remaining budget and delegation limits, so that I can make informed approval decisions. (Source: intelligence DB #97, priority: high) + +12. **Ledenraad member preparing with constituency input**: As a ledenraad member, I want to review the agenda, consult my constituency, and prepare my voting position so that I effectively represent my members. (Source: intelligence DB #82, priority: medium) + +13. **Manager tracking personal meeting KPIs**: As a manager, I want a personal meeting scorecard showing my KPIs so that I can optimize my own meeting behavior. (Source: intelligence DB #331, priority: must) + +14. **Accessibility officer checking document compliance**: As a toegankelijkheidsmedewerker, I want to automatically check documents for accessibility issues before publication. (Source: intelligence DB #197, priority: must) + +15. **Council member monitoring executive commitments**: As a raadslid, I want a dashboard showing all open commitments from the executive with deadlines and status. (Source: intelligence DB #203, priority: should) + +16. **Alderman reviewing participation results**: As an alderman, I want a dashboard showing all active and completed participation processes with key results. (Source: intelligence DB #255, priority: high) + +17. **CFO viewing enterprise risk dashboard**: As a CFO, I want a real-time risk dashboard showing all enterprise risks, control effectiveness, and compliance status. (Source: intelligence DB #21, priority: should) + +18. **Institutional investor managing proxy voting at scale**: As an institutional investor, I want to manage proxy voting across all portfolio company AGMs from a single dashboard. (Source: intelligence DB #5, priority: should) -2. **Supervisory board member accessing secure workspace**: As a supervisory board member, I want a secure digital workspace where I can access management reports, governance documents, and communicate with fellow board members between meetings. (Source: intelligence DB #27) +19. **Meeting organizer displaying live cost ticker**: As a meeting organizer, I want to display a live cost ticker showing the running cost of the current meeting. (Source: intelligence DB #335, priority: could) -3. **Board member accessing board pack on mobile**: As a supervisory board member, I want to access the board pack on my tablet or smartphone with offline capability, so that I can prepare for meetings while traveling. (Source: intelligence DB #18) +20. **Participation coordinator conducting ranked preference poll**: As a participation coordinator, I want citizens to rank their preferred options so that we find solutions with broadest support. (Source: intelligence DB #328, priority: should) ## Acceptance Criteria -- Notification preferences are configurable per event type (vote, meeting, decision, action item) -- Delivery channels (Nextcloud notification, email) are independently toggleable -- Meeting reminder timing is configurable (default: 24h + 1h before) -- Display preferences support default view, items per page, and date format -- Absence delegation notifies the delegate but does not grant voting rights -- Communication preferences allow separate governance email -- Settings use Nextcloud personal settings section via OCP\Settings\ISettings +1. Notification preferences are configurable per event type (vote, meeting, decision, action item, convocation, quorum, proxy) +2. Delivery channels (Nextcloud notification, email) are independently toggleable per event type +3. Meeting reminder timing is configurable with multiple time points (default: 24h + 1h before) +4. Display preferences support default view, items per page, date format, language, and list density +5. NcAppSettingsDialog is used for the settings interface within the Decidesk app +6. Absence delegation allows notification forwarding and read access but not voting +7. Formal proxy (volmacht) is a separate process from delegation with body-configured limits +8. Proxy granting supports general and item-specific proxies with confirmation +9. Communication preferences allow separate governance email and urgent contact number +10. Speaking time alerts are configurable with visual and optional audio indicators +11. Preparation reminders include links to unread meeting documents +12. Dashboard widgets are configurable, reorderable, and filterable per body +13. Mobile/offline preferences support document caching and do-not-disturb hours +14. Keyword alerts match across titles, descriptions, and document names +15. Personal meeting scorecard shows private KPIs (meetings/week, duration, decision rate) +16. Accessibility preferences respect Nextcloud themes and support keyboard navigation +17. All user preferences are stored per-user via Nextcloud's `IConfig` personal values +18. Settings changes take effect immediately without page reload +19. Default values are sensible and documented for all preferences +20. Delegation and proxy audit trail is maintained for compliance diff --git a/openspec/specs/voting-system/spec.md b/openspec/specs/voting-system/spec.md index e5c3d86..32db499 100644 --- a/openspec/specs/voting-system/spec.md +++ b/openspec/specs/voting-system/spec.md @@ -6,16 +6,27 @@ status: idea ## Purpose -The voting system is Decidesk's most critical feature. It supports multiple voting methods (open vote, secret ballot, roll call, weighted voting), real-time ballot casting and result calculation, quorum-aware majority thresholds, proxy vote handling, and configurable voting rules per governing body. The system ensures legally compliant voting for associations (ALV), corporate boards (BV/NV), and government councils. +The voting system is Decidesk's most critical feature. It supports multiple voting methods (open vote, secret ballot, roll call, weighted voting, ranked choice, dot voting, quadratic voting, consent-based, approval voting, score polling), real-time ballot casting and result calculation, quorum-aware majority thresholds, proxy vote handling, and configurable voting rules per governing body. The system ensures legally compliant voting for associations (ALV), corporate boards (BV/NV), government councils, citizen participation, and operational teams. -**Standards**: Schema.org (`VoteAction`, `ChooseAction`), Akoma Ntoso (`voting`, `count`), OpenRaadsinformatie (`Stemming`, `Stem`) +**Standards**: Schema.org (`VoteAction`, `ChooseAction`), Akoma Ntoso (`voting`, `count`), OpenRaadsinformatie (`Stemming`, `Stem`), CoE CM/Rec(2017)5 (e-voting standards) **Feature tier**: MVP -**Legal reference**: BW 2:38 (ALV voting), BW 2:230 (BV shareholder voting), Gemeentewet 27-32 (council voting), WBTR (documentation requirements) +**Legal reference**: BW 2:38 (ALV voting), BW 2:230 (BV shareholder voting), BW 2:42 (statute amendment 2/3), BW 2:18 (dissolution 2/3), Gemeentewet 20 (quorum), 29 (second meeting without quorum), 30 (absolute majority), 31 (secret ballot), 32 (roll call), WBTR (documentation requirements), WDAV (digital meetings) ## Data Model See [ARCHITECTURE.md](../../docs/ARCHITECTURE.md) for the full Vote and VotingRound entity definitions including property tables, Schema.org mappings, and OpenRaadsinformatie alignment. +## Evidence Base + +This specification is informed by **345 user stories**, **178 requirements** from Dutch government tenders, and **50 external sources** from the intelligence database. Key evidence clusters: + +- **Requirement cluster #43**: "Besluitvorming (decision process)" -- 271 requirements across 133 tenders (Source: intelligence DB cluster #43) +- **Council of Europe CM/Rec(2017)5**: 49 standards in three-tiered structure for e-voting (principles, recommendations, standards) (Source: intelligence DB ext #258) +- **Gemeentewet Art. 20/29/30/31/32**: Dutch municipal voting law codified as non-negotiable system requirements (Source: intelligence DB ext #273, #292) +- **BW 2:230/238**: Configurable majority and written procedure for BVs (Source: intelligence DB ext #293) +- **Competitor analysis**: Loomio (7 voting types), OpenSlides (4 modes), Decidim (encrypted e-voting), POLYAS (BSI-certified), Belenios (cryptographic verification), ElectionBuddy (multi-ballot) (Source: intelligence DB competitors) +- **Market sizing**: European participation market 300M EUR, e-voting 500M EUR expected within 5 years (Source: intelligence DB insight #23, ext #87) + ## Requirements --- @@ -25,6 +36,7 @@ See [ARCHITECTURE.md](../../docs/ARCHITECTURE.md) for the full Vote and VotingRo The system MUST support open (public) voting where each participant casts a for, against, or abstain vote. Results MUST be displayed in real-time. The vote of each participant MUST be recorded and visible in the minutes. **Feature tier**: MVP +**Evidence**: 47 user stories reference open voting; Gemeentewet Art. 30 mandates this as the default method for council decisions (Source: intelligence DB ext #292) #### Scenario: Conduct an open vote on an agenda item @@ -41,6 +53,7 @@ The system MUST support open (public) voting where each participant casts a for, - WHEN a user views the voting results - THEN the system MUST display how each member voted (for/against/abstain) - AND the results MUST be recorded in the decision audit trail +- AND the results MUST be mappable to OpenRaadsinformatie `Stemming`/`Stem` format #### Scenario: Reject a vote when quorum is lost mid-meeting @@ -48,6 +61,7 @@ The system MUST support open (public) voting where each participant casts a for, - WHEN the chair attempts to start a new vote - THEN the system MUST recalculate quorum from current attendance - AND if quorum is no longer met, voting MUST be blocked with a quorum warning +- AND the system MUST offer the option to adjourn per Gemeentewet Art. 29 (second meeting without quorum) --- @@ -57,10 +71,11 @@ The system MUST support secret (anonymous) voting where individual votes are not **Feature tier**: MVP **Legal reference**: BW 2:38 (election by secret ballot), Gemeentewet 31 (secret ballot requirements) +**Evidence**: Competitors Belenios (ElGamal homomorphic encryption, ZK proofs), POLYAS (BSI Common Criteria certified) set the security bar (Source: intelligence DB ext #269, #270) #### Scenario: Conduct a secret ballot for board election -- GIVEN a meeting with an agenda item "Board Election — Treasurer" +- GIVEN a meeting with an agenda item "Board Election -- Treasurer" - WHEN the chair initiates a secret ballot - THEN each eligible member MUST see a voting panel with candidate options - AND individual votes MUST NOT be linked to voters in the stored results @@ -73,15 +88,51 @@ The system MUST support secret (anonymous) voting where individual votes are not - WHEN the results are tallied - THEN the total number of votes MUST equal exactly 12 - AND if a discrepancy is detected, the system MUST flag it for the chair +- AND the system SHOULD provide E2E verifiability: cast-as-intended, recorded-as-cast (Source: intelligence DB ext #261) + +#### Scenario: Secret ballot for council appointments per Gemeentewet Art. 31 + +- GIVEN a council meeting with a personnel appointment on the agenda +- WHEN the chair initiates voting on the appointment +- THEN the system MUST enforce secret ballot mode (non-overridable for appointments) +- AND blank votes MUST be counted separately from abstentions +- AND the system MUST support multiple rounds if no candidate achieves majority + +--- + +### Requirement: Roll Call Vote (Hoofdelijke Stemming) + +The system MUST support roll call voting where each member is called individually to declare their vote. The starting position MUST be randomized to prevent order bias. Roll call voting is mandatory when requested by the chair or any council member per Gemeentewet Art. 32. + +**Feature tier**: MVP +**Legal reference**: Gemeentewet Art. 32 +**Evidence**: Parlaeus, Notubiz, and iBabs all support roll call with automated speaker identification (Source: intelligence DB competitors #601, #623, #605) + +#### Scenario: Conduct a roll call vote with randomized order + +- GIVEN a council meeting where a member requests a roll call vote +- WHEN the chair initiates a roll call vote (hoofdelijke stemming) +- THEN the system MUST generate a randomized member order +- AND each member MUST be called individually to declare "for", "against", or "abstain" +- AND the system MUST record each vote with timestamp in declaration order +- AND results MUST show the full voting sequence + +#### Scenario: Handle tie in roll call vote per Gemeentewet Art. 32 + +- GIVEN a roll call vote on a non-personnel matter resulting in a tie +- WHEN all members have voted and the result is equal for/against +- THEN if the meeting is not full (not all seated members present), the vote MUST be postponed to the next meeting +- AND if the meeting IS full (all seated members present), the proposal MUST be declared rejected --- ### Requirement: Qualified Majority and Voting Rules -The system MUST support configurable majority rules: simple majority (50%+1), qualified majority (e.g., 2/3), unanimous, and weighted voting. Abstentions MUST be configurable as counting toward total or excluded from calculation. +The system MUST support configurable majority rules: simple majority (50%+1), absolute majority (>50% of all members), qualified majority (e.g., 2/3, 3/4), unanimous, and weighted voting. Abstentions MUST be configurable as counting toward total or excluded from calculation. The system MUST support DMN-inspired decision tables for configurable voting rules per organization. **Feature tier**: MVP -**Legal reference**: BW 2:42 (statute amendment requires 2/3), BW 2:18 (dissolution requires 2/3) +**Legal reference**: BW 2:42 (statute amendment requires 2/3), BW 2:18 (dissolution requires 2/3), BW 2:230 (default absolute majority) +**Evidence**: DMN decision tables recommended for modeling voting rules per organization (Source: intelligence DB insight #13, ext #283) #### Scenario: Verify qualified majority for statute amendment @@ -102,16 +153,24 @@ The system MUST support configurable majority rules: simple majority (50%+1), qu - GIVEN a simple majority vote where 10 for and 10 against - WHEN the votes are tallied - THEN the system MUST declare the result as "tied" -- AND the system MUST apply the configured tie-breaking rule (e.g., chair's casting vote, motion fails, or revote) +- AND the system MUST apply the configured tie-breaking rule (e.g., chair's casting vote, motion fails, revote, or lot for persons per BW 2:230) + +#### Scenario: Configure custom majority rules via decision table + +- GIVEN a governing body with custom statutes requiring 3/4 majority for asset disposal +- WHEN the administrator configures the voting rules +- THEN the system MUST allow creating a decision table mapping: decision type -> required majority, required quorum, abstention handling, tie-breaking rule +- AND the configured rules MUST be applied automatically when a matching vote is initiated --- -### Requirement: Proxy Voting +### Requirement: Proxy Voting (Volmacht) -The system MUST support digital proxy voting (volmacht) where a member authorizes another member to vote on their behalf. Proxy votes MUST be verifiable and count toward both quorum and voting. +The system MUST support digital proxy voting (volmacht) where a member authorizes another member to vote on their behalf. Proxy votes MUST be verifiable and count toward both quorum and voting. The system MUST enforce configurable limits on proxies per member. **Feature tier**: MVP **Legal reference**: BW 2:227 (shareholder proxy), BW 2:38 (ALV proxy per statutes) +**Evidence**: Broadridge processes global proxy voting with push notifications, facial recognition, and synchronized multi-channel voting (Source: intelligence DB ext #265). Lumi Global combines live + proxy + pre-meeting votes (Source: intelligence DB ext #264) #### Scenario: Grant and exercise a digital proxy @@ -120,6 +179,7 @@ The system MUST support digital proxy voting (volmacht) where a member authorize - THEN the system MUST prompt member B to cast their own vote AND the proxy vote separately - AND both votes MUST be recorded (member B's own vote and member A's proxy vote) - AND the results MUST show the total including proxy votes +- AND the proxy grant MUST be stored with timestamp and digital confirmation #### Scenario: Limit proxy votes per member @@ -127,6 +187,14 @@ The system MUST support digital proxy voting (volmacht) where a member authorize - WHEN member B already holds 2 proxies and member C attempts to grant a proxy to member B - THEN the system MUST reject the proxy with a message indicating the maximum has been reached +#### Scenario: Submit proxy vote before AGM + +- GIVEN a shareholder AGM with resolution items published in the convocation +- WHEN a shareholder submits proxy votes before the meeting date +- THEN each resolution item MUST allow a for/against/abstain proxy vote +- AND proxy votes MUST be combinable with live votes (overridable if shareholder attends) +- AND the system MUST support split voting for institutional investors with multiple fund mandates (Source: intelligence DB story #319) + --- ### Requirement: Remote Voting in Digital/Hybrid Meetings @@ -134,6 +202,8 @@ The system MUST support digital proxy voting (volmacht) where a member authorize The system MUST support real-time voting for remote participants in digital and hybrid meetings. Remote votes MUST have equal weight to in-person votes. The system MUST ensure vote integrity through session verification. **Feature tier**: MVP +**Legal reference**: WDAV (Wet Digitale Algemene Vergadering, passed Tweede Kamer Dec 2025) (Source: intelligence DB ext #21) +**Evidence**: 71% of Dutch municipal clerks want digital meetings to continue post-COVID (Source: intelligence DB ext #140) #### Scenario: Cast vote remotely during hybrid meeting @@ -142,27 +212,411 @@ The system MUST support real-time voting for remote participants in digital and - THEN the remote member MUST see the same voting panel as in-person attendees - AND their vote MUST be counted with equal weight - AND their attendance mode (remote) MUST be recorded alongside their vote +- AND identity verification MUST confirm the remote voter is the authenticated member -## User Stories +#### Scenario: Vote by email reply for non-platform users -1. **Chair conducting open vote**: As chair, I want to conduct an open vote (for/against/abstain) on an agenda item and see results in real-time so that I can announce the outcome immediately. (Source: intelligence DB #57) +- GIVEN a member who does not use the Decidesk platform regularly +- WHEN a voting notification is sent via email +- THEN the member SHOULD be able to reply with "For", "Against", or "Abstain" +- AND the system MUST verify the reply came from the registered email address +- AND the vote MUST be recorded with "email" as the channel (Source: intelligence DB stories #1814-1816) + +--- + +### Requirement: Weighted Voting + +The system MUST support weighted voting where votes carry different weights based on share ownership, contribution level, or other configurable criteria. The system MUST calculate results using weighted tallies. + +**Feature tier**: MVP +**Legal reference**: BW 2:228 (share-proportional voting for NV/BV) +**Evidence**: Lumi Global and ConveneAGM both support real-time weighted voting for shareholder meetings (Source: intelligence DB ext #264, #161). Decidim supports cost-based and budget-weighted voting (Source: intelligence DB ext #267) + +#### Scenario: Conduct weighted shareholder vote at AGM + +- GIVEN an AGM with shareholders holding different numbers of shares (A: 1000, B: 500, C: 250) +- WHEN a resolution is put to vote and all three vote "for" +- THEN the system MUST calculate: 1750 weighted votes for (100%) +- AND individual vote weights MUST be displayed alongside the result + +#### Scenario: Handle split votes for institutional investors + +- GIVEN an institutional investor holding shares across multiple fund mandates +- WHEN they wish to vote different directions per mandate +- THEN the system MUST allow splitting the total weight across for/against/abstain +- AND the split MUST be validated to equal the total holding (Source: intelligence DB story #319) + +--- + +### Requirement: Ranked Choice Voting (Preferential) + +The system MUST support ranked choice voting where voters rank options in order of preference. The system MUST implement Instant Runoff Voting (IRV) for single-winner elections and support configurable elimination algorithms. + +**Feature tier**: V1 +**Evidence**: Stanford Encyclopedia analysis of voting methods shows IRV and Condorcet agree >95% of the time (Source: intelligence DB ext #251, #252). Loomio supports drag-and-drop ranked choice (Source: intelligence DB ext #266). ElectionBuddy supports preferential/STV and Borda count (Source: intelligence DB ext #263) + +#### Scenario: Conduct ranked choice vote for venue selection + +- GIVEN an MT meeting deciding between 4 venue options +- WHEN each member ranks the options 1st through 4th +- THEN the system MUST apply IRV: eliminate lowest first-choice, redistribute preferences +- AND continue rounds until one option exceeds 50% +- AND display round-by-round elimination results + +#### Scenario: Use ranked choice for board election with multiple seats (STV) + +- GIVEN a board election with 3 open positions and 7 candidates +- WHEN members rank all candidates +- THEN the system MUST apply Single Transferable Vote (STV) with configurable quota (Droop or Hare) +- AND surplus votes from elected candidates MUST be redistributed fractionally +- AND elected candidates MUST be announced in order of election + +--- + +### Requirement: Dot Voting (Budget/Point Allocation) + +The system MUST support dot voting where participants distribute a fixed number of points across multiple options. This supports prioritization, backlog management, and participatory budgeting. + +**Feature tier**: V1 +**Evidence**: Loomio supports dot voting with budget allocation (Source: intelligence DB ext #266). Decidim uses budget-limited voting for participatory budgeting (Source: intelligence DB ext #267). Research shows participants prefer expressive voting formats for budget decisions (Source: intelligence DB ext #277) + +#### Scenario: Prioritize backlog items with dot voting + +- GIVEN 10 backlog items and each team member has 5 dots to distribute +- WHEN team members allocate their dots (max 3 per item) +- THEN the system MUST tally total dots per item +- AND rank items by total allocation +- AND display a visual heat map of point distribution (Source: intelligence DB story #321) + +#### Scenario: Participatory budget allocation with cost constraints + +- GIVEN a participatory budget of 100,000 EUR with 8 project proposals of varying costs +- WHEN citizens allocate their budget tokens to projects +- THEN the system MUST enforce that selected projects do not exceed the total budget +- AND apply the "method of equal shares" for proportional allocation (Source: intelligence DB ext #277) +- AND display which projects are funded and unfunded (Source: intelligence DB story #326) + +--- + +### Requirement: Quadratic Voting + +The system MUST support quadratic voting where participants buy votes at quadratic cost (1 vote = 1 credit, 2 votes = 4 credits, 3 votes = 9 credits). This allows expressing intensity of preference while preventing tyranny of the majority. + +**Feature tier**: V2 +**Evidence**: Seminal research proposes quadratic voting for corporate governance, preventing majority tyranny while capturing preference intensity (Source: intelligence DB ext #254). Used in participatory democracy for multi-issue prioritization (Source: intelligence DB story #329) + +#### Scenario: Run quadratic voting for multi-issue prioritization + +- GIVEN 5 policy proposals and each citizen has 25 credits +- WHEN a citizen allocates 9 credits (3 votes) to proposal A, 4 credits (2 votes) to proposal B, and 1 credit each to C, D, E +- THEN the system MUST validate total credits used (9+4+1+1+1 = 16 <= 25) +- AND aggregate all votes per proposal with quadratic weighting +- AND rank proposals by total votes received + +--- + +### Requirement: Consent-Based Decision-Making (Sociocracy) + +The system MUST support consent-based decision-making following sociocratic principles. In consent, a decision is adopted when no participant has a "paramount objection" -- it does not require agreement, only the absence of reasoned objections. + +**Feature tier**: V1 +**Evidence**: Sociocracy For All defines the process: proposal -> question round -> reaction round -> objection round -> integration (Source: intelligence DB ext #256). Consent is faster than consensus for organizations, avoids gridlock (Source: intelligence DB ext #257) + +#### Scenario: Conduct consent-based decision round + +- GIVEN a proposal presented to a team using consent-based process +- WHEN the facilitator initiates a consent round +- THEN the system MUST guide through phases: (1) Proposal presentation, (2) Clarifying questions, (3) Quick reactions, (4) Objection round, (5) Integration +- AND each phase MUST have a configurable timer +- AND if no objections are raised, the proposal MUST be marked "adopted by consent" +- AND if objections are raised, the system MUST capture the objection text and trigger integration discussion (Source: intelligence DB stories #324, #346) + +#### Scenario: Record consent decision without formal vote counting + +- GIVEN a supervisory board using consent-based decision-making +- WHEN the chair concludes a consent round with no objections +- THEN the system MUST record the decision as "adopted by consent" (not by vote count) +- AND the record MUST include who participated and that no objections were raised (Source: intelligence DB story #320) + +--- + +### Requirement: Approval Voting and Score Polling + +The system MUST support approval voting (vote for as many options as you approve of) and score polling (rate each option on a numeric scale). These methods capture nuanced preferences for multi-option decisions. -2. **Chair conducting secret ballot**: As chair, I want to conduct a secret ballot for board elections so that members can vote freely without social pressure. (Source: intelligence DB #60) +**Feature tier**: V1 +**Evidence**: ElectionBuddy supports approval, scoring, and rating scale ballots (Source: intelligence DB ext #263). Loomio score polls use 0-9 per option (Source: intelligence DB ext #266) -3. **Secretary verifying qualified majority**: As secretary, I want to verify that a statute amendment vote meets the required quorum and qualified majority so that the notary can confirm proper adoption. (Source: intelligence DB #59) +#### Scenario: Evaluate vendor proposals with score polling -4. **Member casting remote vote**: As a member attending remotely, I want to cast my vote securely during the ALV so that my participation is equal to physical attendees. (Source: intelligence DB #58) +- GIVEN 4 vendor proposals to evaluate across 5 criteria +- WHEN each MT member scores each proposal 0-10 per criterion +- THEN the system MUST calculate weighted average scores per proposal +- AND rank proposals by aggregate score +- AND display score distribution per criterion (Source: intelligence DB story #323) -5. **Member granting digital proxy**: As a member who cannot attend the ALV, I want to grant a proxy (volmacht) to another member digitally so that my vote is represented without paper forms. (Source: intelligence DB #63) +#### Scenario: Approval voting for committee membership + +- GIVEN 8 candidates for 4 committee seats +- WHEN each voter approves as many candidates as they wish +- THEN the top 4 candidates by approval count MUST be elected +- AND the system MUST handle ties via configurable tiebreaker + +--- + +### Requirement: Asynchronous (Written) Decision-Making + +The system MUST support decision-making outside meetings via written procedure (schriftelijke besluitvorming). For BVs, written procedure requires unanimous consent to the METHOD (not the decision itself) per BW 2:238. + +**Feature tier**: MVP +**Legal reference**: BW 2:40 (board decision outside meeting), BW 2:238 (BV written procedure) +**Evidence**: BoardPro captures decisions from "flying minutes" (Source: intelligence DB ext #114). Loomio enables asynchronous proposals with deadline-based voting (Source: intelligence DB ext #118) + +#### Scenario: Circulate written resolution for board decision outside meeting + +- GIVEN a chair wants to make an urgent decision between meetings +- WHEN they circulate a proposal to all board members with a response deadline +- THEN each member MUST receive a notification with the proposal text +- AND each member MUST cast a for/against/abstain vote before the deadline +- AND the proposal MUST be adopted only if the configured majority is met +- AND for BVs, the system MUST first collect consent to the written procedure before collecting votes on the substance (Source: intelligence DB story #68) + +#### Scenario: Extend voting deadline for asynchronous decision + +- GIVEN an asynchronous vote with 2 of 5 board members not yet responded and deadline approaching +- WHEN the chair extends the deadline by 48 hours +- THEN the system MUST notify outstanding voters of the extension +- AND the original votes MUST remain valid + +--- + +### Requirement: Consent Agenda (Hamerstukken) + +The system MUST support processing consent agenda items (hamerstukken) as a batch without individual debate or voting. Any member MUST be able to pull an item from the consent agenda for individual discussion. + +**Feature tier**: MVP +**Legal reference**: Standard Dutch council procedure +**Evidence**: Hamerstuk/bespreekstuk classification is a core Dutch council pattern (Source: intelligence DB stories #158, #164) + +#### Scenario: Process consent agenda items in batch + +- GIVEN a council meeting with 8 hamerstukken on the consent agenda +- WHEN the chair asks "Are there any items to be removed from the consent agenda?" +- AND no member objects +- THEN all 8 items MUST be marked as "adopted without debate" in a single action +- AND each item MUST receive an individual decision record + +#### Scenario: Pull item from consent agenda for debate + +- GIVEN a consent agenda with 8 items +- WHEN a council member requests item 5 be discussed separately +- THEN item 5 MUST be moved to the regular agenda for debate and individual vote +- AND the remaining 7 items MUST proceed as hamerstukken + +--- + +### Requirement: Decision Point Activation from Agenda [MVP] + +The system MUST automatically activate the voting interface when the chair advances to an agenda item that has a `decisionPoint` (linked Motion, Amendment, or Vote). The chair MUST NOT need to manually open the voting panel for decision-point items. Amendments linked to a decision point MUST be voted on before the main motion, following standard parliamentary procedure. + +**Cross-reference**: See agenda-management spec -- AgendaItem `decisionPoint` field links to Motion/Amendment/Vote. The live meeting page (meeting-management spec) displays the voting panel when a decision-point item is active. + +#### Scenario: Voting interface activates when chair reaches decision-point agenda item + +- GIVEN a meeting in progress and agenda item 7 "Vaststellen begroting 2027" has a linked decisionPoint (a Motion to approve the budget) +- WHEN the chair advances the meeting to agenda item 7 +- THEN the voting interface MUST activate automatically for all eligible participants +- AND the motion text and any supporting documents MUST be displayed alongside the voting panel +- AND the chair MUST be able to open debate before starting the formal vote + +#### Scenario: Amendments are voted before the main motion + +- GIVEN agenda item 7 has a main motion and 2 linked amendments (Amendment A and Amendment B) +- WHEN the chair reaches item 7 and starts the voting sequence +- THEN the system MUST present amendments for voting first, in submission order (Amendment A, then Amendment B) +- AND after all amendments are resolved (adopted or rejected), the main motion (as possibly amended) MUST be put to vote +- AND the final motion text MUST reflect any adopted amendments before the main vote + +#### Scenario: Vote result updates agenda item status in real-time + +- GIVEN a vote has been conducted on agenda item 7's decision point +- WHEN the vote result is calculated (adopted or rejected) +- THEN the agenda item's status MUST update to "decided" in real-time on all participants' live meeting pages +- AND the decision outcome (adopted/rejected with vote counts) MUST be recorded on the agenda item +- AND the chair MUST see a summary before advancing to the next agenda item + +#### Scenario: Non-decision agenda item does not trigger voting + +- GIVEN a meeting in progress and agenda item 3 "Mededelingen" has type "informational" with no decisionPoint +- WHEN the chair advances to agenda item 3 +- THEN the voting interface MUST NOT activate +- AND the chair MUST retain the ability to manually initiate an ad-hoc vote if needed + +--- + +### Requirement: Quorum Tracking and Enforcement + +The system MUST continuously track attendance and calculate quorum in real-time. Quorum rules MUST be configurable per governing body. The system MUST block voting when quorum is not met and provide alerts when quorum is at risk. + +**Feature tier**: MVP +**Legal reference**: Gemeentewet Art. 20 (council quorum >50%), Art. 56 (B&W quorum >=50%), BW 2:38 (ALV quorum per statutes) +**Evidence**: iBabs and Notubiz both provide quorum tracking with RSVP management (Source: intelligence DB ext #97). 271 requirements across 133 tenders reference decision process support (Source: intelligence DB cluster #43) + +#### Scenario: Real-time quorum monitoring during meeting + +- GIVEN a council meeting requiring >50% of 35 seated members (>17 required) +- WHEN 19 members are present and 1 member leaves +- THEN the system MUST update the quorum indicator to "18/18 required -- AT RISK" +- AND send an alert to the chair +- AND if another member leaves, voting MUST be blocked + +#### Scenario: Track attendance patterns for quorum analytics + +- GIVEN historical attendance data across multiple meetings +- WHEN the secretary views attendance analytics +- THEN the system MUST show per-member attendance rate, average quorum percentage, and meetings where quorum was at risk +- AND identify patterns (e.g., "Member X has attended 4 of last 10 meetings") (Source: intelligence DB story #342) + +--- + +### Requirement: Voting Audit Trail and Transparency + +The system MUST maintain a tamper-evident audit trail of all voting actions. All vote results MUST be publishable for public transparency. The system MUST support the three E2E verifiability properties where applicable. + +**Feature tier**: MVP +**Evidence**: CoE CM/Rec(2017)5 defines 49 standards including auditability and verifiability (Source: intelligence DB ext #258). OSCE guidelines warn about voter coercion risks in remote settings (Source: intelligence DB ext #259). Every state change must be logged in Nextcloud Activity stream (Source: intelligence DB insight #25) + +#### Scenario: Publish council vote results for citizen transparency + +- GIVEN a completed council vote +- WHEN the clerk publishes the results +- THEN the system MUST generate a public-facing view showing: agenda item, vote type, per-member positions, totals, and outcome +- AND the data MUST be available via API in OpenRaadsinformatie format +- AND citizens MUST be able to search voting history by topic or member (Source: intelligence DB stories #168, #187) + +#### Scenario: Generate complete audit package for notarial deed + +- GIVEN a statute amendment adopted by qualified majority +- WHEN the notary requests proof of proper adoption +- THEN the system MUST produce: convocation proof (with delivery receipts), quorum verification log, individual voting records, and the resolution text +- AND the package MUST include cryptographic integrity verification (Source: intelligence DB story #78) + +--- + +### Requirement: Voting UX and Accessibility + +The system MUST provide an accessible, mobile-friendly voting interface that meets WCAG AA standards. The voting UX MUST minimize errors and provide clear confirmation of cast votes. + +**Feature tier**: MVP +**Evidence**: UX research shows mobile-first design boosts participation up to 3x; key principles include clean fonts >=12pt, high contrast ratio, vote confirmation builds trust (Source: intelligence DB ext #278). ElectionBuddy provides one-click voting via personal secure invitations (Source: intelligence DB ext #16) + +#### Scenario: Cast vote on mobile device + +- GIVEN a member accessing the voting panel on a mobile phone +- WHEN they tap their vote choice +- THEN the system MUST display a confirmation dialog: "You voted: FOR. Confirm?" +- AND after confirmation, display a receipt: "Vote recorded at [timestamp]" +- AND the interface MUST meet WCAG AA contrast ratios and support screen readers + +#### Scenario: Voting panel accessibility for keyboard-only users + +- GIVEN a member using keyboard-only navigation +- WHEN the voting panel is active +- THEN all vote options MUST be reachable via Tab key +- AND the current selection MUST have a visible focus indicator +- AND Enter/Space MUST activate the selected option + +## User Stories + +### Priority: Must Have + +1. **Chair conducting open vote**: As chair, I want to conduct an open vote (for/against/abstain) on an agenda item and see results in real-time so that I can announce the outcome immediately. (Source: intelligence DB #57) +2. **Chair initiating roll call vote**: As a voorzitter, I want to conduct a roll call vote (hoofdelijke stemming) with randomized starting position so that the voting order does not always favor the same factions. (Source: intelligence DB #166) +3. **Clerk recording individual voting records**: As a commissiegriffier, I want to automatically record how each member voted on each item so that voting records are complete and accurate. (Source: intelligence DB #167) +4. **Council member casting electronic vote**: As a council member, I want to cast my vote electronically during a plenary session so that voting is faster and results are immediately visible. (Source: intelligence DB #308) +5. **Clerk publishing vote results**: As a clerk, I want to publish vote results including each member's position so that citizens can verify how their representatives voted. (Source: intelligence DB #309) +6. **Board chair verifying ALV quorum**: As a board chair, I want to verify quorum before opening voting so that all decisions taken are legally valid per BW 2:38 and our statutes. (Source: intelligence DB #312) +7. **Member delegating vote via proxy**: As a member, I want to delegate my vote to another member via proxy so that my voice is counted even when I cannot attend the ALV. (Source: intelligence DB #313) +8. **Secretary conducting qualified majority vote**: As a board secretary, I want to conduct a 2/3 qualified majority vote so that statute amendments meet the legal threshold per BW 2:42. (Source: intelligence DB #314) +9. **Administrator enabling digital ALV voting**: As an association administrator, I want to enable digital voting during hybrid ALV meetings so that remote members can participate equally. (Source: intelligence DB #316) +10. **Secretary conducting weighted shareholder vote**: As a board secretary, I want to conduct weighted voting at the AGM so that each shareholder's vote reflects their share ownership. (Source: intelligence DB #317) +11. **Shareholder submitting proxy vote before AGM**: As a shareholder, I want to submit my proxy vote before the AGM so that my shares are voted even if I cannot attend. (Source: intelligence DB #318) +12. **MT member approving decision asynchronously**: As an MT member, I want to vote on decisions asynchronously so that we don't need to wait for the next meeting for routine approvals. (Source: intelligence DB #322) +13. **Chair classifying hamerstuk/bespreekstuk**: As a voorzitter, I want to classify agenda items as hamerstuk (consent) or bespreekstuk (discussion) so that meeting time is used efficiently. (Source: intelligence DB #158) +14. **Chair processing hamerstukken in batch**: As a voorzitter, I want to process all hamerstukken in one batch without debate so that meeting time is reserved for items requiring discussion. (Source: intelligence DB #164) +15. **Secretary conducting formal votes with configurable rules**: As a council clerk or board secretary, I want to conduct formal votes with configurable majority rules (simple, absolute, qualified 2/3), real-time vote counting, and an auditable result trail. (Source: intelligence DB #347) +16. **Secretary tracking quorum in real-time**: As a meeting secretary, I want real-time quorum tracking with automatic alerts when quorum is at risk and historical attendance analytics per member. (Source: intelligence DB #342) +17. **Citizen voting in participatory budget**: As a citizen, I want to allocate my budget tokens to community projects so that public money is spent on what residents actually want. (Source: intelligence DB #326) +18. **Citizen voting in local referendum**: As a citizen, I want to vote yes/no on a referendum question so that my voice directly influences municipal policy. (Source: intelligence DB #327) + +### Priority: Should Have + +19. **Secretary verifying voting rights**: As secretary, I want to verify each attendee's voting rights (paid-up membership, correct category) so that only eligible members participate in voting. (Source: intelligence DB #56) +20. **Member casting remote vote**: As a member attending remotely, I want to cast my vote securely during the ALV so that my participation is equal to physical attendees. (Source: intelligence DB #58) +21. **Chair conducting secret ballot**: As chair, I want to conduct a secret ballot for board elections so that members can vote freely without social pressure. (Source: intelligence DB #60) +22. **Member granting digital proxy**: As a member who cannot attend the ALV, I want to grant a proxy (volmacht) to another member digitally so that my vote is represented without paper forms. (Source: intelligence DB #63) +23. **Secretary recording board decisions with votes**: As secretary, I want to record each board decision with the vote distribution per board member so that we comply with WBTR documentation requirements. (Source: intelligence DB #66) +24. **Faction leader analyzing voting patterns**: As a faction leader, I want to analyze voting patterns across my party members so that I can assess party discipline and identify cross-party alliances. (Source: intelligence DB #310) +25. **Team lead using dot voting for backlog**: As a team lead, I want to use dot voting to prioritize backlog items so that the team collectively decides what to work on next. (Source: intelligence DB #321) +26. **Project manager using score polling**: As a project manager, I want to use score polling to evaluate multiple vendor proposals so that the team's nuanced preferences are captured. (Source: intelligence DB #323) +27. **Member voting by email reply**: As a member who cannot attend the meeting, I want to cast my vote by replying to the voting notification email so that my vote is counted without needing the platform. (Source: intelligence DB #1814) +28. **Stakeholder receiving calendar entries for voting deadlines**: As a stakeholder, I want voting deadlines to automatically appear in my calendar so that I never miss a deadline. (Source: intelligence DB #1829) +29. **Journalist searching voting history**: As a journalist, I want to search voting records by topic, member name, or faction so that I can research political positions for my reporting. (Source: intelligence DB #187) +30. **Citizen comparing faction positions**: As a burger, I want to compare how different factions voted on specific issues so that I can make an informed choice at the next election. (Source: intelligence DB #196) + +### Priority: Could Have + +31. **Investor casting split votes**: As an institutional investor, I want to cast split votes so that I can vote different shares in different directions reflecting diverse fund mandates. (Source: intelligence DB #319) +32. **Supervisory board chair recording consent decision**: As a supervisory board chair, I want to record consent-based decisions so that the board can approve matters efficiently without formal vote counting. (Source: intelligence DB #320) +33. **Department head using consent-based process**: As a department head, I want to use consent-based decision-making (sociocracy) so that decisions move forward quickly while ensuring no critical objections are missed. (Source: intelligence DB #324) +34. **MT member using ranked choice**: As an MT member, I want to rank options in order of preference so that the group finds the option with broadest support rather than just plurality. (Source: intelligence DB #325) +35. **Facilitator using quadratic voting**: As a facilitator, I want to use quadratic voting so that citizens can express intensity of preference across multiple issues without tyranny of the majority. (Source: intelligence DB #329) +36. **Fractievoorzitter recording faction positions**: As a fractievoorzitter, I want to record the agreed faction position (for/against/undecided) on each agenda item so that all members know how to vote. (Source: intelligence DB #153) +37. **Partijbestuurslid analyzing faction voting patterns**: As a partijbestuurslid, I want to analyze my faction's voting patterns across topics and time periods so that I can verify alignment with the party program. (Source: intelligence DB #195) +38. **Assembly participant voting on recommendations**: As an assembly participant, I want to vote on draft recommendations so that the final output reflects the group consensus. (Source: intelligence DB #225) +39. **Cooperative member voting on profit distribution**: As a cooperative member, I want to vote on the proposed profit distribution plan so that members collectively decide how cooperative earnings are allocated. (Source: intelligence DB #81) +40. **Chair circulating written resolution**: As chair, I want to circulate a proposal for written decision to all board members and collect their votes electronically so that urgent decisions can be made between meetings per BW 2:40. (Source: intelligence DB #68) + +## Competitor Analysis + +| Competitor | Voting Features | Strengths | Gaps | +|---|---|---|---| +| **Loomio** | 7 types: proposals, polls, dot voting, score (0-9), ranked choice, time poll, check | Best variety of collaborative voting methods; drag-and-drop ranked choice | No weighted voting, no formal quorum tracking, no legal compliance features | +| **OpenSlides** | 4 modes: analog, named electronic, token-based, VoteCollector hardware | Assembly-focused; live visualization on projector screens; motion-vote workflow | No ranked choice, no consent-based, no participatory budgeting | +| **Decidim** | Encrypted e-voting, threshold/weighted/cost-based, participatory budgeting | Open source (AGPL); 80+ governments; strong citizen participation | Heavy platform (Ruby on Rails); not suitable for board/corporate governance | +| **POLYAS** | BSI Common Criteria certified; browser-side encryption; anonymous tokens | Only certified online voting software; highest security guarantees | Pure voting tool; no meeting management, no minutes, no motion handling | +| **Belenios** | ElGamal homomorphic encryption; distributed key management; ZK proofs | Strongest cryptographic guarantees; open source (AGPL) | Academic tool; no organizational workflow; verification requires expertise | +| **ElectionBuddy** | FPTP, cumulative, preferential/STV, Borda, scored, approval, rating | Multi-channel (phone, web, mail, in-person); free under 20 voters | No meeting context; standalone voting tool only | +| **iBabs** | Digital voting with audit trail; quorum tracking; RSVP | ISO-certified; strong Dutch government presence; integrated RIS | Limited voting types (open only); no secret ballot; no ranked choice | +| **Notubiz** | Council instruments: motions, amendments, votes; NotuVote | Dominant Dutch council market; video integration | Poor UX ("a true maze"); limited voting types; closed platform | +| **Diligent/OnBoard** | E-voting, surveys, polls, AI minutes, resolutions | Enterprise board governance market leader; 700K+ directors | No legislative features; no citizen participation; expensive | + +(Sources: intelligence DB ext #266, #268, #267, #270, #269, #263, #97, #361, competitor features #685, #709, #699, #605, #601, #661, #642) ## Acceptance Criteria -- Open vote records individual votes per participant (for/against/abstain) +- Open vote records individual votes per participant (for/against/abstain) with real-time display - Secret ballot stores only aggregate totals with vote count integrity verification -- Configurable majority rules: simple, qualified (2/3, 3/4), unanimous, weighted -- Proxy votes are verifiable, count toward quorum, and respect per-member limits -- Remote votes have equal weight with session verification -- Quorum is rechecked before each vote -- Tie-breaking rules are configurable per body -- All voting results mapped to OpenRaadsinformatie `Stemming`/`Stem` -- Real-time result display during voting +- Roll call vote supports randomized order per Gemeentewet Art. 32 with tie-breaking rules +- Configurable majority rules: simple, absolute, qualified (2/3, 3/4), unanimous, weighted +- Proxy votes are verifiable, count toward quorum, respect per-member limits, and support split voting +- Remote votes have equal weight with session verification and identity confirmation +- Weighted voting calculates results proportionally to configured weights +- Ranked choice voting implements IRV (single-winner) and STV (multi-winner) +- Dot voting supports fixed-point and budget-constrained allocation +- Quadratic voting enforces credit-based cost function +- Consent-based decision records "adopted by consent" with participant list and objection status +- Approval voting and score polling support multi-option evaluation +- Asynchronous written procedure supports BW 2:238 consent-to-method requirement +- Consent agenda (hamerstukken) can be processed in batch with individual pull-out +- Quorum is tracked in real-time with alerts and historical analytics +- Tie-breaking rules are configurable per body (chair casting vote, lot, rejection, revote) +- Complete audit trail mapped to Nextcloud Activity stream +- All voting results mapped to OpenRaadsinformatie `Stemming`/`Stem` and Akoma Ntoso `voting`/`count` +- Voting UX meets WCAG AA; mobile-first design with vote confirmation +- E2E verifiability (cast-as-intended, recorded-as-cast, tallied-as-recorded) for secret ballots +- Decision tables for configurable voting rules per organization +- Voting interface activates automatically when the chair advances to an agenda item with a decisionPoint +- Amendments linked to a decision point are voted before the main motion in submission order +- Vote results update the agenda item status to "decided" in real-time on all participants' views +- Non-decision agenda items do not trigger the voting interface diff --git a/project.md b/project.md index 9afc358..60720b3 100644 --- a/project.md +++ b/project.md @@ -1,16 +1,14 @@ -# App Template — Decidesk +# Decidesk ## Overview -App Template is the official starter template for Conduction Nextcloud apps. It provides the standard structure, configuration, and tooling that all Conduction apps share. - -When creating a new app, clone this template and use `/app-create` to rename all identifiers. +Decidesk is a universal decision-making platform for governance bodies, associations, corporate boards, and operational meetings. It manages meetings, agendas, motions, amendments, voting, minutes, and decision tracking with configurable workflows per organization type. ## Architecture - **Type**: Nextcloud App (PHP backend + Vue 2 frontend) - **Data layer**: OpenRegister (all data stored as register objects) -- **Pattern**: Thin client — App Template provides UI/UX, OpenRegister handles persistence +- **Pattern**: Thin client — Decidesk provides UI/UX, OpenRegister handles persistence - **License**: EUPL-1.2 ## Tech Stack diff --git a/src/views/settings/AdminRoot.vue b/src/views/settings/AdminRoot.vue index 658e272..b670b34 100644 --- a/src/views/settings/AdminRoot.vue +++ b/src/views/settings/AdminRoot.vue @@ -1,12 +1,12 @@