diff --git a/.github/workflows/code_quality.yml b/.github/workflows/code_quality.yml index dfab364..7cec011 100644 --- a/.github/workflows/code_quality.yml +++ b/.github/workflows/code_quality.yml @@ -28,6 +28,7 @@ env: DETECT_SECRETS: detect-secrets==1.5.0 FLAKE8: flake8==7.3.0 RUFF: ruff==0.16.5 + OPENSPEC: 1.14.0 jobs: # -------------------------------------------------------------------- @@ -110,6 +111,24 @@ jobs: exit 1 fi + # -------------------------------------------------------------------- + # OpenSpec – artefakty změn v openspec/ musí projít validací + # -------------------------------------------------------------------- + openspec: + name: OpenSpec + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3 + + # Verze CLI napevno – formát validace se mezi verzemi mění. + # Node je v ubuntu-latest předinstalovaný. + - name: openspec validate + run: | + npx --yes @fission-ai/openspec@${{ env.OPENSPEC }} \ + validate --all --strict --no-interactive + # -------------------------------------------------------------------- # 3. Načtení pluginu ve skutečném QGIS, v obou podporovaných verzích # -------------------------------------------------------------------- diff --git a/AGENTS.md b/AGENTS.md index 632adff..12f4953 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -17,9 +17,36 @@ Zdroj dat: https://digiarchiv.aiscr.cz/ · Nápověda: https://amcr-help.aiscr.c Tento repozitář je jedním ze **sourozeneckých repozitářů** ekosystému AIS CR. Centrální governance a AI konfigurace spravuje hub **`aiscr-management`**; konvence v tomto souboru jsou s tímto vzorem sladěné a zjednodušené pro potřeby jednoho -QGIS pluginu. Těžkou mašinerii hubu (složka `.agents/`, OpenSpec, sync skripty, -multi-assistant generování) tento repozitář **záměrně nepřebírá**. Při širších -otázkách governance má přednost vzor z `aiscr-management`. +QGIS pluginu. Z hubu přebírá **OpenSpec** ve stupni `change-tracked` (viz +níže). Ostatní mašinerii hubu (složka `.agents/`, sync skripty, vlastní +schémata OpenSpec, multi-assistant generování) tento repozitář **záměrně +nepřebírá**. Při širších otázkách governance má přednost vzor +z `aiscr-management`. + +## OpenSpec + +Repozitář používá OpenSpec ve stupni **`change-tracked`**: plánovací +artefakty změn (`proposal.md`, delta spec, `design.md`, `tasks.md`) žijí +v `openspec/changes//`, trvalé specifikace v `openspec/specs/` se +**neudržují**. Stupeň a kontext pro agenty jsou v `openspec/config.yaml`; +změna stupně se dělá vědomě společně s hubem, ne v rámci rozpracované práce. + +- **Kdy založit změnu:** práce, která mění chování (co uživatel vidí, + atributy vrstev, kontrakt s API digiarchivu, uložená nastavení), zasahuje + víc repozitářů nebo mění pravidla / AI konfiguraci / CI. +- **Kdy ne:** překlepy a formátování, bump závislostí či pinů nástrojů bez + změny chování, přegenerování odvozených souborů. +- **Postup:** `openspec new change ` → artefakty → `openspec validate + --strict` → implementace (až na výslovný pokyn) → po merge + `openspec archive --skip-specs` (archiv + `openspec/changes/archive/RRRR-MM-DD-/`). +- Artefakty změny jdou **ve stejném PR** jako implementace; v popisu PR + odkaž na adresář změny. +- Používá se vestavěné schéma `spec-driven`; vlastní schémata hubu se sem + nepřenášejí. CLI: `npx @fission-ai/openspec@1.14.0` (nebo lokálně + nainstalované `openspec`); bez CLI lze artefakty psát i ručně. +- Asistentské povrchy (`.claude/`, `.github/prompts/` …) doručuje sync + z hubu; v tomto repozitáři se ručně nezakládají ani necommitují. ## Struktura repozitáře @@ -33,7 +60,8 @@ amcr_viewer/ # vlastní kód pluginu (toto se balí do releasu) metadata.txt # metadata pluginu + verze + changelog i18n/ # překlady (.ts) *.png # ikony -.github/workflows/ # CI – release pluginu +.github/workflows/ # CI – kontroly kvality a release pluginu +openspec/ # OpenSpec – konfigurace a plánovací artefakty změn README.md # uživatelská dokumentace (anglicky) ``` @@ -163,6 +191,7 @@ flatpak run --command=sh org.qgis.qgis -c \ - PR musí mířit do správné `version/v2.x.y` větve. - Před požádáním o review projdi kontrolní seznam v šabloně (zejména bump verze v `metadata.txt`, pokud měníš chování). +- Mění-li PR chování, obsahuje i odpovídající změnu v `openspec/changes/`. - V popisu PR uveď **podíl AI** (např. „text navržen AI, ručně zkontrolováno") a odkaz na související issue, pokud existuje. diff --git a/openspec/changes/archive/.gitkeep b/openspec/changes/archive/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/openspec/config.yaml b/openspec/config.yaml new file mode 100644 index 0000000..c62161b --- /dev/null +++ b/openspec/config.yaml @@ -0,0 +1,65 @@ +schema: spec-driven + +# Seeded from aiscr-management +# .agents/canonical_configs/templates/openspec/config_seed.yaml; +# from now on the content is owned by this repository. + +context: | + Repository: aiscr-qgis-amcr-viewer — QGIS plugin (AMČR Viewer) for + downloading and visualising data from the AMČR Digital Archive + (digiarchiv.aiscr.cz). + + OpenSpec posture: change-tracked. + This is the local reading of a posture declared and owned by the + management hub (aiscr-management, .agents/sync/repos.toml): + - change-tracked — change-scoped planning artifacts live under + `openspec/changes/`; no durable capability specs are maintained here. + Do not edit this line to unblock work in progress. Changing posture is + a decision taken deliberately with the hub and then applied here. + + When OpenSpec fires: behaviour-changing work (user-visible behaviour, + layer attributes, the digiarchiv API contract the plugin relies on, + stored settings), cross-repo work, and governance-touching work. Not + typo and formatting fixes, dependency or tool-pin bumps that change no + behaviour, or refreshing a generated surface from its source. + + Repository conventions: `AGENTS.md` is the single source of truth + (Qt5/Qt6 rules, versioning, branches, checks). Plugin code lives in + `amcr_viewer/` (entry point `amcr_viewer.py`, API and layers in + `amcr_tools.py`, dialogs in `amcr_dialog.py`, codelists in + `amcr_codelists.py`). User documentation is `README.md` (English); + planning artifacts, commits and PRs are in Czech or English as the + author prefers, code and identifiers in English. + +rules: + proposal: + - State what changes for a user of the plugin, not only in the code + - Name the affected modules under amcr_viewer/ explicitly + - Say when the change depends on or affects the digiarchiv API or + another AIS CR repository, and where + specs: + - Use RFC 2119 keywords (SHALL/MUST/SHOULD/MAY) + - Use Given/When/Then scenarios for testable contracts + - Describe behaviour the plugin guarantees, not how the code does it + design: + - Record the alternatives considered and why the chosen one won + - Respect the QGIS 3.44 minimum and Qt5/Qt6 rules from AGENTS.md + - Name the verification that will show the change worked + tasks: + - Order tasks so each one is independently verifiable + - Name the command or check that proves each group is done + - Include the version bump (metadata.txt + CITATION.cff) when + behaviour changes + - Include a final verification task that runs the checks from + AGENTS.md (check_sources, bandit, detect-secrets, flake8, ruff, + pyqgis4-checker, smoke test in qgis/qgis:ltr and :stable) + +operations: + apply: + guidance: + - Completed artifacts are not approval to implement; wait for an + explicit request to apply the change + archive: + guidance: + - Posture is change-tracked, so archive with --skip-specs (no + openspec/specs/ tree is maintained)