From 7b6135b89b7d7652c3e9c8151b6b162a20d46e4f Mon Sep 17 00:00:00 2001
From: Albrecht Degering <albrecht@degering.name>
Date: Tue, 28 Jul 2026 19:05:37 +0200
Subject: [PATCH] Document governed Views architecture

---
 docs/VIEWS_ARCHITECTURE.md | 114 +++++++++++++++++++++++++++++++++++++
 docs/gitea-labels.json     |   6 ++
 2 files changed, 120 insertions(+)
 create mode 100644 docs/VIEWS_ARCHITECTURE.md

diff --git a/docs/VIEWS_ARCHITECTURE.md b/docs/VIEWS_ARCHITECTURE.md
new file mode 100644
index 0000000..073e666
--- /dev/null
+++ b/docs/VIEWS_ARCHITECTURE.md
@@ -0,0 +1,114 @@
+# GovOPlaN Views Architecture
+
+## Purpose
+
+GovOPlaN Views are governed presentation projections for a task,
+responsibility, or workflow step. A View can reduce the visible modules,
+navigation entries, routes, page sections, and commands to the interface
+needed for the current job.
+
+Views are optional. If `govoplan-views` is not installed or enabled, the normal
+permission-derived interface remains unchanged.
+
+## Security Boundary
+
+A View is not an authorization mechanism.
+
+- Access, tenant isolation, resource guards, and backend permission checks
+  remain authoritative.
+- A View may hide an interface surface that the actor is otherwise allowed to
+  use.
+- A View can never expose a route, action, tenant, or resource that normal
+  authorization denies.
+- An authorized deep link outside the current View should offer an explicit
+  temporary escape or View switch. It must not be presented as a permission
+  denial.
+
+This boundary lets Views improve focus without creating a second, weaker RBAC
+system.
+
+## Ownership
+
+Core owns the versioned, module-neutral surface contract and WebUI runtime
+hooks. Modules declare stable surfaces and use shared hooks to respect the
+effective projection. Modules do not import `govoplan-views`.
+
+`govoplan-views` owns:
+
+- draft and immutable published View revisions
+- system, tenant, group, and user assignments
+- default, mandatory, and user-selectable Views
+- active per-user View state
+- effective projection resolution and provenance
+- the View editor, preview, validation, and stale-surface diagnostics
+
+Policy optionally owns inherited ceilings and explainable decisions. Workflow
+optionally references a pinned View revision for an instance or step and may
+narrow it further.
+
+## Surface Contract
+
+Modules announce only useful, semantic surfaces:
+
+- module
+- navigation item
+- route or workspace
+- section or panel
+- command or action
+
+Each descriptor has a stable namespaced id, parent id, kind, label, default
+visibility, ordering, and dependency metadata where needed. Surface ids are
+public module contracts, not CSS selectors, component paths, or arbitrary DOM
+fragments.
+
+The first release supports visible or hidden. Read-only states, layout
+replacement, visual emphasis, and arbitrary styling are separate concerns and
+are deferred.
+
+## Effective Resolution
+
+The effective interface is the intersection of:
+
+1. installed and enabled modules
+2. actor permissions and resource access
+3. administrator and Policy ceilings
+4. an assigned or user-selected View
+5. an optional workflow instance or step overlay
+
+Lower scopes and workflow overlays may narrow inherited visibility but cannot
+broaden it. Every inherited, locked, hidden, unavailable, or stale choice
+should carry provenance that the editor and runtime can explain.
+
+Published View revisions are immutable. Active workflow instances pin the
+revision they use. Unknown or retired surface ids produce diagnostics rather
+than breaking startup. If no valid effective View can be resolved, the system
+uses the last valid projection or the normal authorized interface and reports
+the configuration problem to administrators.
+
+## Workflow Behavior
+
+A workflow definition may reference a View for the whole instance or a
+particular step. Starting, resuming, or advancing the workflow activates the
+appropriate projection. Users can intentionally leave focused mode and return
+from an open-work widget or notification without losing workflow state.
+
+Module handoffs carry the workflow and View context through Core contracts.
+Workflow does not import the target module or the Views implementation.
+
+## Delivery Order
+
+1. Define the Core surface registry and runtime hooks.
+2. Initialize `govoplan-views` and persist versioned definitions.
+3. Add assignment, selection, resolution, provenance, and the editor.
+4. Add Policy inheritance and administrator ceilings.
+5. Add Workflow instance and step activation.
+6. Adopt semantic section/action descriptors module by module.
+
+## Gitea Work Packages
+
+- `govoplan#17`: task-focused Views user story
+- `govoplan#16`: initialize and implement `govoplan-views`
+- `govoplan-core#271`: versioned surface and runtime contracts
+- `govoplan-policy#9`: inheritance, ceilings, and provenance
+- `govoplan-workflow#7`: workflow instance and step activation
+- `govoplan-workflow#3`: focused workflow mode user story
diff --git a/docs/gitea-labels.json b/docs/gitea-labels.json
index 2e620e2..02ebb56 100644
--- a/docs/gitea-labels.json
+++ b/docs/gitea-labels.json
@@ -329,6 +329,12 @@
     "description": "GovOPlaN Tenancy module behavior or integration.",
     "exclusive": false
   },
+  {
+    "name": "module/views",
+    "color": "c5def5",
+    "description": "GovOPlaN governed task views, interface projections, and workflow view integration.",
+    "exclusive": false
+  },
   {
     "name": "module/workflow",
     "color": "f9d0c4",