[Epic] Author configured-system semantics in Docs #49

New Issue

2026-08-21T00:06:46+02:00

zemion commented

2026-08-21 00:06:46 +02:00

Outcome

GovOPlaN Docs becomes the trusted place for three related but visibly distinct kinds of documentation:

System documentation — versioned product behavior supplied by each module.
Configured-state documentation — read-only facts derived from the actual tenant configuration, capabilities, policies, and runtime evidence.
Semantic documentation — institution-authored explanations of what configured artifacts mean, why they exist, how they should be used, and where their intended boundaries lie.

A configurator or process owner can, for example, document what a configured form field means locally or explain what a workflow is and is not intended to handle. End users see that explanation in the Help Center and in context without confusing authored guidance with executable configuration.

This extends the completed documentation-experience work in GovOPlaN/govoplan-docs#15.

Architectural boundary

Feature modules remain authoritative for executable configuration and expose safe, stable documentation subjects through a typed contract.
govoplan-docs owns tenant-authored semantic content, revisions, publication, discovery, and presentation.
Docs reads subjects through Core/module contracts and must not import feature internals.
Semantic content supplements product documentation and configured facts. It never changes validation, workflow execution, permissions, or other configuration.
A reader may see semantic content only when both the document visibility and the underlying subject authorization permit it.

Epic acceptance criteria

Product documentation, current configured-state facts, and tenant-authored semantics are labeled by source and composed predictably in Docs.
Authorized configurators can create, edit, review/publish, supersede, and retire semantic documentation for stable configured subjects.
Entries support locale, audience, meaning, intended use, non-intended use, examples, owner/steward, lifecycle state, and revision history.
Stable subject references support nested targets such as form fields and workflow steps without copying feature configuration into Docs.
Subject access is re-authorized by the owning module; tenant isolation and audience filtering cannot be bypassed through direct links, search, exports, or caches.
Changes to the referenced artifact produce a clear stale/review-required state; deletion or module disablement creates an orphaned/temporarily unavailable state and never silently reattaches content.
Draft, publish, and retire operations are permission-separated and audited.
Published semantics are discoverable in the Help Center and through route-, resource-, or field-aware contextual help.
Search indexes only authorized published content and preserves provenance, locale, and subject state.
Forms and Workflow provide the first end-to-end subject integrations.
User/admin documentation explains authoring, review, permissions, lifecycle, visibility, stale references, export/retention, and operational consequences.
Manifest-shape and focused cross-module checks cover the new extension boundary.

Non-goals

Turning Docs into the configuration editor or an arbitrary public-site CMS.
Letting authored prose override executable rules or conceal module-owned documentation.
Importing Forms, Workflow, or other feature internals into Docs.
Publishing tenant-specific runtime or semantic content through the generic public documentation export.

Delivery slices

GovOPlaN/govoplan-core#292 — stable, authorized semantic-subject contract
GovOPlaN/govoplan-docs#21 — tenant authoring, review, publication, rendering, search, and lifecycle
GovOPlaN/govoplan-forms#5 — first field-level semantic integration
GovOPlaN/govoplan-workflow#16 — first workflow/step semantic integration

Recommended order: contract first; Docs persistence/security and read composition second; Forms as the first end-to-end vertical slice; Workflow next; then promote the subject integration pattern to other configurable modules.

Verification

Contract tests for deterministic subject identity, safe projection, authorization, and lifecycle states.
Docs tests for tenant isolation, permissions, optimistic concurrency, publication, localization, stale/orphan handling, search filtering, exports, and audit events.
Forms and Workflow integration tests plus a manual end-to-end author/publish/read check.
/mnt/DATA/git/govoplan/tools/checks/check-manifest-shapes.py
/mnt/DATA/git/govoplan/tools/checks/check-focused.sh

