govoplan/docs/GITEA_ISSUES.md

# Gitea Issues And Wiki Workflow

Gitea issues are the canonical backlog for GovOPlaN work: bugs, feature requests, tasks, tech debt, TODO migrations, open decisions, and blocked work should live there. Gitea wiki pages are the canonical project reference for durable project context mirrored from repository docs and product-directory notes.

The same pattern is reusable outside GovOPlaN for any project where Codex works in a local checkout, VSCodium or another editor is used for human inspection, and Gitea is the issue tracker. In that setup, Gitea is the durable coordination layer; Codex and the editor are clients of that state.

## Initial Setup

The repository contains Gitea issue templates in `.gitea/ISSUE_TEMPLATE`, a pull request template in `.gitea/PULL_REQUEST_TEMPLATE.md`, and the label taxonomy in `docs/gitea-labels.json`.

The scripts infer this repository from `origin` (`git@git.add-ideas.de:add-ideas/govoplan.git`). Override inference when needed:

```bash
export GITEA_URL=https://git.add-ideas.de
export GITEA_OWNER=add-ideas
export GITEA_REPO=govoplan
export GITEA_TOKEN=...
```

The API scripts also read `GITEA_*` values from the target repository's `.env` file. That file is gitignored in this repo, so it is suitable for local tokens:

```bash
GITEA_TOKEN=...
# Optional if origin inference is not enough:
GITEA_URL=https://git.add-ideas.de
GITEA_OWNER=add-ideas
GITEA_REPO=govoplan
```

For a shared credentials file outside the target repository, pass `--env-file`:

```bash
./tools/gitea/gitea-sync-labels.py --env-file /path/to/private/gitea.env --apply
```

Create a Gitea token with issue read/write access and label-management
permission for the repository. On scoped-token instances, this usually means
issue read/write and, if label writes are rejected, repository write permission
too.

For GovOPlaN repositories, prefer organization labels for the shared taxonomy.
Creating or updating organization labels requires a token with
`write:organization`. Repository label management only needs repository label
permission, but it duplicates the taxonomy into each repository.

Preview and apply labels:

```bash
cd /mnt/DATA/git/govoplan
./tools/gitea/gitea-sync-labels.py
./tools/gitea/gitea-sync-labels.py --apply
```

Preview and apply the shared taxonomy as organization labels:

```bash
cd /mnt/DATA/git/govoplan
./tools/gitea/gitea-sync-labels.py --scope organization --env-file /home/zemion/.config/gitea/gitea.env
./tools/gitea/gitea-sync-labels.py --scope organization --env-file /home/zemion/.config/gitea/gitea.env --apply
```

The import helpers resolve repository labels and organization labels. Repository
labels win when a repository defines the same name locally, but a repository does
not need a local copy of every shared `type/*`, `status/*`, `priority/*`,
`module/*`, `area/*`, `source/*`, or `codex/*` label.

After the `.gitea` files are pushed to the default branch, Gitea will show the issue template chooser. Blank issues are disabled by `.gitea/ISSUE_TEMPLATE/config.yaml`.

## Multiple Repositories And Workspaces

The helper scripts are path-based and can run from the meta checkout against any repository with a Gitea remote:

```bash
cd /mnt/DATA/git/govoplan
./tools/gitea/gitea-sync-labels.py --root /mnt/DATA/git/govoplan-mail --apply
./tools/gitea/gitea-todo-import.py --root /mnt/DATA/git/govoplan-mail
./tools/gitea/gitea-codex-note.py --root /mnt/DATA/git/govoplan-mail --issue 123 --status progress
```

Each target repository is inferred from its own `origin` remote. Use `GITEA_URL`, `GITEA_OWNER`, or `GITEA_REPO` only when a workspace has unusual remotes or the Gitea web URL cannot be inferred from SSH.

When the meta checkout drives another workspace, prefer `--env-file` for shared
credentials instead of putting `GITEA_REPO` in the meta `.env`; a repo-specific
`GITEA_REPO` can accidentally override target inference.

For non-GovOPlaN projects, provide a project-specific label file and module/project label:

```bash
./tools/gitea/gitea-sync-labels.py \
  --root /path/to/project \
  --labels-file /path/to/project/docs/gitea-labels.json \
  --apply

./tools/gitea/gitea-todo-import.py \
  --root /path/to/project \
  --module-label project/example \
  --extra-label area/backend
```

If another project does not use `area/*` labels, disable area inference:

