diff --git a/README.md b/README.md index 1e8ef9b..dedc660 100644 --- a/README.md +++ b/README.md @@ -123,7 +123,7 @@ Synchronize module package workflows and inspect the registry release contract: Package publication, exact artifact locking, and the optional `govoplan` developer meta-package are documented in -[Package Registry Releases](docs/PACKAGE_REGISTRY_RELEASES.md). +[Package Registry Releases](docs/operations/PACKAGE_REGISTRY_RELEASES.md). For reproducible release artifacts, set `SOURCE_DATE_EPOCH` to the release commit timestamp (or pass an explicit timezone-qualified `--timestamp`): @@ -170,19 +170,19 @@ Create and validate a private, declarative installation bundle: ``` The current executable slice and remaining production gates are documented in -[Installation and Deployment Architecture](docs/INSTALLATION_AND_DEPLOYMENT_ARCHITECTURE.md). +[Installation and Deployment Architecture](docs/operations/INSTALLATION_AND_DEPLOYMENT_ARCHITECTURE.md). The canonical distinction between local source development, split source integration, immutable single-host rehearsal, one-host production and multi-host Kubernetes production is in -[Deployment Profiles](docs/DEPLOYMENT_PROFILES.md). +[Deployment Profiles](docs/operations/DEPLOYMENT_PROFILES.md). Same-host replica balancing and the multi-host promotion boundary are documented -in [Scaling and Multi-Host Deployment](docs/SCALING_AND_MULTI_HOST_DEPLOYMENT.md). +in [Scaling and Multi-Host Deployment](docs/operations/SCALING_AND_MULTI_HOST_DEPLOYMENT.md). Create, update, pause, resume, verify and remove a local or multi-hypervisor K3s VM target with the guarded lifecycle documented in -[Kubernetes VM Test Lab](docs/KUBERNETES_TEST_LAB.md). +[Kubernetes VM Test Lab](docs/operations/KUBERNETES_TEST_LAB.md). The recovery state machine, migration rollback boundary, and required restore drills are documented in -[Recovery and Rollback Guarantees](docs/RECOVERY_AND_ROLLBACK_GUARANTEES.md). +[Recovery and Rollback Guarantees](docs/operations/RECOVERY_AND_ROLLBACK_GUARANTEES.md). ## Configuration @@ -195,47 +195,14 @@ such as `~/.config/gitea/gitea.env` and be passed with `--env-file`. ## Structure -The repository categories are documented in -`docs/REPOSITORY_STRUCTURE.md`. The machine-readable list lives in -`repositories.json`; the clickable human-readable index is -`docs/REPOSITORY_INDEX.md`. +Start with the [documentation map](docs/README.md). It separates stable +strategy, architecture, operations, project reference, pinned evidence, and +historical records and identifies the canonical source for each question. -Meta ownership and module install/contract boundaries are documented in -`docs/META_REPO_SCAN.md` and `docs/MODULE_CONTRACTS_AND_INSTALLS.md`. -Frontend layout principles for module pages are documented in -`docs/FRONTEND_LAYOUT_PRINCIPLES.md`. -The provider-neutral datasource boundary and reusable Dataflow/Workflow graph -contract are documented in -`docs/DATASOURCE_AND_DEFINITION_GRAPH_ARCHITECTURE.md`. -The cross-product destination, stakeholder visions, configuration archetypes, -connected outcome stories, and capability horizons are documented in -the [Connected Governance Platform Roadmap](docs/CONNECTED_GOVERNANCE_PLATFORM_ROADMAP.md). -The reconciled institutional semantics, source-authority modes, module layers, -candidate Mandates/Services/Parties/Decisions boundaries, and migration -sequence are documented in the -[Institutional Governance Target Architecture](docs/INSTITUTIONAL_GOVERNANCE_TARGET_ARCHITECTURE.md). -The selected Campaign-to-Postbox-to-data-to-collaboration implementation path, -including stage gates and shared documentation expectations, is in the -[Reference Journey Program](docs/REFERENCE_JOURNEY_PROGRAM.md). -The administrator journey from a Core-baseline bootstrap through online module -installation, scale-out, and reversible environment promotion is defined in -[System Administrator Lifecycle User Story](docs/SYSTEM_ADMINISTRATOR_LIFECYCLE_USER_STORY.md). -The corresponding host deployment compiler, managed/external component choices, -reconfiguration semantics, and safe Web update boundary are defined in -[Installation and Deployment Architecture](docs/INSTALLATION_AND_DEPLOYMENT_ARCHITECTURE.md). -The concrete replica, worker-node, load-balancer, and shared-state topology is -defined in [Scaling and Multi-Host Deployment](docs/SCALING_AND_MULTI_HOST_DEPLOYMENT.md). -Durable deployment journals, Core recovery evidence, and the distinction -between pre-migration configuration restore and post-migration forward recovery -are defined in -[Recovery and Rollback Guarantees](docs/RECOVERY_AND_ROLLBACK_GUARANTEES.md). -The first Campaign-centric capability and infrastructure fit assessment is in -`docs/CAPABILITY_AND_INFRASTRUCTURE_FIT.md`. Its rerun tooling can collect and -verify a bounded installed composition; target, provider and production claims -remain separate, expiring attestations signed by independently scoped proof -authorities. The operational issuance, target-run, recovery-measurement, key -custody, and promotion-gate procedure is in -[Target Maturity Evidence Runbook](docs/TARGET_MATURITY_EVIDENCE_RUNBOOK.md). +The machine-readable repository list lives in `repositories.json`; the +clickable directory is the +[Repository Index](docs/project/REPOSITORY_INDEX.md), and ownership boundaries +are in [Repository Structure](docs/project/REPOSITORY_STRUCTURE.md). # GovOPlaN Docker diff --git a/dev/production-like/README.md b/dev/production-like/README.md index 9605801..1a5e05c 100644 --- a/dev/production-like/README.md +++ b/dev/production-like/README.md @@ -3,7 +3,7 @@ This profile runs the shared services that production depends on while keeping API, worker, scheduler, and WebUI code in the editable local repositories. It is the **split source integration** profile defined in -[`docs/DEPLOYMENT_PROFILES.md`](../../docs/DEPLOYMENT_PROFILES.md). It does not +[`docs/operations/DEPLOYMENT_PROFILES.md`](../../docs/operations/DEPLOYMENT_PROFILES.md). It does not exercise signed application images. Use an installer-generated evaluation Compose bundle for an immutable Dockerized whole-product rehearsal. diff --git a/docs/FRONTEND_LAYOUT_PRINCIPLES.md b/docs/FRONTEND_LAYOUT_PRINCIPLES.md deleted file mode 100644 index efaf7dc..0000000 --- a/docs/FRONTEND_LAYOUT_PRINCIPLES.md +++ /dev/null @@ -1,77 +0,0 @@ -# GovOPlaN Frontend Layout Principles - -GovOPlaN modules should choose their page layout by the kind of work the user is -doing, not by the repository that owns the feature. - -These concise layout choices are one canonical input to the broader -[`INTERFACE_PATTERN_LANGUAGE.md`](INTERFACE_PATTERN_LANGUAGE.md). The current -route and rollout evidence lives in -[`INTERFACE_SURFACE_INVENTORY.md`](INTERFACE_SURFACE_INVENTORY.md). - -## Structured Data Directories - -Use a full-available-space workspace for structured data directories: files, -addresses, calendars, records, mailboxes, document stores, and similar domains -where the primary task is browsing, selecting, filtering, inspecting, and acting -on related objects. - -Principles: - -- The module route should use the full available content area. -- Do not add a separate page heading row above the main workspace. -- Prefer persistent navigation panes, such as tree panels, source panels, folder - panels, calendar list panels, or mailbox folder panels. -- Keep collection navigation and collection-level actions close to the relevant - pane header. -- In a list-detail workspace such as Scheduling, keep related lists stacked in - the left pane and use the remaining main pane for view/create/edit. A single - Add action stays in the relevant list-pane header and opens the common main - editor; it does not create an additional menu or launcher. -- Use bounded widths for navigation/list panes and let the main detail/content - pane take the remaining space. -- Keep filtering controls inside the pane they affect. -- Use overlays, toasts, or floating alerts for transient messages so the - workspace height does not change. - -This pattern is appropriate when the user is working inside one coherent data -domain and needs spatial continuity. - -## Workflow And Configuration Surfaces - -Use the standard heading/menu/card visual language for workflow structures, -settings, administration, dashboards, and pages that collect essentially -unrelated areas. - -Principles: - -- A page heading and subnavigation are appropriate when the page explains a - task, workflow stage, or administrative area. -- Cards are appropriate for repeated independent panels, settings groups, - summaries, and dashboard widgets. -- Collapsible panels and segmented controls are appropriate when a dense - configuration area needs controlled disclosure. -- A collapsible card whose sole content is a table gives that table the full - available card body; avoid nested cards, duplicate padding, inner max-widths, - and nested scrolling. -- Avoid forcing workflow/configuration pages into a file-explorer style unless - the primary interaction is genuinely directory browsing. - -This pattern is appropriate when the user is comparing or configuring separate -concerns rather than navigating one structured object space. - -## Shared Components - -Reusable layout components belong in `govoplan-core` WebUI. Modules may consume -shared components from core, but must not import another module's private UI -components directly. - -When a module-specific component becomes generally useful, promote it to core -with a parameterized API before reusing it elsewhere. - -Non-self-explanatory fields use Core `FieldLabel`; documented omissions must -name their accessible-label source. Explicit Discard and dirty navigation use -the same Core unsaved-changes dialog. Table action sets retain unavailable row -actions as disabled controls and reserve empty-state slots so Add remains -aligned. Use central feedback/dialog components; `window.alert` is not an -authorized product surface unless a product-owner-approved exception is first -recorded in the Core decision ledger. diff --git a/docs/README.md b/docs/README.md index 1d4e459..1693010 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,80 +1,119 @@ -# GovOPlaN Documentation Map +# GovOPlaN Documentation -This directory contains cross-repository product, architecture, release, and -operational documentation. The map below defines which document answers which -question. A document not listed as the current status source must not present -volatile repository, issue, release, or maturity counts as current facts. +This directory contains cross-repository product, architecture, delivery, and +project documentation. Start here instead of browsing every file. + +## Read First + +| Need | Source | +| --- | --- | +| Understand the platform in ten minutes | [Platform Core Ideas](strategy/PLATFORM_CORE_IDEAS.md) | +| See the intended product sequence | [Roadmap](strategy/ROADMAP.md) | +| Check the reconciled state and material gaps | [Strategy Status](strategy/STRATEGY_STATUS.md) | +| Find active work, priority, or ownership | [Gitea issue workflow](project/GITEA_ISSUES.md) and Gitea issues | +| Understand the selected end-to-end proofs | [Reference Journey Program](strategy/REFERENCE_JOURNEY_PROGRAM.md) | + +The first three documents are the normal entry points. Detailed architecture, +runbooks, evidence, and historical assessments support them; they are not +parallel roadmaps. ## Strategy -| Question | Canonical source | +| Document | Role | | --- | --- | -| What are the stable ideas and boundaries of the platform? | [Platform Core Ideas](PLATFORM_CORE_IDEAS.md) | -| What product outcomes should GovOPlaN pursue? | [Connected Governance Platform Roadmap](CONNECTED_GOVERNANCE_PLATFORM_ROADMAP.md) | -| Which institutional concepts and owners form the target architecture? | [Institutional Governance Target Architecture](INSTITUTIONAL_GOVERNANCE_TARGET_ARCHITECTURE.md) | -| Which end-to-end proofs should guide implementation? | [Reference Journey Program](REFERENCE_JOURNEY_PROGRAM.md) | -| What is the reconciled state now? | [Strategy Status](STRATEGY_STATUS.md) | -| Which collected ideas and user stories inform the product direction? | [Product Input Register](PRODUCT_INPUT_REGISTER.md) | +| [Platform Core Ideas](strategy/PLATFORM_CORE_IDEAS.md) | Stable purpose, principles, planes, distinctions, and non-goals | +| [Roadmap](strategy/ROADMAP.md) | Concise product outcomes, horizons, and current sequence | +| [Strategy Status](strategy/STRATEGY_STATUS.md) | Only prose source for current cross-product status | +| [Reference Journey Program](strategy/REFERENCE_JOURNEY_PROGRAM.md) | Acceptance journeys and their gates | +| [Product Input Register](strategy/PRODUCT_INPUT_REGISTER.md) | Normalized ideas and user-story source material | +| [System Administrator Lifecycle](strategy/SYSTEM_ADMINISTRATOR_LIFECYCLE_USER_STORY.md) | Installation and lifecycle outcome story | +| [Detailed Connected-Platform Vision](strategy/reference/CONNECTED_GOVERNANCE_PLATFORM_ROADMAP.md) | Long-form stakeholder, configuration, and outcome catalogue | -The dated [Strategic Review](STRATEGIC_REVIEW_2026-08-05.md) explains why the -current reset and sequencing were chosen. It is an assessment record, not a -second live status page. - -## Product Architecture +## Architecture | Topic | Canonical source | | --- | --- | -| Product-facing experience and hiding technical module boundaries | [Product Experience and Module Boundaries](PRODUCT_EXPERIENCE_AND_MODULE_BOUNDARIES.md) | -| Configurable product areas and task-local tools | [Quick Access and Product Areas](QUICK_ACCESS_AND_PRODUCT_AREAS.md) | -| Federation between autonomous installations | [Federated GovOPlaN Architecture](FEDERATED_GOVOPLAN_ARCHITECTURE.md) | -| Institutional digital twin and continuous assurance | [Institutional Digital Twin](INSTITUTIONAL_DIGITAL_TWIN.md) | -| Assisted and non-digital channels | [Assisted and Non-Digital Channels](ASSISTED_AND_NON_DIGITAL_CHANNELS.md) | -| Cross-module temporal, purpose, retention, and institutional-context adoption | `govoplan-core/docs/INFORMATION_GOVERNANCE_ADOPTION.md` | -| eAkte and digital-record ownership | `govoplan-records/docs/EAKTE_ARCHITECTURE.md` | -| Data source, definition, and transformation graph | [Datasource and Definition Graph Architecture](DATASOURCE_AND_DEFINITION_GRAPH_ARCHITECTURE.md) | -| Focused task views | [Views Architecture](VIEWS_ARCHITECTURE.md) | -| Shared interface patterns | [Interface Pattern Language](INTERFACE_PATTERN_LANGUAGE.md) | +| Institutional model and ownership | [Institutional Governance Target Architecture](architecture/INSTITUTIONAL_GOVERNANCE_TARGET_ARCHITECTURE.md) | +| Product experience and technical boundaries | [Product Experience and Module Boundaries](architecture/PRODUCT_EXPERIENCE_AND_MODULE_BOUNDARIES.md) | +| Shared interface and layout rules | [Interface Pattern Language](architecture/INTERFACE_PATTERN_LANGUAGE.md) | +| Focused task views | [Views Architecture](architecture/VIEWS_ARCHITECTURE.md) | +| Product areas and task-local tools | [Quick Access and Product Areas](architecture/QUICK_ACCESS_AND_PRODUCT_AREAS.md) | +| Platform self-description and configuration | [Platform Control Plane](architecture/PLATFORM_CONTROL_PLANE.md) | +| Data sources, definitions, and graph execution | [Datasource and Definition Graph Architecture](architecture/DATASOURCE_AND_DEFINITION_GRAPH_ARCHITECTURE.md) | +| Federation between autonomous installations | [Federated GovOPlaN Architecture](architecture/FEDERATED_GOVOPLAN_ARCHITECTURE.md) | +| Institutional digital twin | [Institutional Digital Twin](architecture/INSTITUTIONAL_DIGITAL_TWIN.md) | +| Assisted and non-digital participation | [Assisted and Non-Digital Channels](architecture/ASSISTED_AND_NON_DIGITAL_CHANNELS.md) | -## Runtime And Delivery +Module-specific architecture remains in the owning repository. In particular, +information-governance adoption is in +`govoplan-core/docs/INFORMATION_GOVERNANCE_ADOPTION.md`, and the eAkte model is +in `govoplan-records/docs/EAKTE_ARCHITECTURE.md`. -- [Module Contracts and Installs](MODULE_CONTRACTS_AND_INSTALLS.md) -- [Platform Control Plane](PLATFORM_CONTROL_PLANE.md) -- [Installation and Deployment Architecture](INSTALLATION_AND_DEPLOYMENT_ARCHITECTURE.md) -- [Kubernetes VM Test Lab](KUBERNETES_TEST_LAB.md) -- [Deployment Profiles](DEPLOYMENT_PROFILES.md) -- [Scaling and Multi-Host Deployment](SCALING_AND_MULTI_HOST_DEPLOYMENT.md) -- [Recovery and Rollback Guarantees](RECOVERY_AND_ROLLBACK_GUARANTEES.md) -- [Recovery Ledger Adoption](RECOVERY_LEDGER_ADOPTION.md) -- [Package Registry Releases](PACKAGE_REGISTRY_RELEASES.md) +## Operations -## Evidence And Snapshots +| Need | Source | +| --- | --- | +| Installation model and managed components | [Installation and Deployment Architecture](operations/INSTALLATION_AND_DEPLOYMENT_ARCHITECTURE.md) | +| Supported operating modes | [Deployment Profiles](operations/DEPLOYMENT_PROFILES.md) | +| Horizontal scaling and multi-host topology | [Scaling and Multi-Host Deployment](operations/SCALING_AND_MULTI_HOST_DEPLOYMENT.md) | +| Local Kubernetes evidence target | [Kubernetes VM Test Lab](operations/KUBERNETES_TEST_LAB.md) | +| Recovery guarantees and state machine | [Recovery and Rollback Guarantees](operations/RECOVERY_AND_ROLLBACK_GUARANTEES.md) | +| Recovery-ledger rollout | [Recovery Ledger Adoption](operations/RECOVERY_LEDGER_ADOPTION.md) | +| Backup evidence contract | [Backup and Restore Evidence](operations/BACKUP_AND_RESTORE_EVIDENCE.md) | +| Target handoff and independent evidence | [Production Target Handoff](operations/PRODUCTION_TARGET_HANDOFF.md) | +| Evidence collection and promotion | [Target Maturity Evidence Runbook](operations/TARGET_MATURITY_EVIDENCE_RUNBOOK.md) | +| Package publication and consumption | [Package Registry Releases](operations/PACKAGE_REGISTRY_RELEASES.md) | +| Release-console operation | [Release Console](operations/RELEASE_CONSOLE.md) | +| Module compatibility and install behavior | [Module Contracts and Installs](operations/MODULE_CONTRACTS_AND_INSTALLS.md) | +| Security-audit toolchain | [Security Audit](operations/SECURITY_AUDIT.md) | -These documents are intentionally dated or pinned. They may remain useful even -after the product changes, but they do not override `STRATEGY_STATUS.md`. +## Project Reference -- [Capability and Infrastructure Fit Assessment](CAPABILITY_AND_INFRASTRUCTURE_FIT.md), pinned to the 2026-07-22 Campaign composition -- [Strategic Review 2026-08-05](STRATEGIC_REVIEW_2026-08-05.md) -- [Backup and Restore Evidence](BACKUP_AND_RESTORE_EVIDENCE.md) -- [Production Target Handoff](PRODUCTION_TARGET_HANDOFF.md) -- [Target Maturity Evidence Runbook](TARGET_MATURITY_EVIDENCE_RUNBOOK.md) +- [Repository Index](project/REPOSITORY_INDEX.md) is the human-readable module + and repository directory; `../repositories.json` is authoritative for tools. +- [Repository Structure](project/REPOSITORY_STRUCTURE.md) defines ownership of + meta, module, deployment, and website content. +- [Gitea Issues](project/GITEA_ISSUES.md) defines labels, templates, import, and + state-update conventions. -Machine-readable schemas and evidence files belong beside the document that -defines them. Generated inventories belong in `audit-reports/` and should not -be edited manually. +## Evidence And Archive + +Pinned evidence is retained under `evidence/`; completed reviews and migration +inventories are under `archive/`. They explain or prove a dated state and must +not be read as current product status. + +- [Campaign capability and infrastructure fit, 2026-07-22](evidence/snapshots/CAPABILITY_AND_INFRASTRUCTURE_FIT.md) +- [Interface surface inventory, 2026-08-03](evidence/snapshots/INTERFACE_SURFACE_INVENTORY.md) +- [Strategic review, 2026-08-05](archive/2026-08/STRATEGIC_REVIEW_2026-08-05.md) +- [Meta repository scan, 2026-07-13](archive/2026-07/META_REPO_SCAN.md) +- [Meta repository migration audit](archive/2026-07/META_REPOSITORY_MIGRATION_AUDIT.md) + +The JSON files at the root of this directory are machine-readable schemas, +evidence inputs, and project configuration. Their paths are intentionally +stable because tools and published schema identifiers consume them; they are +not additional reading-list entries. ## Maintenance Rules -1. Gitea issues are the only live work-state source. -2. `STRATEGY_STATUS.md` is the only prose reconciliation of current portfolio - state. Refresh it from manifests, inventories, tests, and Gitea; do not copy - its counts into durable architecture pages. +1. Gitea issues are the only live source for work state, priority, and owner. +2. `strategy/STRATEGY_STATUS.md` is the only prose reconciliation of current + portfolio state. Do not copy its volatile counts into durable documents. 3. Durable documents state decisions, invariants, ownership, and acceptance - gates. They link to status and issues for implementation depth. -4. Dated assessments retain their original composition and conclusion. Add a - snapshot notice rather than silently updating their claims. -5. Module-specific behavior and user/admin documentation remain in the owning - repository. Meta documentation defines cross-module outcomes and contracts. -6. A new strategy document must replace, narrow, or link an existing source; - it must not introduce a parallel roadmap. -7. The Product Input Register preserves external idea and story notes, but only - Gitea issues carry live priority, ownership, and implementation state. + gates. They link to Gitea for implementation detail. +4. Dated evidence and archive documents retain their original composition and + conclusion. Add a snapshot notice instead of silently modernizing them. +5. Module-specific behavior and user/admin documentation stay in the owning + repository. Meta documentation covers cross-module outcomes and contracts. +6. Do not add another top-level Markdown file. Place new content in the + appropriate directory and add it to this map only when it has a distinct + canonical purpose. +7. A new strategy document must replace, narrow, or become a reference for an + existing source; it must not introduce a parallel roadmap. +8. The Product Input Register preserves source ideas. Only a named journey, + package, or Gitea issue turns an idea into implementation work. + +After moving or adding documentation, run: + +```sh +./.venv/bin/python -m unittest tests.test_documentation_structure +``` diff --git a/docs/ASSISTED_AND_NON_DIGITAL_CHANNELS.md b/docs/architecture/ASSISTED_AND_NON_DIGITAL_CHANNELS.md similarity index 100% rename from docs/ASSISTED_AND_NON_DIGITAL_CHANNELS.md rename to docs/architecture/ASSISTED_AND_NON_DIGITAL_CHANNELS.md diff --git a/docs/DATASOURCE_AND_DEFINITION_GRAPH_ARCHITECTURE.md b/docs/architecture/DATASOURCE_AND_DEFINITION_GRAPH_ARCHITECTURE.md similarity index 100% rename from docs/DATASOURCE_AND_DEFINITION_GRAPH_ARCHITECTURE.md rename to docs/architecture/DATASOURCE_AND_DEFINITION_GRAPH_ARCHITECTURE.md diff --git a/docs/FEDERATED_GOVOPLAN_ARCHITECTURE.md b/docs/architecture/FEDERATED_GOVOPLAN_ARCHITECTURE.md similarity index 100% rename from docs/FEDERATED_GOVOPLAN_ARCHITECTURE.md rename to docs/architecture/FEDERATED_GOVOPLAN_ARCHITECTURE.md diff --git a/docs/INSTITUTIONAL_DIGITAL_TWIN.md b/docs/architecture/INSTITUTIONAL_DIGITAL_TWIN.md similarity index 100% rename from docs/INSTITUTIONAL_DIGITAL_TWIN.md rename to docs/architecture/INSTITUTIONAL_DIGITAL_TWIN.md diff --git a/docs/INSTITUTIONAL_GOVERNANCE_TARGET_ARCHITECTURE.md b/docs/architecture/INSTITUTIONAL_GOVERNANCE_TARGET_ARCHITECTURE.md similarity index 98% rename from docs/INSTITUTIONAL_GOVERNANCE_TARGET_ARCHITECTURE.md rename to docs/architecture/INSTITUTIONAL_GOVERNANCE_TARGET_ARCHITECTURE.md index 3e22ed4..2524982 100644 --- a/docs/INSTITUTIONAL_GOVERNANCE_TARGET_ARCHITECTURE.md +++ b/docs/architecture/INSTITUTIONAL_GOVERNANCE_TARGET_ARCHITECTURE.md @@ -12,21 +12,21 @@ The source concepts describe GovOPlaN as an operational governance platform for public institutions. This document is the canonical repository version of that durable architectural direction. Its implementation table records the accepted 2026-08-01 baseline; it is not a rolling status report. Current reconciliation -lives in [Strategy Status](STRATEGY_STATUS.md), and Gitea issues remain the +lives in [Strategy Status](../strategy/STRATEGY_STATUS.md), and Gitea issues remain the source of truth for delivery state. Read this together with: -- [Connected Governance Platform Roadmap](CONNECTED_GOVERNANCE_PLATFORM_ROADMAP.md) -- [Platform Core Ideas](PLATFORM_CORE_IDEAS.md) -- [Strategy Status](STRATEGY_STATUS.md) -- [Reference Journey Program](REFERENCE_JOURNEY_PROGRAM.md) -- [Module Contracts and Install Boundaries](MODULE_CONTRACTS_AND_INSTALLS.md) +- [Connected Governance Platform Roadmap](../strategy/reference/CONNECTED_GOVERNANCE_PLATFORM_ROADMAP.md) +- [Platform Core Ideas](../strategy/PLATFORM_CORE_IDEAS.md) +- [Strategy Status](../strategy/STRATEGY_STATUS.md) +- [Reference Journey Program](../strategy/REFERENCE_JOURNEY_PROGRAM.md) +- [Module Contracts and Install Boundaries](../operations/MODULE_CONTRACTS_AND_INSTALLS.md) - [Datasource and Definition Graph Architecture](DATASOURCE_AND_DEFINITION_GRAPH_ARCHITECTURE.md) -- [Capability and Infrastructure Fit](CAPABILITY_AND_INFRASTRUCTURE_FIT.md) -- [Core Module Architecture](../../govoplan-core/docs/MODULE_ARCHITECTURE.md) -- [Core External References and Integration Maturity](../../govoplan-core/docs/EXTERNAL_REFERENCES_AND_INTEGRATION_MATURITY.md) -- [Core Action, Effect, and Automation Layer](../../govoplan-core/docs/ACTION_EFFECT_AUTOMATION_LAYER.md) +- [Capability and Infrastructure Fit](../evidence/snapshots/CAPABILITY_AND_INFRASTRUCTURE_FIT.md) +- [Core Module Architecture](../../../govoplan-core/docs/MODULE_ARCHITECTURE.md) +- [Core External References and Integration Maturity](../../../govoplan-core/docs/EXTERNAL_REFERENCES_AND_INTEGRATION_MATURITY.md) +- [Core Action, Effect, and Automation Layer](../../../govoplan-core/docs/ACTION_EFFECT_AUTOMATION_LAYER.md) ## Decision diff --git a/docs/INTERFACE_PATTERN_LANGUAGE.md b/docs/architecture/INTERFACE_PATTERN_LANGUAGE.md similarity index 96% rename from docs/INTERFACE_PATTERN_LANGUAGE.md rename to docs/architecture/INTERFACE_PATTERN_LANGUAGE.md index 1d7eb92..1638811 100644 --- a/docs/INTERFACE_PATTERN_LANGUAGE.md +++ b/docs/architecture/INTERFACE_PATTERN_LANGUAGE.md @@ -2,12 +2,13 @@ This document is the cross-repository pattern language for GovOPlaN user interfaces. It turns the existing ethical doctrine, binding UI/UX decisions, -layout principles, and module boundary into a common composition and review -grammar. It does not replace those sources. +layout rules, and module boundary into a common composition and review grammar. +This document also owns the former standalone frontend-layout principles. -The companion [interface surface inventory](INTERFACE_SURFACE_INVENTORY.md) -records which surfaces the current code contributes and where each surface -enters the rollout. +The dated [interface surface inventory](../evidence/snapshots/INTERFACE_SURFACE_INVENTORY.md) +records the 2026-08-03 rollout snapshot. Current implementation state belongs +in Gitea and generated inventory evidence, not in this durable pattern +language. ## Source Of Truth And Precedence @@ -19,14 +20,11 @@ Use the narrowest owning document when changing a rule: 2. `govoplan-core/docs/UI_UX_DECISION_LEDGER.md` owns accepted product decisions such as progressive disclosure, adaptive forms, blocker language, guided operations, and the platform theme contract. -3. `docs/FRONTEND_LAYOUT_PRINCIPLES.md` owns the high-level choice between a - full-space structured-data workspace and a heading/menu/card workflow or - configuration surface. -4. `govoplan-core/docs/MODULE_ARCHITECTURE.md` owns the shell, route, navigation, +3. `govoplan-core/docs/MODULE_ARCHITECTURE.md` owns the shell, route, navigation, UI-capability, and shared-component boundaries. -5. This document owns the common pattern names, placement grammar, wording and - state conventions, focused-view composition, and definition of done across - those sources. +4. This document owns the high-level layout choice, common pattern names, + placement grammar, wording and state conventions, focused-view composition, + and definition of done across those sources. If two rules appear to conflict, do not create a third local convention. Record the conflict in the owning decision ledger, resolve it there, and update the @@ -95,6 +93,12 @@ one. - Structured directories use the full available content space and persistent panes. They do not add a decorative heading row that reduces working height. + Give navigation and list panes bounded widths and let the main content or + detail pane consume the remaining space. +- In a list-detail workspace, related lists may be stacked in the left pane + while the main pane owns view, create, and edit. Keep one create action in + the relevant list heading instead of adding a second launcher or permanent + creation panel. - Workflow, configuration, dashboard, and explanatory pages may use a heading. The heading names the task or scoped object and contains only route-level actions. diff --git a/docs/PLATFORM_CONTROL_PLANE.md b/docs/architecture/PLATFORM_CONTROL_PLANE.md similarity index 100% rename from docs/PLATFORM_CONTROL_PLANE.md rename to docs/architecture/PLATFORM_CONTROL_PLANE.md diff --git a/docs/PRODUCT_EXPERIENCE_AND_MODULE_BOUNDARIES.md b/docs/architecture/PRODUCT_EXPERIENCE_AND_MODULE_BOUNDARIES.md similarity index 100% rename from docs/PRODUCT_EXPERIENCE_AND_MODULE_BOUNDARIES.md rename to docs/architecture/PRODUCT_EXPERIENCE_AND_MODULE_BOUNDARIES.md diff --git a/docs/QUICK_ACCESS_AND_PRODUCT_AREAS.md b/docs/architecture/QUICK_ACCESS_AND_PRODUCT_AREAS.md similarity index 100% rename from docs/QUICK_ACCESS_AND_PRODUCT_AREAS.md rename to docs/architecture/QUICK_ACCESS_AND_PRODUCT_AREAS.md diff --git a/docs/VIEWS_ARCHITECTURE.md b/docs/architecture/VIEWS_ARCHITECTURE.md similarity index 98% rename from docs/VIEWS_ARCHITECTURE.md rename to docs/architecture/VIEWS_ARCHITECTURE.md index f78a584..99b628b 100644 --- a/docs/VIEWS_ARCHITECTURE.md +++ b/docs/architecture/VIEWS_ARCHITECTURE.md @@ -141,7 +141,7 @@ Still intentionally separate: Quick Access ordering and availability remain owned by `govoplan-quick-access`; Views only narrow its declared surfaces for the active task. Neither contract permits arbitrary layout or styling. See -`docs/QUICK_ACCESS_AND_PRODUCT_AREAS.md` in the meta repository. +`docs/architecture/QUICK_ACCESS_AND_PRODUCT_AREAS.md` in the meta repository. ## Gitea Work Packages diff --git a/docs/META_REPOSITORY_MIGRATION_AUDIT.md b/docs/archive/2026-07/META_REPOSITORY_MIGRATION_AUDIT.md similarity index 95% rename from docs/META_REPOSITORY_MIGRATION_AUDIT.md rename to docs/archive/2026-07/META_REPOSITORY_MIGRATION_AUDIT.md index 8b23bc7..85b22c6 100644 --- a/docs/META_REPOSITORY_MIGRATION_AUDIT.md +++ b/docs/archive/2026-07/META_REPOSITORY_MIGRATION_AUDIT.md @@ -1,5 +1,9 @@ # Meta Repository Migration Audit +> **Archived migration record:** The ownership migration described here is +> complete. Current boundaries are defined by Repository Structure, module +> manifests, and the owning repositories. + This audit records which existing GovOPlaN files should move toward the `govoplan` meta repository and which should remain with their current runtime owner. @@ -148,7 +152,7 @@ It should not own: Known references reviewed after the server-side rename: - `govoplan/repositories.json` -- `govoplan/docs/REPOSITORY_STRUCTURE.md` +- `govoplan/docs/project/REPOSITORY_STRUCTURE.md` - `govoplan/docker/README.md` - `govoplan-core/docs/RELEASE_DEPENDENCIES.md` - `govoplan-core/docs/MODULE_ARCHITECTURE.md` diff --git a/docs/META_REPO_SCAN.md b/docs/archive/2026-07/META_REPO_SCAN.md similarity index 92% rename from docs/META_REPO_SCAN.md rename to docs/archive/2026-07/META_REPO_SCAN.md index bcf2f0d..e3ca460 100644 --- a/docs/META_REPO_SCAN.md +++ b/docs/archive/2026-07/META_REPO_SCAN.md @@ -1,5 +1,8 @@ # Meta Repository Scan +> **Archived assessment:** This file records the 2026-07-13 repository state. +> Use `repositories.json` and the current documentation map for present state. + Scan date: 2026-07-13. This scan checked local repositories under `/mnt/DATA/git` listed in @@ -13,7 +16,7 @@ Checked-out repositories not listed in `repositories.json`: none. Repositories listed in `repositories.json` but not checked out locally: none. -The human-readable link index is `docs/REPOSITORY_INDEX.md`; the JSON file +The human-readable link index is `docs/project/REPOSITORY_INDEX.md`; the JSON file remains the machine-readable source of truth. ## Meta-Owned Content diff --git a/docs/STRATEGIC_REVIEW_2026-08-05.md b/docs/archive/2026-08/STRATEGIC_REVIEW_2026-08-05.md similarity index 94% rename from docs/STRATEGIC_REVIEW_2026-08-05.md rename to docs/archive/2026-08/STRATEGIC_REVIEW_2026-08-05.md index fb9790a..0ea2529 100644 --- a/docs/STRATEGIC_REVIEW_2026-08-05.md +++ b/docs/archive/2026-08/STRATEGIC_REVIEW_2026-08-05.md @@ -1,5 +1,8 @@ # Strategic Review - 2026-08-05 +> **Archived assessment:** This review explains the 2026-08-05 strategy reset. +> It is not updated with later implementation or portfolio state. + ## Assessment GovOPlaN has not lost its central direction. The architecture now expresses a @@ -9,8 +12,8 @@ need is convergence: fewer simultaneous fronts, stronger cross-cutting adoption, and end-to-end reference journeys that non-developers can complete. This is a dated review. Current status belongs in -[Strategy Status](STRATEGY_STATUS.md); stable direction belongs in -[Platform Core Ideas](PLATFORM_CORE_IDEAS.md). +[Strategy Status](../../strategy/STRATEGY_STATUS.md); stable direction belongs in +[Platform Core Ideas](../../strategy/PLATFORM_CORE_IDEAS.md). ## What Is Already Strong @@ -58,7 +61,7 @@ already reduce navigation and the complete technical rail remains useful for power users. The correction is configurable product areas, task-focused Views and a bounded Quick Access rail, while preserving deliberate access to every authorized tool and technical provenance. The accepted design is maintained in -[Quick Access And Product Areas](QUICK_ACCESS_AND_PRODUCT_AREAS.md). +[Quick Access And Product Areas](../../architecture/QUICK_ACCESS_AND_PRODUCT_AREAS.md). ### Status became duplicated diff --git a/docs/CAPABILITY_AND_INFRASTRUCTURE_FIT.md b/docs/evidence/snapshots/CAPABILITY_AND_INFRASTRUCTURE_FIT.md similarity index 97% rename from docs/CAPABILITY_AND_INFRASTRUCTURE_FIT.md rename to docs/evidence/snapshots/CAPABILITY_AND_INFRASTRUCTURE_FIT.md index 835330f..0379628 100644 --- a/docs/CAPABILITY_AND_INFRASTRUCTURE_FIT.md +++ b/docs/evidence/snapshots/CAPABILITY_AND_INFRASTRUCTURE_FIT.md @@ -2,7 +2,7 @@ > **Pinned historical evidence:** This document assesses the exact 2026-07-22 > Campaign composition below. It is intentionally not updated to describe later -> main-branch work. Use [Strategy Status](STRATEGY_STATUS.md) for the current +> main-branch work. Use [Strategy Status](../../strategy/STRATEGY_STATUS.md) for the current > cross-product reconciliation and create a new dated fit assessment for a new > target composition. @@ -17,16 +17,16 @@ | Configuration basis | Root `.env.example` and the production-like development profile | | Scope | Campaign-centric internal pilot and small-production candidate | | Explicitly postponed | Workflow and workflow-driven user stories | -| Machine-readable companion | [`capability-fit-current.json`](capability-fit-current.json) | -| Input schema | [`capability-fit.schema.json`](capability-fit.schema.json) | +| Machine-readable companion | [`capability-fit-current.json`](../../capability-fit-current.json) | +| Input schema | [`capability-fit.schema.json`](../../capability-fit.schema.json) | **Snapshot notice:** this assessment remains valid only for the pinned 2026-07-22 composition above. Workflow Engine, the optional Workflow editor, Datasources, Dataflow, Search, encryption contracts, and other later main-branch work must not be inferred into this evidence record. The current product direction and implemented-state reconciliation are documented separately in -the [Institutional Governance Target Architecture](INSTITUTIONAL_GOVERNANCE_TARGET_ARCHITECTURE.md) -and [Strategy Status](STRATEGY_STATUS.md). +the [Institutional Governance Target Architecture](../../architecture/INSTITUTIONAL_GOVERNANCE_TARGET_ARCHITECTURE.md) +and [Strategy Status](../../strategy/STRATEGY_STATUS.md). This is a fit assessment, not a production approval or security certification. It deliberately does not infer implementation from a repository, issue, or @@ -404,7 +404,7 @@ that observation to the assessment and signed catalog: ``` The collector follows the strict version `0.4.0` -[`installed-composition-evidence.schema.json`](installed-composition-evidence.schema.json) +[`installed-composition-evidence.schema.json`](../../installed-composition-evidence.schema.json) contract. It enumerates all installed distributions whose normalized name starts with `govoplan-`, compares the enabled assessed package and module-manifest versions, and identifies missing, duplicate and extra GovOPlaN distributions. @@ -487,14 +487,14 @@ unchecked boundary. Installed evidence cannot establish target acceptance, accessibility, privacy, security, operations, recovery, an external provider, or production use. These scopes use a separate, expiring -[`capability-fit-boundary-evidence.schema.json`](capability-fit-boundary-evidence.schema.json) +[`capability-fit-boundary-evidence.schema.json`](../../capability-fit-boundary-evidence.schema.json) bundle. The bundle is bound to the assessment ID, assessment release and exact installed-evidence SHA-256 digest. It contains only opaque subject/control/result IDs and content hashes, not endpoints, credentials, people or raw result files. Boundary evidence is accepted only when at least one Ed25519 signature validates against a separately provisioned -[`capability-fit-proof-authority-keyring.schema.json`](capability-fit-proof-authority-keyring.schema.json). +[`capability-fit-proof-authority-keyring.schema.json`](../../capability-fit-proof-authority-keyring.schema.json). Each authority key explicitly lists the scopes it may attest. Target, accessibility, privacy, security, operations, recovery, and provider claims use `passed` or `failed`; production claims use `approved` or `rejected`. @@ -511,7 +511,7 @@ the tool's deterministic canonicalization. `tools/assessments/boundary-evidence.py` is the bounded issuance path. It accepts a private target-run manifest conforming to -[`capability-fit-boundary-run.schema.json`](capability-fit-boundary-run.schema.json), +[`capability-fit-boundary-run.schema.json`](../../capability-fit-boundary-run.schema.json), hashes each retained result file without following a final-component symlink, and excludes all paths and raw results from the signed receipt. Issuance is refused unless an independently trusted catalog, exact installed payload, @@ -521,7 +521,7 @@ is authorized for the full proof interval; catalog and installer key reuse is rejected. The command immediately verifies its own result and atomically writes both the proof and a sanitized review. The complete operator procedure and recovery measurement definition are in -[`TARGET_MATURITY_EVIDENCE_RUNBOOK.md`](TARGET_MATURITY_EVIDENCE_RUNBOOK.md). +[`TARGET_MATURITY_EVIDENCE_RUNBOOK.md`](../../operations/TARGET_MATURITY_EVIDENCE_RUNBOOK.md). ```bash ./.venv/bin/python tools/assessments/capability-fit.py \ @@ -599,7 +599,7 @@ separate from production approval and from provider-specific acceptance. Both authority keyrings are governance trust roots. Installer receipt keys use the strict -[`installer-receipt-authority-keyring.schema.json`](installer-receipt-authority-keyring.schema.json) +[`installer-receipt-authority-keyring.schema.json`](../../installer-receipt-authority-keyring.schema.json) contract and may attest only `installed_release_origin`; their public material must not be reused by catalog or boundary-proof authorities. Do not download or generate them from the proof bundle being checked. The checker rejects @@ -623,9 +623,9 @@ journey, source tests, or signed release metadata. ## Evidence used in this slice -- [Production-like profile](../dev/production-like/README.md) and - [Compose dependencies](../dev/production-like/docker-compose.yml) -- [Module contracts and install boundaries](MODULE_CONTRACTS_AND_INSTALLS.md) +- [Production-like profile](../../../dev/production-like/README.md) and + [Compose dependencies](../../../dev/production-like/docker-compose.yml) +- [Module contracts and install boundaries](../../operations/MODULE_CONTRACTS_AND_INSTALLS.md) - [Core deployment operator guide](https://git.add-ideas.de/GovOPlaN/govoplan-core/src/branch/main/docs/DEPLOYMENT_OPERATOR_GUIDE.md) - [Ops scalability profiles](https://git.add-ideas.de/GovOPlaN/govoplan-ops/src/branch/main/docs/SCALABILITY_PROFILES.md) - Actual module manifests in the pinned repositories and the static contract diff --git a/docs/INTERFACE_SURFACE_INVENTORY.md b/docs/evidence/snapshots/INTERFACE_SURFACE_INVENTORY.md similarity index 98% rename from docs/INTERFACE_SURFACE_INVENTORY.md rename to docs/evidence/snapshots/INTERFACE_SURFACE_INVENTORY.md index 1525cd9..b7333b1 100644 --- a/docs/INTERFACE_SURFACE_INVENTORY.md +++ b/docs/evidence/snapshots/INTERFACE_SURFACE_INVENTORY.md @@ -1,19 +1,24 @@ # GovOPlaN Interface Surface Inventory And Rollout +> **Pinned snapshot:** This inventory records the source-derived state reviewed +> on 2026-08-03. It is retained as evidence, not maintained as the current +> rollout ledger. Generate a new inventory and use Gitea issues for current +> implementation state. + This is the initial evidence inventory for the product-wide interface pattern language. It records code contributions, not an assertion that every listed surface is complete, enabled in a deployment, usable, or compliant. The applicable design contract is -[`INTERFACE_PATTERN_LANGUAGE.md`](INTERFACE_PATTERN_LANGUAGE.md). +[`INTERFACE_PATTERN_LANGUAGE.md`](../../architecture/INTERFACE_PATTERN_LANGUAGE.md). ## Snapshot And Method The source-derived inventory command is documented in -[`PLATFORM_CONTROL_PLANE.md`](PLATFORM_CONTROL_PLANE.md). It produces +[`PLATFORM_CONTROL_PLANE.md`](../../architecture/PLATFORM_CONTROL_PLANE.md). It produces machine-readable field, label, translation, route, API-reference, and module -manifest evidence. This hand-maintained document remains the reviewed product -interpretation and rollout ledger; generated evidence does not replace it. +manifest evidence. This hand-maintained document is the reviewed interpretation +of that snapshot; generated evidence does not retroactively change it. Snapshot refreshed: 2026-08-03. diff --git a/docs/BACKUP_AND_RESTORE_EVIDENCE.md b/docs/operations/BACKUP_AND_RESTORE_EVIDENCE.md similarity index 97% rename from docs/BACKUP_AND_RESTORE_EVIDENCE.md rename to docs/operations/BACKUP_AND_RESTORE_EVIDENCE.md index 7ddeae3..71da01c 100644 --- a/docs/BACKUP_AND_RESTORE_EVIDENCE.md +++ b/docs/operations/BACKUP_AND_RESTORE_EVIDENCE.md @@ -16,8 +16,8 @@ deployment/evidence boundary. The machine-readable contracts are: -- [`backup-evidence.schema.json`](backup-evidence.schema.json); -- [`backup-evidence-keyring.schema.json`](backup-evidence-keyring.schema.json). +- [`backup-evidence.schema.json`](../backup-evidence.schema.json); +- [`backup-evidence-keyring.schema.json`](../backup-evidence-keyring.schema.json). One evidence document is bound to the installation id, deployment profile, topology subject, exact signed release manifest, image digests, and composition diff --git a/docs/DEPLOYMENT_PROFILES.md b/docs/operations/DEPLOYMENT_PROFILES.md similarity index 100% rename from docs/DEPLOYMENT_PROFILES.md rename to docs/operations/DEPLOYMENT_PROFILES.md diff --git a/docs/INSTALLATION_AND_DEPLOYMENT_ARCHITECTURE.md b/docs/operations/INSTALLATION_AND_DEPLOYMENT_ARCHITECTURE.md similarity index 98% rename from docs/INSTALLATION_AND_DEPLOYMENT_ARCHITECTURE.md rename to docs/operations/INSTALLATION_AND_DEPLOYMENT_ARCHITECTURE.md index cd45a9a..28c65c4 100644 --- a/docs/INSTALLATION_AND_DEPLOYMENT_ARCHITECTURE.md +++ b/docs/operations/INSTALLATION_AND_DEPLOYMENT_ARCHITECTURE.md @@ -8,7 +8,7 @@ receives a working base system. Re-running the same tool repairs or reconfigures that installation instead of creating unrelated state. The canonical product journey remains -[System Administrator Lifecycle User Story](SYSTEM_ADMINISTRATOR_LIFECYCLE_USER_STORY.md). +[System Administrator Lifecycle User Story](../strategy/SYSTEM_ADMINISTRATOR_LIFECYCLE_USER_STORY.md). This document defines the deployer boundary and the first executable slice. The execution, topology, component-ownership and assurance modes are defined canonically in [Deployment Profiles](DEPLOYMENT_PROFILES.md). In particular, @@ -111,7 +111,7 @@ The private installation directory contains: | `.deployment.lock` | Same-host operation exclusion | The specification contract is -[`installation-spec.schema.json`](installation-spec.schema.json). +[`installation-spec.schema.json`](../installation-spec.schema.json). The API, workers, scheduler, and Ops read the capability receipt through the same bounded Core validator. Configuration-package providers receive that typed @@ -210,9 +210,9 @@ it can initialize a new volume; the actual HAProxy process retains the image's non-root identity and runs read-only with all capabilities dropped. The manifest contract is -[`runtime-distribution-manifest.schema.json`](runtime-distribution-manifest.schema.json), +[`runtime-distribution-manifest.schema.json`](../runtime-distribution-manifest.schema.json), and its separately distributed trust-anchor contract is -[`runtime-distribution-keyring.schema.json`](runtime-distribution-keyring.schema.json). +[`runtime-distribution-keyring.schema.json`](../runtime-distribution-keyring.schema.json). Publication is immutable: an existing Gitea release asset must have the same size and SHA-256 digest or publication fails. diff --git a/docs/KUBERNETES_TEST_LAB.md b/docs/operations/KUBERNETES_TEST_LAB.md similarity index 100% rename from docs/KUBERNETES_TEST_LAB.md rename to docs/operations/KUBERNETES_TEST_LAB.md diff --git a/docs/MODULE_CONTRACTS_AND_INSTALLS.md b/docs/operations/MODULE_CONTRACTS_AND_INSTALLS.md similarity index 100% rename from docs/MODULE_CONTRACTS_AND_INSTALLS.md rename to docs/operations/MODULE_CONTRACTS_AND_INSTALLS.md diff --git a/docs/PACKAGE_REGISTRY_RELEASES.md b/docs/operations/PACKAGE_REGISTRY_RELEASES.md similarity index 100% rename from docs/PACKAGE_REGISTRY_RELEASES.md rename to docs/operations/PACKAGE_REGISTRY_RELEASES.md diff --git a/docs/PRODUCTION_TARGET_HANDOFF.md b/docs/operations/PRODUCTION_TARGET_HANDOFF.md similarity index 100% rename from docs/PRODUCTION_TARGET_HANDOFF.md rename to docs/operations/PRODUCTION_TARGET_HANDOFF.md diff --git a/docs/RECOVERY_AND_ROLLBACK_GUARANTEES.md b/docs/operations/RECOVERY_AND_ROLLBACK_GUARANTEES.md similarity index 100% rename from docs/RECOVERY_AND_ROLLBACK_GUARANTEES.md rename to docs/operations/RECOVERY_AND_ROLLBACK_GUARANTEES.md diff --git a/docs/RECOVERY_LEDGER_ADOPTION.md b/docs/operations/RECOVERY_LEDGER_ADOPTION.md similarity index 98% rename from docs/RECOVERY_LEDGER_ADOPTION.md rename to docs/operations/RECOVERY_LEDGER_ADOPTION.md index 9b2b0f7..2c95d0f 100644 --- a/docs/RECOVERY_LEDGER_ADOPTION.md +++ b/docs/operations/RECOVERY_LEDGER_ADOPTION.md @@ -2,7 +2,7 @@ The Core recovery ledger is a platform primitive, not automatic protection for module-owned effects. The canonical, machine-checked inventory is -[`recovery-operation-inventory.json`](recovery-operation-inventory.json). +[`recovery-operation-inventory.json`](../recovery-operation-inventory.json). ## Classification Rules diff --git a/docs/RELEASE_CONSOLE.md b/docs/operations/RELEASE_CONSOLE.md similarity index 100% rename from docs/RELEASE_CONSOLE.md rename to docs/operations/RELEASE_CONSOLE.md diff --git a/docs/SCALING_AND_MULTI_HOST_DEPLOYMENT.md b/docs/operations/SCALING_AND_MULTI_HOST_DEPLOYMENT.md similarity index 99% rename from docs/SCALING_AND_MULTI_HOST_DEPLOYMENT.md rename to docs/operations/SCALING_AND_MULTI_HOST_DEPLOYMENT.md index 095fcc4..d4ca543 100644 --- a/docs/SCALING_AND_MULTI_HOST_DEPLOYMENT.md +++ b/docs/operations/SCALING_AND_MULTI_HOST_DEPLOYMENT.md @@ -277,4 +277,4 @@ test against the target ingress controller and network implementation. This proves the bounded stateless-node-loss slice only. Session continuity, accepted-job redelivery, state-service failover, and coordinated restore remain separate target exercises whose signed evidence is governed by -`docs/TARGET_MATURITY_EVIDENCE_RUNBOOK.md` and GovOPlaN #37. +`docs/operations/TARGET_MATURITY_EVIDENCE_RUNBOOK.md` and GovOPlaN #37. diff --git a/docs/SECURITY_AUDIT.md b/docs/operations/SECURITY_AUDIT.md similarity index 100% rename from docs/SECURITY_AUDIT.md rename to docs/operations/SECURITY_AUDIT.md diff --git a/docs/TARGET_MATURITY_EVIDENCE_RUNBOOK.md b/docs/operations/TARGET_MATURITY_EVIDENCE_RUNBOOK.md similarity index 100% rename from docs/TARGET_MATURITY_EVIDENCE_RUNBOOK.md rename to docs/operations/TARGET_MATURITY_EVIDENCE_RUNBOOK.md diff --git a/docs/GITEA_ISSUES.md b/docs/project/GITEA_ISSUES.md similarity index 100% rename from docs/GITEA_ISSUES.md rename to docs/project/GITEA_ISSUES.md diff --git a/docs/REPOSITORY_INDEX.md b/docs/project/REPOSITORY_INDEX.md similarity index 100% rename from docs/REPOSITORY_INDEX.md rename to docs/project/REPOSITORY_INDEX.md diff --git a/docs/REPOSITORY_STRUCTURE.md b/docs/project/REPOSITORY_STRUCTURE.md similarity index 98% rename from docs/REPOSITORY_STRUCTURE.md rename to docs/project/REPOSITORY_STRUCTURE.md index 251f090..9511f40 100644 --- a/docs/REPOSITORY_STRUCTURE.md +++ b/docs/project/REPOSITORY_STRUCTURE.md @@ -79,7 +79,7 @@ development depend on submodule updates. Module release tags also publish wheels and WebUI tarballs to the organization PyPI/npm registries. The meta release resolves exact versions into a hash-bound package lock before producing the signed OCI runtime. See -`docs/PACKAGE_REGISTRY_RELEASES.md`. Git tags remain source provenance; package +`docs/operations/PACKAGE_REGISTRY_RELEASES.md`. Git tags remain source provenance; package registries are reusable artifact transport; the signed runtime manifest and digest-pinned images remain production authority. diff --git a/docs/PLATFORM_CORE_IDEAS.md b/docs/strategy/PLATFORM_CORE_IDEAS.md similarity index 100% rename from docs/PLATFORM_CORE_IDEAS.md rename to docs/strategy/PLATFORM_CORE_IDEAS.md diff --git a/docs/PRODUCT_INPUT_REGISTER.md b/docs/strategy/PRODUCT_INPUT_REGISTER.md similarity index 99% rename from docs/PRODUCT_INPUT_REGISTER.md rename to docs/strategy/PRODUCT_INPUT_REGISTER.md index eb3b836..7624bf1 100644 --- a/docs/PRODUCT_INPUT_REGISTER.md +++ b/docs/strategy/PRODUCT_INPUT_REGISTER.md @@ -6,7 +6,7 @@ This document preserves and normalizes product ideas and user-story notes that inform GovOPlaN without turning a private note file into a second backlog. Gitea issues remain the source of live work state; the stable platform direction remains in [Platform Core Ideas](PLATFORM_CORE_IDEAS.md), the -[Connected Governance Platform Roadmap](CONNECTED_GOVERNANCE_PLATFORM_ROADMAP.md), +[Connected Governance Platform Roadmap](reference/CONNECTED_GOVERNANCE_PLATFORM_ROADMAP.md), and the [Reference Journey Program](REFERENCE_JOURNEY_PROGRAM.md). The register was reconciled on 2026-08-06 from: diff --git a/docs/REFERENCE_JOURNEY_PROGRAM.md b/docs/strategy/REFERENCE_JOURNEY_PROGRAM.md similarity index 99% rename from docs/REFERENCE_JOURNEY_PROGRAM.md rename to docs/strategy/REFERENCE_JOURNEY_PROGRAM.md index 600ef05..004bf65 100644 --- a/docs/REFERENCE_JOURNEY_PROGRAM.md +++ b/docs/strategy/REFERENCE_JOURNEY_PROGRAM.md @@ -11,7 +11,7 @@ is not an automatic dependency of every journey. The institutional semantics and source-authority model applied to these stages are defined in the -[Institutional Governance Target Architecture](INSTITUTIONAL_GOVERNANCE_TARGET_ARCHITECTURE.md). +[Institutional Governance Target Architecture](../architecture/INSTITUTIONAL_GOVERNANCE_TARGET_ARCHITECTURE.md). The stages are ordered, but they are not monolithic releases. Each stage is delivered as small, reviewable, green increments and is complete only when its diff --git a/docs/strategy/ROADMAP.md b/docs/strategy/ROADMAP.md new file mode 100644 index 0000000..60c399e --- /dev/null +++ b/docs/strategy/ROADMAP.md @@ -0,0 +1,100 @@ +# GovOPlaN Roadmap + +## Purpose + +GovOPlaN should become the connective, governance-aware operating layer of an +institution: people complete services and work without learning the module +graph, while the institution can explain authority, policy, source data, +effects, evidence, and recovery. + +This is the concise product roadmap. It states durable outcomes and sequence, +not release dates or issue state. Use [Strategy Status](STRATEGY_STATUS.md) for +the current reconciliation and Gitea issues for active work. The +[detailed connected-platform vision](reference/CONNECTED_GOVERNANCE_PLATFORM_ROADMAP.md) +retains stakeholder perspectives, configuration archetypes, and the complete +outcome-story catalogue. + +## Product Promise + +GovOPlaN will: + +1. model institutional context, responsibility, authority, and time; +2. turn incoming information into owned, reviewable human and machine work; +3. connect native and external systems without obscuring the source of truth; +4. preserve decisions, effects, records, corrections, and recovery evidence; +5. support digital, assisted, paper, message, calendar, and system channels as + paths through the same governed work; and +6. package successful configurations so institutions can adopt them without + code forks or loss of local autonomy. + +It will not replace every specialist system, copy all data into one master +database, infer authority from membership, or claim production maturity from +repository breadth. + +## Outcome Horizons + +| Horizon | Outcome | Completion evidence | +| --- | --- | --- | +| Trustworthy baseline | A pinned composition can be installed, upgraded, operated, explained, and recovered. | Signed artifacts, clean install/upgrade, provider failure tests, restore drill, coherent UI, and target evidence | +| Connected work | Intake becomes accountable work with context, assignment, review, communication, and evidence. | One digital and assisted service reaches a decision and eAkte without losing responsibility or state | +| Reusable products | Complete service, communication, and data outcomes ship as governed configuration packages. | Two materially different deployments adapt packages without code forks | +| Institutional assurance | Records, transparency, privacy, risk, regulated review, and reporting connect to real operations. | A consequential decision can be reconstructed, corrected, retained, and disclosed under policy | +| Federated ecosystem | Autonomous installations exchange signed data and configuration across explicit trust boundaries. | Paired-instance exchange, reconciliation, supported deployment profiles, and independent evidence | + +## Current Sequence + +The sequence is outcome-led. Shared foundation work enters when one of these +proofs needs it. + +1. **Enforce the platform quality contract.** German is the reference locale; + help, accessibility, temporal browsing, purpose-aware access, retention, + institutional context, optional-module combinations, and recovery behavior + become measurable release gates. +2. **Complete governed communication.** Prove recipient selection, Campaign, + Files, Mail, function-bound Postbox delivery, acknowledgement, uncertain + outcomes, correction, filing, and recovery against a named target. +3. **Complete the monthly-data and sanctions journey.** Acquire immutable + source snapshots, validate and reconcile data interactively, preserve + lineage and review, publish reports and files, and deliver accepted results. +4. **Complete inclusive service to decision.** Accept digital or assisted + input, establish actor and purpose, persist human handoffs, decide, notify, + and reconstruct the exact eAkte under current authorization. +5. **Complete discovery and external coexistence.** Finish native PostgreSQL + search coverage, prove reauthorization and reindexing, then prove one + external product connector and one paired GovOPlaN federation exchange. +6. **Prove production operation.** Complete multi-host, provider, restore, + accessibility, volume, key-custody, and independently signed target + evidence before raising maturity claims. + +## Continuous Foundation + +Every journey applies the same boundaries: + +- modules cooperate through versioned Core contracts and typed references; +- permissions, policy, institutional context, purpose, and current authority + are evaluated before presenting or acting on data; +- requested actions, durable intent, observed effects, unknown outcomes, + retries, reconciliation, and correction remain distinct; +- Workflow Engine coordinates stable module-owned actions and human handoffs; + it does not become a second owner of domain state; +- Files owns managed bytes, Records owns institutional filing and retention, + and source systems retain explicitly declared authority; +- focused views and product areas reduce interface complexity without granting + access or hiding material consequences; +- configuration packages include terminology, forms, policies, workflows, + views, reports, providers, documentation, migration, and evidence; and +- maturity advances from scaffold to vertical slice, reference-ready, + supported, and LTS only with evidence appropriate to each claim. + +## Decision Rule + +A roadmap item should answer all of the following before implementation: + +1. Which real journey and actor outcome does it improve? +2. Which module or external system owns each object and source of truth? +3. Which institutional, temporal, purpose, and policy context applies? +4. Which effects, evidence, retention, failure, and recovery states result? +5. Which package and target evidence will prove the outcome? + +If those answers are missing, retain the idea in the Product Input Register or +Gitea discovery work rather than opening an unbounded implementation program. diff --git a/docs/STRATEGY_STATUS.md b/docs/strategy/STRATEGY_STATUS.md similarity index 98% rename from docs/STRATEGY_STATUS.md rename to docs/strategy/STRATEGY_STATUS.md index 63b18dc..31301b7 100644 --- a/docs/STRATEGY_STATUS.md +++ b/docs/strategy/STRATEGY_STATUS.md @@ -6,7 +6,7 @@ | --- | --- | | Reconciled on | 2026-08-06 | | Source scope | Local workspace manifests, source inventory, focused journey checks, signed release evidence, and live Gitea issue state | -| Stable direction | [Platform Core Ideas](PLATFORM_CORE_IDEAS.md) and [Connected Governance Platform Roadmap](CONNECTED_GOVERNANCE_PLATFORM_ROADMAP.md) | +| Stable direction | [Platform Core Ideas](PLATFORM_CORE_IDEAS.md) and [Roadmap](ROADMAP.md) | | Collected product input | [Product Input Register](PRODUCT_INPUT_REGISTER.md) | | Delivery source | Gitea issues | diff --git a/docs/SYSTEM_ADMINISTRATOR_LIFECYCLE_USER_STORY.md b/docs/strategy/SYSTEM_ADMINISTRATOR_LIFECYCLE_USER_STORY.md similarity index 100% rename from docs/SYSTEM_ADMINISTRATOR_LIFECYCLE_USER_STORY.md rename to docs/strategy/SYSTEM_ADMINISTRATOR_LIFECYCLE_USER_STORY.md diff --git a/docs/CONNECTED_GOVERNANCE_PLATFORM_ROADMAP.md b/docs/strategy/reference/CONNECTED_GOVERNANCE_PLATFORM_ROADMAP.md similarity index 97% rename from docs/CONNECTED_GOVERNANCE_PLATFORM_ROADMAP.md rename to docs/strategy/reference/CONNECTED_GOVERNANCE_PLATFORM_ROADMAP.md index d17dd55..7da1f05 100644 --- a/docs/CONNECTED_GOVERNANCE_PLATFORM_ROADMAP.md +++ b/docs/strategy/reference/CONNECTED_GOVERNANCE_PLATFORM_ROADMAP.md @@ -1,30 +1,32 @@ -# GovOPlaN Connected Governance Platform Roadmap +# GovOPlaN Detailed Connected-Platform Vision ## Purpose and status -This document describes the long-term product destination for GovOPlaN from an -outcome and stakeholder perspective. It answers what a completely connected -governance platform should enable, how the same platform can be configured for -different institutions, and which capability horizons lead from the current -baseline to that destination. +This reference catalogue describes the long-term product destination from an +outcome and stakeholder perspective. It preserves the detailed perspectives, +configuration archetypes, stories, horizons, and maturity notes behind the +concise [Roadmap](../ROADMAP.md). -It is a durable direction, not a release promise or a substitute for issue -tracking. Live work state belongs in Gitea issues. The +It is not a release promise, live plan, or second status source. The concise +roadmap owns the current durable sequence, Strategy Status owns the reconciled +state, and Gitea issues own work state. Where dated detail here differs from +those sources, those sources take precedence. The [Core master roadmap](https://git.add-ideas.de/GovOPlaN/govoplan-core/src/branch/main/docs/GOVOPLAN_MASTER_ROADMAP.md) remains the technical module and wave sequence; this document supplies the cross-product vision that sequence serves. Read it together with: -- the [institutional governance target architecture](INSTITUTIONAL_GOVERNANCE_TARGET_ARCHITECTURE.md) -- the [selected reference-journey program](REFERENCE_JOURNEY_PROGRAM.md) -- the [current strategy status](STRATEGY_STATUS.md) -- the [pinned Campaign capability and infrastructure fit assessment](CAPABILITY_AND_INFRASTRUCTURE_FIT.md) -- the [interface pattern language](INTERFACE_PATTERN_LANGUAGE.md) -- the [interface surface inventory](INTERFACE_SURFACE_INVENTORY.md) -- the [module contract and install model](MODULE_CONTRACTS_AND_INSTALLS.md) -- the [repository and module index](REPOSITORY_INDEX.md) -- the [Gitea issue workflow](GITEA_ISSUES.md) +- the [concise product roadmap](../ROADMAP.md) +- the [institutional governance target architecture](../../architecture/INSTITUTIONAL_GOVERNANCE_TARGET_ARCHITECTURE.md) +- the [selected reference-journey program](../REFERENCE_JOURNEY_PROGRAM.md) +- the [current strategy status](../STRATEGY_STATUS.md) +- the [pinned Campaign capability and infrastructure fit assessment](../../evidence/snapshots/CAPABILITY_AND_INFRASTRUCTURE_FIT.md) +- the [interface pattern language](../../architecture/INTERFACE_PATTERN_LANGUAGE.md) +- the [interface surface inventory](../../evidence/snapshots/INTERFACE_SURFACE_INVENTORY.md) +- the [module contract and install model](../../operations/MODULE_CONTRACTS_AND_INSTALLS.md) +- the [repository and module index](../../project/REPOSITORY_INDEX.md) +- the [Gitea issue workflow](../../project/GITEA_ISSUES.md) ### How to read this roadmap @@ -42,14 +44,15 @@ Read it together with: - Use [Near-term portfolio order](#near-term-portfolio-order) for the bridge to implementation and [Product decisions](#product-decisions-to-make-progressively) for choices that can remain deferred. -- Use the [dated strategic review](STRATEGIC_REVIEW_2026-08-05.md) to understand +- Use the [dated strategic review](../../archive/2026-08/STRATEGIC_REVIEW_2026-08-05.md) to understand why the current convergence and reference-journey order was chosen. ### Planning ownership | Question | Canonical source | | --- | --- | -| What product should GovOPlaN become, for whom, in which configurations, and through which outcome horizons? | This meta roadmap | +| What product should GovOPlaN become and in which durable sequence? | The concise Roadmap | +| Which stakeholder perspectives, configuration archetypes, and detailed outcome stories inform that direction? | This reference catalogue | | Which module owns a capability, which technical wave should deliver it, and what implementation gates apply? | The Core master roadmap and owning-module concepts | | What is actively planned, blocked, implemented, or closed now? | Gitea issues and the dated reconciliation in `STRATEGY_STATUS.md` | | What can a named composition credibly claim in a target environment? | A dated capability/infrastructure fit assessment | @@ -110,7 +113,7 @@ safe modules -> connected work -> reusable services -> institutional assurance - ``` The active implementation path is the -[Reference Journey Program](REFERENCE_JOURNEY_PROGRAM.md), selected on +[Reference Journey Program](../REFERENCE_JOURNEY_PROGRAM.md), selected on 2026-07-21. Its five stages do not replace these product horizons: they are the ordered demonstrations through which the shared platform contracts and horizon gates are to be proved. Connector safety, identity/function semantics, @@ -266,7 +269,7 @@ Diagnostics minimize personal data and link to governed evidence when deeper inspection is authorized. The complete installation and lifecycle journey is specified in the -[System Administrator Lifecycle User Story](SYSTEM_ADMINISTRATOR_LIFECYCLE_USER_STORY.md): +[System Administrator Lifecycle User Story](../SYSTEM_ADMINISTRATOR_LIFECYCLE_USER_STORY.md): one-command Core-baseline bootstrap, signed online module installation and updates, stateless scale-out, versioned configuration transfer, undo, and reproducible environment-promotion recipes. @@ -950,7 +953,7 @@ first analytical product prove Horizons 2 and 3; governed BI adds assurance and ecosystem capabilities across Horizons 3–5; collaborative documents combine the evidence spine, service packages, and records assurance across Horizons 2–4. The detailed mapping and gates are in the -[Reference Journey Program](REFERENCE_JOURNEY_PROGRAM.md). +[Reference Journey Program](../REFERENCE_JOURNEY_PROGRAM.md). ### Current baseline: modular pilot foundations @@ -976,7 +979,7 @@ checkouts. Priorities: 1. Deliver the first slices of the - [System Administrator Lifecycle User Story](SYSTEM_ADMINISTRATOR_LIFECYCLE_USER_STORY.md): + [System Administrator Lifecycle User Story](../SYSTEM_ADMINISTRATOR_LIFECYCLE_USER_STORY.md): a verified full-package distribution with only the Core baseline active, first-run control plane, read-only online module directory, and durable plan/confirm/install progress. @@ -1220,7 +1223,7 @@ provides all applicable evidence below. ## Near-term portfolio order This order is now selected. Detailed slices and gates are in the -[Reference Journey Program](REFERENCE_JOURNEY_PROGRAM.md). Workflow Engine and +[Reference Journey Program](../REFERENCE_JOURNEY_PROGRAM.md). Workflow Engine and the optional editor may support these stages, but Workflow work enters the portfolio only through an explicit bounded package or reference journey. @@ -1357,6 +1360,6 @@ evidence remains—and the product can prove that explanation at runtime. The volatile release and backlog appendix that originally accompanied this roadmap has been removed so the durable direction cannot become a competing -status source. The [Strategic Review 2026-08-05](STRATEGIC_REVIEW_2026-08-05.md) +status source. The [Strategic Review 2026-08-05](../../archive/2026-08/STRATEGIC_REVIEW_2026-08-05.md) retains the dated assessment and reasoning. Current reconciliation belongs in -[Strategy Status](STRATEGY_STATUS.md), and live work state belongs in Gitea. +[Strategy Status](../STRATEGY_STATUS.md), and live work state belongs in Gitea. diff --git a/tests/test_documentation_structure.py b/tests/test_documentation_structure.py new file mode 100644 index 0000000..0bd45c3 --- /dev/null +++ b/tests/test_documentation_structure.py @@ -0,0 +1,61 @@ +from __future__ import annotations + +import re +import unittest +from pathlib import Path + + +ROOT = Path(__file__).resolve().parents[1] +DOCS = ROOT / "docs" +MARKDOWN_LINK = re.compile( + r"!?\[[^\n]*?\]\((?P<[^>]+>|[^)\s]+)" +) + + +class DocumentationStructureTests(unittest.TestCase): + def test_documentation_root_has_one_human_entry_point(self) -> None: + self.assertEqual( + [path.name for path in sorted(DOCS.glob("*.md"))], + ["README.md"], + ) + + def test_documentation_front_doors_exist(self) -> None: + expected = ( + DOCS / "strategy" / "PLATFORM_CORE_IDEAS.md", + DOCS / "strategy" / "ROADMAP.md", + DOCS / "strategy" / "STRATEGY_STATUS.md", + DOCS / "strategy" / "REFERENCE_JOURNEY_PROGRAM.md", + ) + self.assertFalse([path for path in expected if not path.is_file()]) + + def test_local_markdown_links_resolve(self) -> None: + broken: list[str] = [] + sources = [ROOT / "README.md", *sorted(DOCS.rglob("*.md"))] + for source in sources: + for line_number, line in enumerate( + source.read_text(encoding="utf-8").splitlines(), + start=1, + ): + for match in MARKDOWN_LINK.finditer(line): + destination = match.group("destination") + if destination.startswith("<") and destination.endswith(">"): + destination = destination[1:-1] + path_text = destination.split("#", 1)[0] + if ( + not path_text + or path_text.startswith(("/", "mailto:", "data:")) + or "://" in path_text + ): + continue + target = (source.parent / path_text).resolve() + if not target.is_relative_to(ROOT): + continue + if not target.exists(): + broken.append( + f"{source.relative_to(ROOT)}:{line_number}: {destination}" + ) + self.assertEqual(broken, []) + + +if __name__ == "__main__": + unittest.main() diff --git a/tests/test_release_catalog_entry_synthesis.py b/tests/test_release_catalog_entry_synthesis.py index 04b7e21..3e8037a 100644 --- a/tests/test_release_catalog_entry_synthesis.py +++ b/tests/test_release_catalog_entry_synthesis.py @@ -73,7 +73,7 @@ class ReleaseCatalogEntrySynthesisTests(unittest.TestCase): ), ModuleMaturityEvidence( kind="documentation", - reference="docs/INSTITUTIONAL_GOVERNANCE_TARGET_ARCHITECTURE.md", + reference="docs/architecture/INSTITUTIONAL_GOVERNANCE_TARGET_ARCHITECTURE.md", summary="Defines the provider declaration contract.", ), ), diff --git a/tools/gitea/gitea-import-all-backlogs.py b/tools/gitea/gitea-import-all-backlogs.py index 57cc167..de78325 100644 --- a/tools/gitea/gitea-import-all-backlogs.py +++ b/tools/gitea/gitea-import-all-backlogs.py @@ -247,7 +247,7 @@ def is_excluded_repo_file(path: pathlib.Path) -> bool: return True if "testing_plan" in name or "test_plan" in name: return True - if text.endswith("/docs/GITEA_ISSUES.md"): + if text.endswith(("/docs/GITEA_ISSUES.md", "/docs/project/GITEA_ISSUES.md")): return True if text.endswith("/docs/GOVOPLAN_MASTER_ROADMAP.md"): return True diff --git a/tools/gitea/gitea-todo-import.py b/tools/gitea/gitea-todo-import.py index 8454002..fb90a96 100644 --- a/tools/gitea/gitea-todo-import.py +++ b/tools/gitea/gitea-todo-import.py @@ -34,6 +34,7 @@ DEFAULT_EXCLUDES = ( "!**/.cache/**", "!.gitea/**", "!docs/GITEA_ISSUES.md", + "!docs/project/GITEA_ISSUES.md", "!tools/gitea/gitea-todo-import.py", "!tools/gitea/gitea-sync-labels.py", "!tools/gitea/gitea-codex-note.py",