## Outcome GovOPlaN Docs becomes the trusted place for three related but visibly distinct kinds of documentation: 1. **System documentation** — versioned product behavior supplied by each module. 2. **Configured-state documentation** — read-only facts derived from the actual tenant configuration, capabilities, policies, and runtime evidence. 3. **Semantic documentation** — institution-authored explanations of what configured artifacts mean, why they exist, how they should be used, and where their intended boundaries lie. A configurator or process owner can, for example, document what a configured form field means locally or explain what a workflow is and is not intended to handle. End users see that explanation in the Help Center and in context without confusing authored guidance with executable configuration. This extends the completed documentation-experience work in GovOPlaN/govoplan-docs#15. ## Architectural boundary - Feature modules remain authoritative for executable configuration and expose safe, stable documentation subjects through a typed contract. - `govoplan-docs` owns tenant-authored semantic content, revisions, publication, discovery, and presentation. - Docs reads subjects through Core/module contracts and must not import feature internals. - Semantic content supplements product documentation and configured facts. It never changes validation, workflow execution, permissions, or other configuration. - A reader may see semantic content only when both the document visibility and the underlying subject authorization permit it. ## Epic acceptance criteria - [x] Product documentation, current configured-state facts, and tenant-authored semantics are labeled by source and composed predictably in Docs. - [x] Authorized configurators can create, edit, review/publish, supersede, and retire semantic documentation for stable configured subjects. - [x] Entries support locale, audience, meaning, intended use, non-intended use, examples, owner/steward, lifecycle state, and revision history. - [x] Stable subject references support nested targets such as form fields and workflow steps without copying feature configuration into Docs. - [x] Subject access is re-authorized by the owning module; tenant isolation and audience filtering cannot be bypassed through direct links, search, exports, or caches. - [x] Changes to the referenced artifact produce a clear stale/review-required state; deletion or module disablement creates an orphaned/temporarily unavailable state and never silently reattaches content. - [x] Draft, publish, and retire operations are permission-separated and audited. - [x] Published semantics are discoverable in the Help Center and through route-, resource-, or field-aware contextual help. - [x] Search indexes only authorized published content and preserves provenance, locale, and subject state. - [x] Forms and Workflow provide the first end-to-end subject integrations. - [x] User/admin documentation explains authoring, review, permissions, lifecycle, visibility, stale references, export/retention, and operational consequences. - [x] Manifest-shape and focused cross-module checks cover the new extension boundary. ## Non-goals - Turning Docs into the configuration editor or an arbitrary public-site CMS. - Letting authored prose override executable rules or conceal module-owned documentation. - Importing Forms, Workflow, or other feature internals into Docs. - Publishing tenant-specific runtime or semantic content through the generic public documentation export. ## Delivery slices - [x] GovOPlaN/govoplan-core#292 — stable, authorized semantic-subject contract - [x] GovOPlaN/govoplan-docs#21 — tenant authoring, review, publication, rendering, search, and lifecycle - [x] GovOPlaN/govoplan-forms#5 — first field-level semantic integration - [x] GovOPlaN/govoplan-workflow#16 — first workflow/step semantic integration Recommended order: contract first; Docs persistence/security and read composition second; Forms as the first end-to-end vertical slice; Workflow next; then promote the subject integration pattern to other configurable modules. ## Verification - Contract tests for deterministic subject identity, safe projection, authorization, and lifecycle states. - Docs tests for tenant isolation, permissions, optimistic concurrency, publication, localization, stale/orphan handling, search filtering, exports, and audit events. - Forms and Workflow integration tests plus a manual end-to-end author/publish/read check. - `/mnt/DATA/git/govoplan/tools/checks/check-manifest-shapes.py` - `/mnt/DATA/git/govoplan/tools/checks/check-focused.sh`

zemion added the module/docs module/forms module/workflow area/governance codex/ready

module/core labels 2026-08-21 00:06:46 +02:00

zemion referenced this issue from GovOPlaN/govoplan-core

2026-08-21 00:07:02 +02:00

[Contract] Expose stable semantic-documentation subjects from modules #292

zemion referenced this issue from GovOPlaN/govoplan-docs

2026-08-21 00:07:21 +02:00

[User Story] Author, review, and publish tenant semantic documentation #21

zemion referenced this issue from GovOPlaN/govoplan-forms

2026-08-21 00:07:35 +02:00

[User Story] Document the local meaning of configured forms and fields #5

zemion referenced this issue from GovOPlaN/govoplan-workflow

2026-08-21 00:07:48 +02:00

[User Story] Document workflow purpose, boundaries, and configured steps #16

zemion commented

2026-08-21 14:58:32 +02:00

Core contract slice GovOPlaN/govoplan-core#292 is complete and closed in commit 925dc33. This unblocks Docs #21; Forms #5 and Workflow #16 remain intentionally dependent on the Docs persistence/publication slice for their end-to-end acceptance criteria.

zemion commented

2026-08-21 16:40:38 +02:00

Epic delivered and released.

Completed slices:

Core #292 — stable authorized semantic-subject contract (925dc33)
Docs #21 — tenant authoring, review/publication, lifecycle, visibility, search/export, and rendering (d6db344, 7984573)
Forms #5 — form/section/field subject integration (b9132d0)
Workflow #16 — definition/step subject integration and optional-boundary facade (0fd744a, d5214c6)

Root release evidence is synchronized in 6517b6a. The complete tools/checks/check-focused.sh gate passed: 68 manifest checks, DSAR and strict endpoint inventories, dependency boundaries, backend suites, all optional WebUI permutations, bundle budgets, browser conformance, and module interface checks.

A real browser author/publish/read smoke test remains recommended for deployment acceptance, but no implementation or product decision remains open in this epic.

Epic delivered and released. Completed slices: - Core #292 — stable authorized semantic-subject contract (925dc33) - Docs #21 — tenant authoring, review/publication, lifecycle, visibility, search/export, and rendering (d6db344, 7984573) - Forms #5 — form/section/field subject integration (b9132d0) - Workflow #16 — definition/step subject integration and optional-boundary facade (0fd744a, d5214c6) Root release evidence is synchronized in 6517b6a. The complete `tools/checks/check-focused.sh` gate passed: 68 manifest checks, DSAR and strict endpoint inventories, dependency boundaries, backend suites, all optional WebUI permutations, bundle budgets, browser conformance, and module interface checks. A real browser author/publish/read smoke test remains recommended for deployment acceptance, but no implementation or product decision remains open in this epic.

zemion closed this issue

2026-08-21 16:40:38 +02:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: GovOPlaN/govoplan#49