```bash
./tools/gitea/gitea-todo-import.py \
  --root /path/to/project \
  --module-label project/example \
  --no-area-labels
```

Install or refresh the shared issue templates in sibling or external repositories:

```bash
./tools/gitea/gitea-install-workflow.py /mnt/DATA/git/govoplan-mail
./tools/gitea/gitea-install-workflow.py /mnt/DATA/git/govoplan-mail --apply
```

The installer rewrites the default template label from `module/core` to the module label inferred from the target repository name. Known mappings cover the packaged GovOPlaN repositories, and any other `govoplan-<name>` checkout maps to `module/<name>`. For another workspace or repository name, pass an explicit label:

```bash
./tools/gitea/gitea-install-workflow.py /path/to/repo --module-label module/example --apply
```

Use `--include-labels-file` if a repository should carry its own copy of `docs/gitea-labels.json`; otherwise keep the shared taxonomy in the meta repo and run the sync script from the meta repo.

For a fully portable workflow kit, copy these files into the other project:

- `tools/gitea/gitea_common.py`
- `tools/gitea/gitea-sync-labels.py`
- `tools/gitea/gitea-todo-import.py`
- `tools/gitea/gitea-codex-note.py`
- `tools/gitea/gitea-install-workflow.py`
- `.gitea/ISSUE_TEMPLATE/*`
- `.gitea/PULL_REQUEST_TEMPLATE.md`
- a project-specific `docs/gitea-labels.json`

Keep credentials out of the repository. Put `GITEA_TOKEN` in the shell environment, a gitignored `.env`, a local direnv file, or the user-level Codex/VSCodium environment setup.

## Label Taxonomy

Use one `type/*` label:

- `type/bug`
- `type/feature`
- `type/task`
- `type/debt`
- `type/docs`

Use one `status/*` label while the issue is open:

- `status/triage`: needs ownership, priority, or acceptance criteria.
- `status/ready`: ready to implement.
- `status/in-progress`: actively being worked.
- `status/blocked`: blocked on an external dependency, credential, or decision.
- `status/needs-info`: blocked on clarification.

Use one `priority/*` label when prioritization matters: `priority/p0`, `priority/p1`, `priority/p2`, or `priority/p3`.

Use `module/*` and `area/*` labels to route work. Module labels are not exclusive because cross-module work can exist. Core issues should still preserve ownership boundaries: module-specific implementation belongs in the owning module repository.

Use `codex/ready` when the issue has enough context for Codex to work from, and `codex/needs-human` when a human decision is required first.

## Moving TODOs Into Gitea

Preview inline markers:

```bash
cd /mnt/DATA/git/govoplan
./tools/gitea/gitea-todo-import.py
```

Create missing issues after labels are synced:

```bash
./tools/gitea/gitea-todo-import.py --apply
```

The importer scans `TODO`, `FIXME`, `XXX`, and `HACK` markers, skips markers that already reference an issue, applies `source/todo-scan`, and writes a hidden fingerprint into each generated issue body so reruns do not duplicate already imported items.

When touching code with an imported marker, either remove the marker as part of the fix or replace it with a short reference:

```python
# TODO(gitea#123): keep only if the local pointer is still useful
```

Do not add new untracked TODO comments. Create the Gitea issue first, then reference it inline only when the local pointer materially helps future readers.

For a broader project import across all local repositories hosted on `git.add-ideas.de`, use the generic backlog importer:

```bash
./tools/gitea/gitea-import-all-backlogs.py --env-file /home/zemion/.config/gitea/gitea.env
./tools/gitea/gitea-import-all-backlogs.py --env-file /home/zemion/.config/gitea/gitea.env --apply
```

It scans repository and product-directory files with backlog-like names, resolves
shared labels from the organization label catalogue where available, creates only
missing fallback repository labels when needed, imports missing open work, and
deduplicates reruns by hidden fingerprint and normalized title.

## Mirroring Project Docs Into Gitea Wikis

Preview wiki pages for all local repositories hosted on `git.add-ideas.de`, cross-referenced with product directories under `/mnt/DATA/Nextcloud/ADD ideas UG/Products`:

```bash
cd /mnt/DATA/git/govoplan
./tools/gitea/gitea-sync-wiki.py --env-file /home/zemion/.config/gitea/gitea.env
```

Apply the wiki mirror:

```bash
./tools/gitea/gitea-sync-wiki.py --env-file /home/zemion/.config/gitea/gitea.env --apply
```

