docs: organize cross-product documentation
This commit is contained in:
@@ -0,0 +1,184 @@
|
||||
# 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.
|
||||
|
||||
## Website Repository Rename
|
||||
|
||||
The former `govoplan-web` repository has been renamed to
|
||||
`addideas-govoplan-website`. It is a public website and catalog publication
|
||||
target, not an installable GovOPlaN runtime module.
|
||||
|
||||
Resolved target name:
|
||||
|
||||
- `addideas-govoplan-website`
|
||||
|
||||
The rename happened server-side in Gitea first. Local checkout paths, remotes,
|
||||
docs, and release/catalog defaults should use the new name.
|
||||
|
||||
The renamed repository should remain categorized as `website`, not `module`.
|
||||
|
||||
## Move To `govoplan`
|
||||
|
||||
These are whole-product/operator concerns and should be owned by the meta
|
||||
repository.
|
||||
|
||||
### Release Orchestration
|
||||
|
||||
Former location:
|
||||
|
||||
- core-local release and catalog helper scripts
|
||||
|
||||
Target shape:
|
||||
|
||||
- command entry points live in `govoplan/tools`
|
||||
- repository lists come from `govoplan/repositories.json`
|
||||
- generated catalogs are written to the renamed public site repository
|
||||
- core keeps only runtime catalog validation/signing primitives used by the
|
||||
installer
|
||||
|
||||
### Cross-Repository Gitea Workflow Tooling
|
||||
|
||||
Former location:
|
||||
|
||||
- core-local Gitea helper scripts
|
||||
- source issue templates copied into each repo under `.gitea/`
|
||||
- the shared label taxonomy JSON file
|
||||
|
||||
Target shape:
|
||||
|
||||
- source templates and label taxonomy live in `govoplan`
|
||||
- sync/import/migration helpers live in `govoplan/tools`
|
||||
- generated/copy-installed `.gitea/` files may remain in each repository
|
||||
because Gitea reads them repository-locally
|
||||
- repo-specific AGENTS or issue guidance can remain repo-local when it contains
|
||||
module-specific instructions
|
||||
|
||||
### Whole-Product CI
|
||||
|
||||
Former location:
|
||||
|
||||
- core-local whole-product workflow definitions
|
||||
|
||||
Target shape:
|
||||
|
||||
- whole-product workflows live in `govoplan/.gitea/workflows`
|
||||
- workflows bootstrap or use sibling checkouts based on `repositories.json`
|
||||
- core keeps core-only workflows if needed later
|
||||
|
||||
Notes:
|
||||
|
||||
- Gitea workflows are repository-local, so moving them changes which repository
|
||||
triggers the job.
|
||||
- The workflow scripts must stop assuming the checked-out repository is
|
||||
`govoplan-core`.
|
||||
|
||||
### Security Audit Toolbox
|
||||
|
||||
Former location:
|
||||
|
||||
- core-local security audit toolbox files
|
||||
- core-local audit dependency and Gitleaks configuration files
|
||||
|
||||
Reason to move:
|
||||
|
||||
- the tool already supports `--scope govoplan`
|
||||
- the `govoplan` scan mounts the parent directory and scans sibling repos
|
||||
- this is an operator/security workspace function, not runtime core behavior
|
||||
|
||||
Target shape:
|
||||
|
||||
- `govoplan/tools/checks/security-audit/`
|
||||
- `govoplan/tools/checks/check-security-audit.sh`
|
||||
- `govoplan/requirements-audit.txt`
|
||||
- `govoplan/.gitleaks.toml`
|
||||
|
||||
|
||||
### Whole-Product Docker
|
||||
|
||||
Former locations:
|
||||
|
||||
- core-local shared development Docker profiles
|
||||
- website-local public-site Compose profile
|
||||
|
||||
Target shape:
|
||||
|
||||
- shared development and production-like composition move under `govoplan/dev`
|
||||
- deploy/public-site composition can live under `govoplan/docker`
|
||||
- module-specific testbeds stay module-local:
|
||||
- `govoplan-campaign/dev/mail-testbed/docker-compose.yml`
|
||||
- `govoplan-files/dev/connectors/docker-compose.yml`
|
||||
|
||||
## Keep In Core
|
||||
|
||||
These are runtime/kernel concerns and should stay in `govoplan-core`.
|
||||
|
||||
- installer/runtime code under `govoplan_core.core.module_installer`
|
||||
- module discovery, registry, route aggregation, and lifecycle contracts
|
||||
- catalog validation primitives used by the runtime installer
|
||||
- configuration package validation and safety contracts
|
||||
- database/session primitives and migration orchestration APIs
|
||||
- core WebUI shell and module contribution contracts
|
||||
|
||||
Canonical operator entry points should be in `govoplan`.
|
||||
|
||||
## Keep In Public Site Repository
|
||||
|
||||
After the rename, the website repository should keep:
|
||||
|
||||
- Vite/React public website source
|
||||
- screenshots/content source notes
|
||||
- static catalog assets under `public/catalogs/...`
|
||||
- website-specific catalog asset validator if it validates static publication
|
||||
contents
|
||||
- website Dockerfile and simple site-serving compose, unless a whole-product
|
||||
deployment compose takes over in `govoplan`
|
||||
|
||||
It should not own:
|
||||
|
||||
- release version bumping
|
||||
- cross-repository tagging
|
||||
- catalog generation/signing keys
|
||||
- installer logic
|
||||
- module orchestration
|
||||
|
||||
## Rename Follow-Up References
|
||||
|
||||
Known references reviewed after the server-side rename:
|
||||
|
||||
- `govoplan/repositories.json`
|
||||
- `govoplan/docs/project/REPOSITORY_STRUCTURE.md`
|
||||
- `govoplan/docker/README.md`
|
||||
- `govoplan-core/docs/RELEASE_DEPENDENCIES.md`
|
||||
- `govoplan-core/docs/MODULE_ARCHITECTURE.md`
|
||||
- moved release helper references
|
||||
- moved Gitea helper references
|
||||
- public site `README.md`, `package.json`, `package-lock.json`,
|
||||
`docker-compose.yml`, and catalog key rotation runbook
|
||||
|
||||
## Suggested Migration Order
|
||||
|
||||
1. Update local checkout path, remote, repository manifest, and docs.
|
||||
2. Move Gitea helper scripts and source templates from core to meta.
|
||||
3. Move release/catalog command entry points from core to meta and convert
|
||||
repository discovery to `repositories.json`.
|
||||
4. Move whole-product Gitea Actions workflows to meta.
|
||||
5. Move security audit toolbox to meta.
|
||||
6. Move/wrap whole-product Docker composition in meta.
|
||||
7. Remove core compatibility wrappers once docs and workflows use `govoplan`.
|
||||
|
||||
## Current State
|
||||
|
||||
Completed in the meta repository:
|
||||
|
||||
- canonical tools live in `govoplan/tools`
|
||||
- release/catalog/Gitea/security-audit tools have been moved from core to meta
|
||||
- whole-product Gitea workflows have been moved to `govoplan/.gitea/workflows`
|
||||
- shared PostgreSQL and production-like Docker profiles live under `govoplan/dev`
|
||||
- core-local wrappers for moved commands have been removed
|
||||
- the meta `scripts` compatibility layer has been removed; use `govoplan/tools`
|
||||
@@ -0,0 +1,86 @@
|
||||
# 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
|
||||
`repositories.json`.
|
||||
|
||||
## Repository Inventory
|
||||
|
||||
`repositories.json` already lists every checked-out GovOPlaN repository.
|
||||
|
||||
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/project/REPOSITORY_INDEX.md`; the JSON file
|
||||
remains the machine-readable source of truth.
|
||||
|
||||
## Meta-Owned Content
|
||||
|
||||
These items are correctly owned by the meta repository:
|
||||
|
||||
- `.gitea/workflows`: cross-repository CI and audit workflows.
|
||||
- `.gitleaks.toml`: whole-workspace secret scan policy.
|
||||
- `audit-reports`: whole-workspace audit output.
|
||||
- `dev/postgres`: shared development PostgreSQL service.
|
||||
- `dev/production-like`: production-like product validation composition.
|
||||
- `tools/checks`: whole-product checks and audit launchers.
|
||||
- `tools/gitea`: issue/wiki/label/backlog tooling.
|
||||
- `tools/launch`: product launch entry points.
|
||||
- `tools/release`: release catalog, lock, push, and release console tooling.
|
||||
- `tools/repo`: repository bootstrap, status, and metadata tooling.
|
||||
|
||||
## Module-Local Content That Should Stay Local
|
||||
|
||||
These paths look operational, but they are tied to one module's protocol or
|
||||
transport behavior and should stay in the owning repository for now:
|
||||
|
||||
- `govoplan-campaign/dev/mail-testbed`: mail transport testbed for campaign.
|
||||
- `govoplan-files/dev/connectors`: WebDAV, Nextcloud, and SMB connector smoke
|
||||
environment for files.
|
||||
|
||||
The meta repo can later wrap these with aggregate commands, but the test-bed
|
||||
definitions should remain close to the module code unless they become a shared
|
||||
product deployment profile.
|
||||
|
||||
## Generated Or Local-Only Content
|
||||
|
||||
These should not move to the meta repo; they should be ignored or cleaned:
|
||||
|
||||
- `__pycache__` directories under `tools/gitea` and module test beds.
|
||||
- `.venv` and `.ruff_cache` directories.
|
||||
- Populated `.env` files such as `govoplan-campaign/dev/mail-testbed/.env`.
|
||||
|
||||
## Repo-Local Workflow Files
|
||||
|
||||
Most module repositories have `.gitea/ISSUE_TEMPLATE` installed. These are
|
||||
repo-local generated copies of the shared workflow templates and are fine to
|
||||
keep in each repository.
|
||||
|
||||
Repositories currently missing a `.gitea` directory in the local checkout:
|
||||
|
||||
- `govoplan-dashboard`
|
||||
- `govoplan-evaluation`
|
||||
- `govoplan-poll`
|
||||
- `govoplan-rest`
|
||||
- `govoplan-soap`
|
||||
|
||||
If those repositories should use the shared issue templates, run the meta repo
|
||||
installer from `govoplan/tools/gitea/gitea-install-workflow.py`.
|
||||
|
||||
## Do Not Move
|
||||
|
||||
The following stay in each module repository:
|
||||
|
||||
- `pyproject.toml` and package dependency metadata.
|
||||
- Backend manifests and migrations.
|
||||
- Module-owned tests.
|
||||
- Module READMEs and module-specific docs.
|
||||
- WebUI package manifests and module frontend source.
|
||||
|
||||
Those files describe or implement the module itself. The meta repo should
|
||||
catalog and orchestrate them, not become the owner of module code.
|
||||
@@ -0,0 +1,135 @@
|
||||
# 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
|
||||
coherent institutional governance platform, but architecture and repository
|
||||
breadth have advanced faster than complete, usable outcomes. The immediate
|
||||
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/STRATEGY_STATUS.md); stable direction belongs in
|
||||
[Platform Core Ideas](../../strategy/PLATFORM_CORE_IDEAS.md).
|
||||
|
||||
## What Is Already Strong
|
||||
|
||||
- A modular runtime with manifests, capabilities, interfaces, migrations,
|
||||
optional integrations, signed releases, and permutation checks.
|
||||
- Explicit institutional semantics for identity, representation,
|
||||
organization, function, mandate, service, case, party, approval, decision,
|
||||
evidence, and record references.
|
||||
- Governed communication foundations spanning Campaign, Mail, Files, Postbox,
|
||||
Addresses, Distribution Lists, Templates, Audit, and Policy.
|
||||
- Governed data foundations spanning Connectors, Datasources, Dataflow,
|
||||
Reporting, Search, and immutable provenance.
|
||||
- Bitemporal browsing, views, contextual documentation, action/effect
|
||||
contracts, event delivery, recovery ledgers, and stateless deployment
|
||||
contracts.
|
||||
- A credible deployment and release foundation with signed artifacts and
|
||||
reproducible composition evidence.
|
||||
|
||||
## Where The Program Veered
|
||||
|
||||
### Repository breadth preceded product proof
|
||||
|
||||
Logical modularity often became a repository before a reference journey proved
|
||||
that an independent release boundary was required. Scaffolds are useful as
|
||||
ownership markers, but their number makes the product appear broader and more
|
||||
complete than its supported outcomes.
|
||||
|
||||
### Foundations outran reference gates
|
||||
|
||||
Later-stage contracts such as federation, encryption, formal governance,
|
||||
deployment evidence, and broad module metadata were developed while basic
|
||||
human-work and records journeys remained incomplete. Those foundations are not
|
||||
wasted; they now need to be consumed by a small number of demonstrable
|
||||
products.
|
||||
|
||||
### The module graph leaked into the experience
|
||||
|
||||
Navigation, routes, administration, errors, documentation, and configuration
|
||||
often present module names and package structure directly. This is appropriate
|
||||
for operators, but ordinary users should see work, services, records, and
|
||||
outcomes.
|
||||
|
||||
This is not primarily a rail-length or scrolling problem. Sparse permissions
|
||||
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](../../architecture/QUICK_ACCESS_AND_PRODUCT_AREAS.md).
|
||||
|
||||
### Status became duplicated
|
||||
|
||||
Roadmaps, target architecture, fit assessments, issue comments, and release
|
||||
documents each contained partial implementation snapshots. Their stable
|
||||
decisions remain valuable, but volatile counts and maturity claims diverged.
|
||||
|
||||
### Too much work remained active simultaneously
|
||||
|
||||
The issue portfolio had many high-priority and in-progress items without
|
||||
milestones. This reduces the signal of both labels and roadmap order and makes
|
||||
completion harder to demonstrate.
|
||||
|
||||
## Where GovOPlaN Has Not Gone Far Enough
|
||||
|
||||
1. No composition has yet crossed the full `reference_ready` gate.
|
||||
2. The human-work spine is incomplete: work queues, tasks, handoffs, deadlines,
|
||||
reminders, escalation, and resumption need a coherent user experience.
|
||||
3. Records and document management remain too shallow for a public-sector
|
||||
operating platform.
|
||||
4. Real target integrations and GovOPlaN-to-GovOPlaN federation are not yet
|
||||
proven.
|
||||
5. Temporal browsing, purpose-aware access, retention, and institutional
|
||||
context exist as contracts but are not adopted uniformly by domain reads
|
||||
and effects.
|
||||
6. German completeness, contextual help, accessibility, responsive behavior,
|
||||
and browser-level journey testing are not yet release gates everywhere.
|
||||
7. Multi-host, backup/restore, provider interoperability, and independent
|
||||
signed target evidence still require real environments and operators.
|
||||
|
||||
## Important Omissions
|
||||
|
||||
- a named first institution, bounded users, volumes, and operating constraints;
|
||||
- measurable usability outcomes, not only functional tests;
|
||||
- installable sector packages and migration/exit demonstrations;
|
||||
- support, upgrade, deprecation, and LTS promises;
|
||||
- complete assisted, paper, telephone, and in-person channel handling;
|
||||
- a native eAkte/records model that can also overlay an external DMS or archive.
|
||||
|
||||
## Opportunities Beyond The Original Idea
|
||||
|
||||
- an institutional digital twin that exposes responsibilities, dependencies,
|
||||
obligations, services, work, data, controls, and change impact over time;
|
||||
- continuous assurance that evaluates controls and evidence as work happens;
|
||||
- process mining and conformance analysis over governed event histories;
|
||||
- federated product packages and inter-institution case/evidence exchange;
|
||||
- accountable assistance that drafts and explains without obscuring authority;
|
||||
- public evidence chains that disclose decisions and provenance without
|
||||
exposing protected source data.
|
||||
|
||||
## Recommended Reset
|
||||
|
||||
1. Freeze new repositories unless a real journey proves an independent owner,
|
||||
release lifecycle, security boundary, or optional installation need.
|
||||
2. Use one generated maturity/status dashboard and one current status document.
|
||||
3. Complete governed communication and function-bound Postbox against a real
|
||||
target.
|
||||
4. Complete the monthly-data journey, then sanctions screening on the same
|
||||
data foundations.
|
||||
5. Complete one browser-driven service-to-decision journey, including assisted
|
||||
intake and records.
|
||||
6. Make eAkte/records the next major product-depth program.
|
||||
7. Tie feature work to a reference journey, a security/recovery gate, or a
|
||||
measured usability defect.
|
||||
|
||||
## Success Criterion
|
||||
|
||||
The reset succeeds when a public institution can install a signed composition,
|
||||
configure a named procedure, complete it through digital and assisted channels,
|
||||
connect an external source, reconstruct the authority and evidence, recover it
|
||||
after failure, and transfer or retire it without custom code.
|
||||
Reference in New Issue
Block a user