After renaming or deleting repository docs, prune previously managed wiki pages
that no longer have a source file:

```bash
./tools/gitea/gitea-sync-wiki.py --env-file /home/zemion/.config/gitea/gitea.env --repo govoplan-core --prune-managed --apply
```

The default apply path uses the Gitea wiki git repository, not one REST API
request per page. It keeps a local checkout cache below
`/tmp/codex-gitea-wiki-sync`, commits changed pages once per repository, and
pushes that commit. This is much faster and avoids REST wiki-page timeouts.
Use `--transport api` only when the wiki git remote is unavailable.

Limit a sync to one repository or one generated page while working:

```bash
./tools/gitea/gitea-sync-wiki.py --repo govoplan-core --apply
./tools/gitea/gitea-sync-wiki.py --repo govoplan-core --page Repo-docs-MODULE-ARCHITECTURE --apply
```

Page-limited syncs do not rewrite `Codex-Project-Index`; run a full repository
sync when the set of mirrored pages changes.

The wiki sync mirrors durable text documents only: root README-style files, docs/codex project docs, and selected product notes such as roadmap, plan, concept, pitch, and whitepaper files. It skips generated folders, dependency/build output, `.gitea` templates, and filenames that look credential-related.

Each managed wiki page contains a `codex-wiki-sync` marker and a source path. Reruns update only managed pages unless `--overwrite-unmanaged` is passed. Each repository also gets a managed `Codex-Project-Index` page linking the mirrored pages.

Use the wiki for durable context:

- project overviews and architecture
- workflows, operating notes, and setup references
- product concepts, plans, pitches, and whitepapers
- historical context that helps interpret issues

Keep active state in issues:

- open tasks, TODOs, feature requests, and bugs
- priority, blocking status, and acceptance criteria
- Codex progress updates and implementation notes

## Codex State Updates

Codex should read the relevant issue before making changes when issue access is available. During or after work, Codex should add issue comments with the state that would otherwise drift into local notes:

- scope understood
- files changed
- tests or manual checks run
- blockers or decisions needed
- follow-up issues created

Preview and post a standardized note:

```bash
./tools/gitea/gitea-codex-note.py \
  --issue 123 \
  --status progress \
  --summary "Implemented capability metadata fallback." \
  --changed src/govoplan_core/modules/registry.py \
  --test "./.venv/bin/python -m unittest tests.test_module_system"

./tools/gitea/gitea-codex-note.py \
  --issue 123 \
  --status progress \
  --summary "Implemented capability metadata fallback." \
  --changed src/govoplan_core/modules/registry.py \
  --test "./.venv/bin/python -m unittest tests.test_module_system" \
  --apply
```

Use `--close --apply` only when the acceptance criteria are satisfied and verification is recorded.

## Ownership Rules

Create the issue in the repository that owns the change:

- `govoplan-core`: platform runner, DB/session primitives, auth, tenancy, RBAC, governance, module discovery, migrations, shared WebUI shell, and generic WebUI components.
- `govoplan-access`: access, identity, authentication, sessions, API keys, RBAC, groups, users, and access administration.
- `govoplan-mail`: mail-specific backend, frontend, message workflows, and mail integrations.
- `govoplan-files`: files-specific backend, frontend, storage, and file workflows.
- `govoplan-campaign`: campaign-specific backend, frontend, policy, and template behavior.

For cross-cutting work, create a tracking issue in `govoplan-core` and link module issues from it. Do not use the core issue as a dumping ground for module-specific implementation details.

## Cleaning Up Mirrored Sources

After backlog files have been imported into issues and durable context has been mirrored to wiki, old duplicate sources can be removed from git only when they are tracked files and the Gitea issue/wiki state has been verified. Prefer deleting backlog, TODO, roadmap, and one-off planning files that have become duplicate state.

Do not delete standard repository entry points such as `README`, `LICENSE`, `SECURITY`, or package metadata just because they are mirrored to the wiki. They remain useful for repository browsing, package registries, and developer onboarding.

Do not delete untracked files or files outside git history as part of automated cleanup unless there is a separate backup or explicit human confirmation for that specific path.

## Docs Versus Issues

Keep durable facts in docs:

- architecture and extension points
- command references
- module boundaries
- operational conventions

Keep changing state in Gitea:

- TODOs and follow-ups
- bugs and feature requests
- blocked status
- acceptance criteria
- implementation notes from active work

If a decision becomes durable architecture, write the durable result into docs and link back to the issue for history.