From b0a74142048c9a99688ae7fac23c4299a03c9062 Mon Sep 17 00:00:00 2001 From: Jens Tirsvad Nielsen Date: Wed, 7 Oct 2026 12:02:59 +0800 Subject: [PATCH] Add Pretty Table project: plan, accepted documents and code Business Case, Stakeholder Analysis, Project Plan and milestone MIL-001 with review records RC-001 to RC-003, then the Python project: PrettyTable Pokemon table, constants, pytest tests, pyproject.toml, Doxyfile, CI workflow and README. Task: MIL-001#1 Task: MIL-001#2 Task: MIL-001#3 Task: MIL-001#4 Task: MIL-001#5 Task: MIL-001#6 Task: MIL-001#7 Task: MIL-001#8 --- .agents/skills/.framework-skills | 3 + .agents/skills/artifact/SKILL.md | 131 ++++++++ .agents/skills/artifact/references/ADR.md | 25 ++ .agents/skills/artifact/references/BC.md | 45 +++ .agents/skills/artifact/references/BMC.md | 21 ++ .agents/skills/artifact/references/BPMN.md | 22 ++ .agents/skills/artifact/references/DCD.md | 27 ++ .agents/skills/artifact/references/DICT.md | 31 ++ .agents/skills/artifact/references/DM.md | 26 ++ .agents/skills/artifact/references/ERD.md | 22 ++ .agents/skills/artifact/references/GOV.md | 16 + .agents/skills/artifact/references/KPI.md | 20 ++ .agents/skills/artifact/references/MIL.md | 48 +++ .agents/skills/artifact/references/OC.md | 27 ++ .agents/skills/artifact/references/PP.md | 64 ++++ .agents/skills/artifact/references/QC.md | 55 ++++ .agents/skills/artifact/references/RC.md | 45 +++ .agents/skills/artifact/references/SA.md | 27 ++ .agents/skills/artifact/references/SD.md | 26 ++ .agents/skills/artifact/references/SSD.md | 21 ++ .agents/skills/artifact/references/TM.md | 18 ++ .agents/skills/artifact/references/TRN.md | 18 ++ .agents/skills/artifact/references/TRR.md | 23 ++ .agents/skills/artifact/references/UC.md | 35 +++ .agents/skills/artifact/references/UCD.md | 24 ++ .agents/skills/artifact/references/US.md | 22 ++ .agents/skills/artifact/templates/ADR.md | 42 +++ .agents/skills/artifact/templates/BC.md | 72 +++++ .agents/skills/artifact/templates/BMC.md | 115 +++++++ .agents/skills/artifact/templates/BPMN.md | 43 +++ .agents/skills/artifact/templates/DCD.md | 50 ++++ .agents/skills/artifact/templates/DICT.md | 37 +++ .agents/skills/artifact/templates/DM.md | 56 ++++ .agents/skills/artifact/templates/ERD.md | 53 ++++ .agents/skills/artifact/templates/GOV.md | 70 +++++ .agents/skills/artifact/templates/KPI.md | 37 +++ .agents/skills/artifact/templates/MIL.md | 60 ++++ .agents/skills/artifact/templates/OC.md | 41 +++ .agents/skills/artifact/templates/PP.md | 63 ++++ .agents/skills/artifact/templates/QC.md | 42 +++ .agents/skills/artifact/templates/RC.md | 51 ++++ .agents/skills/artifact/templates/SA.md | 56 ++++ .agents/skills/artifact/templates/SD.md | 47 +++ .agents/skills/artifact/templates/SSD.md | 42 +++ .agents/skills/artifact/templates/TM.md | 30 ++ .agents/skills/artifact/templates/TRN.md | 60 ++++ .agents/skills/artifact/templates/TRR.md | 43 +++ .agents/skills/artifact/templates/UC.md | 57 ++++ .agents/skills/artifact/templates/UCD.md | 52 ++++ .agents/skills/artifact/templates/US.md | 38 +++ .agents/skills/coding-conventions/SKILL.md | 98 ++++++ .../skills/coding-conventions/references/c.md | 71 +++++ .../coding-conventions/references/cpp.md | 70 +++++ .../coding-conventions/references/csharp.md | 72 +++++ .../coding-conventions/references/python.md | 66 ++++ .../coding-conventions/references/shell.md | 62 ++++ .agents/skills/project-planning/SKILL.md | 283 ++++++++++++++++++ .claude/skills/.framework-skills | 3 + .claude/skills/artifact/SKILL.md | 131 ++++++++ .claude/skills/artifact/references/ADR.md | 25 ++ .claude/skills/artifact/references/BC.md | 45 +++ .claude/skills/artifact/references/BMC.md | 21 ++ .claude/skills/artifact/references/BPMN.md | 22 ++ .claude/skills/artifact/references/DCD.md | 27 ++ .claude/skills/artifact/references/DICT.md | 31 ++ .claude/skills/artifact/references/DM.md | 26 ++ .claude/skills/artifact/references/ERD.md | 22 ++ .claude/skills/artifact/references/GOV.md | 16 + .claude/skills/artifact/references/KPI.md | 20 ++ .claude/skills/artifact/references/MIL.md | 48 +++ .claude/skills/artifact/references/OC.md | 27 ++ .claude/skills/artifact/references/PP.md | 64 ++++ .claude/skills/artifact/references/QC.md | 55 ++++ .claude/skills/artifact/references/RC.md | 45 +++ .claude/skills/artifact/references/SA.md | 27 ++ .claude/skills/artifact/references/SD.md | 26 ++ .claude/skills/artifact/references/SSD.md | 21 ++ .claude/skills/artifact/references/TM.md | 18 ++ .claude/skills/artifact/references/TRN.md | 18 ++ .claude/skills/artifact/references/TRR.md | 23 ++ .claude/skills/artifact/references/UC.md | 35 +++ .claude/skills/artifact/references/UCD.md | 24 ++ .claude/skills/artifact/references/US.md | 22 ++ .claude/skills/artifact/templates/ADR.md | 42 +++ .claude/skills/artifact/templates/BC.md | 72 +++++ .claude/skills/artifact/templates/BMC.md | 115 +++++++ .claude/skills/artifact/templates/BPMN.md | 43 +++ .claude/skills/artifact/templates/DCD.md | 50 ++++ .claude/skills/artifact/templates/DICT.md | 37 +++ .claude/skills/artifact/templates/DM.md | 56 ++++ .claude/skills/artifact/templates/ERD.md | 53 ++++ .claude/skills/artifact/templates/GOV.md | 70 +++++ .claude/skills/artifact/templates/KPI.md | 37 +++ .claude/skills/artifact/templates/MIL.md | 60 ++++ .claude/skills/artifact/templates/OC.md | 41 +++ .claude/skills/artifact/templates/PP.md | 63 ++++ .claude/skills/artifact/templates/QC.md | 42 +++ .claude/skills/artifact/templates/RC.md | 51 ++++ .claude/skills/artifact/templates/SA.md | 56 ++++ .claude/skills/artifact/templates/SD.md | 47 +++ .claude/skills/artifact/templates/SSD.md | 42 +++ .claude/skills/artifact/templates/TM.md | 30 ++ .claude/skills/artifact/templates/TRN.md | 60 ++++ .claude/skills/artifact/templates/TRR.md | 43 +++ .claude/skills/artifact/templates/UC.md | 57 ++++ .claude/skills/artifact/templates/UCD.md | 52 ++++ .claude/skills/artifact/templates/US.md | 38 +++ .claude/skills/coding-conventions/SKILL.md | 98 ++++++ .../skills/coding-conventions/references/c.md | 71 +++++ .../coding-conventions/references/cpp.md | 70 +++++ .../coding-conventions/references/csharp.md | 72 +++++ .../coding-conventions/references/python.md | 66 ++++ .../coding-conventions/references/shell.md | 62 ++++ .claude/skills/project-planning/SKILL.md | 283 ++++++++++++++++++ .gitea/workflows/ci.yml | 26 ++ .gitignore | 179 +++++++++++ .gitmodules | 3 + AGENTS.md | 60 ++++ Doxyfile | 16 + README.md | 146 ++++++++- docs/artifact-registry.md | 58 ++++ docs/business-case.md | 121 ++++++++ .../mil-001-pretty-table-project.md | 81 +++++ docs/project-plan.md | 71 +++++ docs/sqa/reviews/rc-001-business-case.md | 60 ++++ .../reviews/rc-002-stakeholder-analysis.md | 53 ++++ docs/sqa/reviews/rc-003-milestone-g1.md | 53 ++++ docs/stakeholder-analysis.md | 74 +++++ framework | 1 + pyproject.toml | 39 +++ src/pretty_table/__init__.py | 4 + src/pretty_table/__main__.py | 8 + src/pretty_table/constants.py | 20 ++ src/pretty_table/main.py | 30 ++ tests/__init__.py | 0 tests/test_constants.py | 17 ++ tests/test_main.py | 40 +++ 137 files changed, 6801 insertions(+), 1 deletion(-) create mode 100644 .agents/skills/.framework-skills create mode 100644 .agents/skills/artifact/SKILL.md create mode 100644 .agents/skills/artifact/references/ADR.md create mode 100644 .agents/skills/artifact/references/BC.md create mode 100644 .agents/skills/artifact/references/BMC.md create mode 100644 .agents/skills/artifact/references/BPMN.md create mode 100644 .agents/skills/artifact/references/DCD.md create mode 100644 .agents/skills/artifact/references/DICT.md create mode 100644 .agents/skills/artifact/references/DM.md create mode 100644 .agents/skills/artifact/references/ERD.md create mode 100644 .agents/skills/artifact/references/GOV.md create mode 100644 .agents/skills/artifact/references/KPI.md create mode 100644 .agents/skills/artifact/references/MIL.md create mode 100644 .agents/skills/artifact/references/OC.md create mode 100644 .agents/skills/artifact/references/PP.md create mode 100644 .agents/skills/artifact/references/QC.md create mode 100644 .agents/skills/artifact/references/RC.md create mode 100644 .agents/skills/artifact/references/SA.md create mode 100644 .agents/skills/artifact/references/SD.md create mode 100644 .agents/skills/artifact/references/SSD.md create mode 100644 .agents/skills/artifact/references/TM.md create mode 100644 .agents/skills/artifact/references/TRN.md create mode 100644 .agents/skills/artifact/references/TRR.md create mode 100644 .agents/skills/artifact/references/UC.md create mode 100644 .agents/skills/artifact/references/UCD.md create mode 100644 .agents/skills/artifact/references/US.md create mode 100644 .agents/skills/artifact/templates/ADR.md create mode 100644 .agents/skills/artifact/templates/BC.md create mode 100644 .agents/skills/artifact/templates/BMC.md create mode 100644 .agents/skills/artifact/templates/BPMN.md create mode 100644 .agents/skills/artifact/templates/DCD.md create mode 100644 .agents/skills/artifact/templates/DICT.md create mode 100644 .agents/skills/artifact/templates/DM.md create mode 100644 .agents/skills/artifact/templates/ERD.md create mode 100644 .agents/skills/artifact/templates/GOV.md create mode 100644 .agents/skills/artifact/templates/KPI.md create mode 100644 .agents/skills/artifact/templates/MIL.md create mode 100644 .agents/skills/artifact/templates/OC.md create mode 100644 .agents/skills/artifact/templates/PP.md create mode 100644 .agents/skills/artifact/templates/QC.md create mode 100644 .agents/skills/artifact/templates/RC.md create mode 100644 .agents/skills/artifact/templates/SA.md create mode 100644 .agents/skills/artifact/templates/SD.md create mode 100644 .agents/skills/artifact/templates/SSD.md create mode 100644 .agents/skills/artifact/templates/TM.md create mode 100644 .agents/skills/artifact/templates/TRN.md create mode 100644 .agents/skills/artifact/templates/TRR.md create mode 100644 .agents/skills/artifact/templates/UC.md create mode 100644 .agents/skills/artifact/templates/UCD.md create mode 100644 .agents/skills/artifact/templates/US.md create mode 100644 .agents/skills/coding-conventions/SKILL.md create mode 100644 .agents/skills/coding-conventions/references/c.md create mode 100644 .agents/skills/coding-conventions/references/cpp.md create mode 100644 .agents/skills/coding-conventions/references/csharp.md create mode 100644 .agents/skills/coding-conventions/references/python.md create mode 100644 .agents/skills/coding-conventions/references/shell.md create mode 100644 .agents/skills/project-planning/SKILL.md create mode 100644 .claude/skills/.framework-skills create mode 100644 .claude/skills/artifact/SKILL.md create mode 100644 .claude/skills/artifact/references/ADR.md create mode 100644 .claude/skills/artifact/references/BC.md create mode 100644 .claude/skills/artifact/references/BMC.md create mode 100644 .claude/skills/artifact/references/BPMN.md create mode 100644 .claude/skills/artifact/references/DCD.md create mode 100644 .claude/skills/artifact/references/DICT.md create mode 100644 .claude/skills/artifact/references/DM.md create mode 100644 .claude/skills/artifact/references/ERD.md create mode 100644 .claude/skills/artifact/references/GOV.md create mode 100644 .claude/skills/artifact/references/KPI.md create mode 100644 .claude/skills/artifact/references/MIL.md create mode 100644 .claude/skills/artifact/references/OC.md create mode 100644 .claude/skills/artifact/references/PP.md create mode 100644 .claude/skills/artifact/references/QC.md create mode 100644 .claude/skills/artifact/references/RC.md create mode 100644 .claude/skills/artifact/references/SA.md create mode 100644 .claude/skills/artifact/references/SD.md create mode 100644 .claude/skills/artifact/references/SSD.md create mode 100644 .claude/skills/artifact/references/TM.md create mode 100644 .claude/skills/artifact/references/TRN.md create mode 100644 .claude/skills/artifact/references/TRR.md create mode 100644 .claude/skills/artifact/references/UC.md create mode 100644 .claude/skills/artifact/references/UCD.md create mode 100644 .claude/skills/artifact/references/US.md create mode 100644 .claude/skills/artifact/templates/ADR.md create mode 100644 .claude/skills/artifact/templates/BC.md create mode 100644 .claude/skills/artifact/templates/BMC.md create mode 100644 .claude/skills/artifact/templates/BPMN.md create mode 100644 .claude/skills/artifact/templates/DCD.md create mode 100644 .claude/skills/artifact/templates/DICT.md create mode 100644 .claude/skills/artifact/templates/DM.md create mode 100644 .claude/skills/artifact/templates/ERD.md create mode 100644 .claude/skills/artifact/templates/GOV.md create mode 100644 .claude/skills/artifact/templates/KPI.md create mode 100644 .claude/skills/artifact/templates/MIL.md create mode 100644 .claude/skills/artifact/templates/OC.md create mode 100644 .claude/skills/artifact/templates/PP.md create mode 100644 .claude/skills/artifact/templates/QC.md create mode 100644 .claude/skills/artifact/templates/RC.md create mode 100644 .claude/skills/artifact/templates/SA.md create mode 100644 .claude/skills/artifact/templates/SD.md create mode 100644 .claude/skills/artifact/templates/SSD.md create mode 100644 .claude/skills/artifact/templates/TM.md create mode 100644 .claude/skills/artifact/templates/TRN.md create mode 100644 .claude/skills/artifact/templates/TRR.md create mode 100644 .claude/skills/artifact/templates/UC.md create mode 100644 .claude/skills/artifact/templates/UCD.md create mode 100644 .claude/skills/artifact/templates/US.md create mode 100644 .claude/skills/coding-conventions/SKILL.md create mode 100644 .claude/skills/coding-conventions/references/c.md create mode 100644 .claude/skills/coding-conventions/references/cpp.md create mode 100644 .claude/skills/coding-conventions/references/csharp.md create mode 100644 .claude/skills/coding-conventions/references/python.md create mode 100644 .claude/skills/coding-conventions/references/shell.md create mode 100644 .claude/skills/project-planning/SKILL.md create mode 100644 .gitea/workflows/ci.yml create mode 100644 .gitignore create mode 100644 .gitmodules create mode 100644 AGENTS.md create mode 100644 Doxyfile create mode 100644 docs/artifact-registry.md create mode 100644 docs/business-case.md create mode 100644 docs/milestones/mil-001-pretty-table-project.md create mode 100644 docs/project-plan.md create mode 100644 docs/sqa/reviews/rc-001-business-case.md create mode 100644 docs/sqa/reviews/rc-002-stakeholder-analysis.md create mode 100644 docs/sqa/reviews/rc-003-milestone-g1.md create mode 100644 docs/stakeholder-analysis.md create mode 160000 framework create mode 100644 pyproject.toml create mode 100644 src/pretty_table/__init__.py create mode 100644 src/pretty_table/__main__.py create mode 100644 src/pretty_table/constants.py create mode 100644 src/pretty_table/main.py create mode 100644 tests/__init__.py create mode 100644 tests/test_constants.py create mode 100644 tests/test_main.py diff --git a/.agents/skills/.framework-skills b/.agents/skills/.framework-skills new file mode 100644 index 0000000..5dad221 --- /dev/null +++ b/.agents/skills/.framework-skills @@ -0,0 +1,3 @@ +artifact +coding-conventions +project-planning diff --git a/.agents/skills/artifact/SKILL.md b/.agents/skills/artifact/SKILL.md new file mode 100644 index 0000000..283b77d --- /dev/null +++ b/.agents/skills/artifact/SKILL.md @@ -0,0 +1,131 @@ +--- +name: artifact +description: Create, edit or review any project document artifact — Business Case, Stakeholder Analysis, KPI, Business Model Canvas, BPMN, milestones/gateways, use case diagram, user stories, use cases, domain model, SSD, operation contracts, sequence diagrams, DCD, ERD, ADRs, SQA review records, traceability matrix, governance, QC checklists. Scaffolds the file with the correct ID, CrossReference and links, then gives the required sections for that type. +--- + +# Artifact + +Every artifact is a markdown file with `## Metadata` and `## Version History` +tables, a registered short-name ID, and links only at the bottom. Types and +their related types are in `framework/registry/artifact-catalog.md`; this +project's file locations and next versions are in `docs/artifact-registry.md`. + +## Creating an artifact + +1. Find the type's short name (`BC`, `SA`, `MIL`, `DM`, `ADR`, `RC`, …) in + the catalog. If the type is new, add it to the catalog and the registry. +2. Scaffold — this sets the ID, `CrossReference` (only artifacts that exist), + the bottom link block and the registry version: + + ```bash + bash framework/scripts/new-artifact.sh [--file ] [--title ""] [--cite =]... + ``` + + `--file` is required for multi-document types (`MIL`, `UC`, `ADR`, `RC`, + `QC`); single-document types default to the registry's `Primary File`. + The script refuses to overwrite an existing file. +3. Read `framework/.agents/skills/artifact/references/.md` (cite-for + hints and required sections), then fill in the file. Keep the sections in + order and replace every ``. + +## Editing an artifact + +Append a row to `## Version History` on every change (a status change such as +`Proposed` → `Accepted`, or a content change). To re-check `CrossReference`, +run `bash framework/scripts/find-crossreferences.sh `. When the first +instance of a type is created, add it to the `CrossReference` of every +existing artifact that lists that type as a candidate (with a new Version +History row). + +### Version History rule + +The table keeps only the **two latest** changes; git holds the rest. Columns: + +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| 2026-10-01 | Accepted | Jens Tirsvad Nielsen | S02 | Added Risks section
Fixed scope wording | [a1b2c3d] | + +- **Status** — `Proposed`, `Accepted`, `Rejected` or `Deprecated` for every + artifact type (`ADR` also has `Superseded by ADR-NNNN`); `Approved` is not + used. A new row starts `Proposed`. When the review gives Go, that row + becomes `Accepted` and the row before it becomes `Deprecated`, so at most + one row is `Accepted`: the latest reviewed one. If the reviewer refuses the + change for good (not a No-Go that returns it for rework), the row becomes + `Rejected`; the earlier `Accepted` row stays `Accepted` and nothing is + deprecated. +- **Change** — a short summary of what this row changed; several lines are + separated with `
`. +- **Commit** — the commit that made the change, as a reference-style link + defined at the bottom of the file + (`[a1b2c3d]: https://///commit/`; Gitea and + GitHub use the same `/commit/` form). A row cannot contain its own commit + hash, so a new row says `pending` until the commit exists. Leave it + `pending` and do not commit: only when the user asks for a commit, then: + 1. commit the edited documents; + 2. run `bash framework/scripts/resolve-pending-commits.sh ...`, which + replaces `pending` with the link to that commit and adds the definition; + 3. commit the result as a follow-up commit, before opening the PR. Do not + amend: an amend changes the hash, so the link would point at a commit + that is never pushed. +- When adding a third row, delete the oldest row and its now-unused commit + link definition. Never rewrite the content of the two retained rows other + than resolving `pending` and setting Status to `Accepted` / `Deprecated` + after a Go review. +- Every document uses this format, including QC checklists. A file still in the + old four-column format is converted when next edited (old row kept as + `Initial version`, plus a new row for the conversion). + +## Reviewing an artifact + +1. Take the QC checklist named in the catalog (`framework/qc/qc-*.md`). +2. Create the review record: `new-artifact.sh RC …`, following + `references/RC.md`. +3. Add or update the instance's row in the Traceability Matrix. + +## Rules + +- **Links:** all links are reference-style, defined once at the bottom of the + file after a final `---`, labelled by the target's ID (`[SA-001]`), never + inline. No links → omit the block. +- **CrossReference:** cite only artifacts that exist now. Empty if none. +- **People:** use exact stakeholder IDs from the project's Stakeholder + Analysis (`S01`) for owners, reviewers and RACI. Never invent role names. +- **Diagrams** are PlantUML blocks; check them with + `bash framework/scripts/render-diagrams.sh --server ` (or set + `PLANTUML_URL`) before review. +- **QC checklists** are framework files: every criterion is tagged with an + ISO/IEC 25010:2023 characteristic, and they never mention real instances. +- **IDs:** `-`, 3 digits (`BC-001`); `ADR` uses 4 digits; + `RC` is sequential across all types; QC is `QC--`. +- **Language:** the PO language and the register of each artifact type are in + the `Languages` section of `docs/artifact-registry.md` (registers: + `IT Executive English` for high-level, `IT Professional English` for + technical). +- **Language and Domain rows:** every artifact of a type written in the PO + language has `Language` and `Domain` rows in its Metadata table, so a reviewer + sees at once how to read it. `Language` is a BCP 47 code (`da`, `en`); + `Domain` is a value from the domain list in the registry's `Languages` + section (for example `it`, `medical`, `construction`), because the same + language can carry a different professional vocabulary. `new-artifact.sh` + fills both from the registry's `PO language` and `PO domain` settings and + leaves a placeholder (with a warning) when a setting is missing. Technical + types (OC, SD, DCD, ERD, ADR, TM, RC, QC, source code) have no such rows: + they are always professional IT English. To list every document's language + and domain, see `check-languages.sh --list`. +- **One file per artifact:** each type the registry marks "Written in the PO + language" exists once, in that language, under its normal name + (`business-case.md`). There is no translated twin (`business-case.da.md`) + and no authoritative English source; two files drift apart. Use the PO terms + from the dictionary (`DICT`). Types marked "No" (OC, SD, DCD, ERD, ADR, TM, + RC, QC, source code) stay in professional IT English. +- **Structural vocabulary stays English:** Metadata keys, section headings, + IDs and statuses are the same in every language, because the scripts read + them (`find-crossreferences.sh`, `new-artifact.sh`, + `resolve-pending-commits.sh`, `sync-project.sh`, `check-plan.sh`). Only the + content (prose and table cells) is in the PO language. +- **Changing an artifact's language** is a material change: add a Version + History row ("language en to da") and review it again. Git history keeps the + earlier language. +- **Dictionary:** the Domain Model uses the PO term; the Operation Contract, + Sequence Diagram, Design Class Diagram and ERD use the IT term. Every pair is + recorded in `docs/dictionary.md` (`DICT`). diff --git a/.agents/skills/artifact/references/ADR.md b/.agents/skills/artifact/references/ADR.md new file mode 100644 index 0000000..eb9e4c3 --- /dev/null +++ b/.agents/skills/artifact/references/ADR.md @@ -0,0 +1,25 @@ +# Architecture Decision Record (ADR) + +Files: `docs/adr/adr-NNNN-kebab-case-title.md`. `NNNN` is 4-digit and +sequential; the ID is `ADR-NNNN` and must match the filename number (an +intentional exception to the usual 3-digit IDs). Use +`new-artifact.sh ADR --file docs/adr/adr-NNNN-title.md`. + +Cite in `CrossReference` the artifacts this decision is about (pass each +with `--cite =`); ADR has no fixed candidate list. + +## Required sections (after Metadata / Version History) + +- **Context** — the problem, the options evaluated and the forces + (cost, risk, constraints). +- **Decision** — the outcome in one or two sentences, no hedging. +- **Consequences** — two bold labels, **Positive:** and **Negative:**, each + with a bullet list. +- **Affected Artifacts** — other artifacts impacted, as `[ID]` links, or a + single `-` if none. + +Allowed statuses: `Proposed`, `Accepted`, `Rejected`, `Deprecated`, +`Superseded by ADR-NNNN`; no others (an ADR is never `Approved`). Status +changes (`Proposed` → `Accepted` → `Deprecated` / `Superseded by ADR-NNNN`, or +`Proposed` → `Rejected`) are new rows in `## Version History` (only the two +latest are kept; earlier ones stay in git); never rewrite a retained row. diff --git a/.agents/skills/artifact/references/BC.md b/.agents/skills/artifact/references/BC.md new file mode 100644 index 0000000..f3f07da --- /dev/null +++ b/.agents/skills/artifact/references/BC.md @@ -0,0 +1,45 @@ +# Business Case (BC) + +Cite in `CrossReference` only if the instance exists (`new-artifact.sh` checks this for you): + +- **SA** — Stakeholders section — cite S-IDs instead of re-describing roles +- **BMC** — Cost–Benefit Assessment must agree with its cost/revenue blocks +- **BPMN** — Forward: the process that realizes the objectives +- **KPI** — Success Criteria — each criterion is operationalized by a KPI +- **UCD** — Forward: scope expressed as actors and goals + +## Required sections (after Metadata / Version History) + +In this order: + +1. **Executive Summary** — one paragraph framing the problem and the + proposed solution. +2. **Methodological and Standards Foundation** — states the methodology + (e.g. Larman's *Applying UML and Patterns*) and quality standards (e.g. + ISO/IEC 25002/25010/25019) the rest of the document and downstream + artifacts are built on. +3. **Problem Statement** — the recurring problems that justify the project. +4. **Business Opportunity** — what becomes possible if the problem is + solved. +5. **Objectives** — concrete, verifiable statements of what the project + will achieve. +6. **Scope** — split into `## In Scope` and `## Out of Scope` subsections. +7. **Expected Benefits** — split into `### Tangible Benefits` and + `### Intangible Benefits`. +8. **Strategic Alignment** — how the project supports organizational goals. +9. **Success Criteria** — a table with explicit, measurable targets (not + aspirations). +10. **Risks** — a table with `Risk | Impact | Mitigation` columns; every + risk must have a mitigation. +11. **Assumptions** — bullet list, kept distinct from Constraints. +12. **Constraints** — bullet list, kept distinct from Assumptions. +13. **Cost–Benefit Assessment** — a table (`Costs | Benefits`); may be + qualitative if explicitly justified. +14. **Stakeholders** — a table referencing exact stakeholder IDs from the + project's Stakeholder Analysis (e.g. `S01`, `S07`) if `SA` exists per + the CrossReference check above. **Never re-describe stakeholder roles + inline instead of citing their IDs** — this is the single most common + defect found when reviewing Business Cases (see `QC-BC-001`'s Common + Defects). +15. **Recommendation** — a single, unambiguous "proceed" or "do not + proceed" statement. diff --git a/.agents/skills/artifact/references/BMC.md b/.agents/skills/artifact/references/BMC.md new file mode 100644 index 0000000..6fe740d --- /dev/null +++ b/.agents/skills/artifact/references/BMC.md @@ -0,0 +1,21 @@ +# Business Model Canvas (BMC) + +Cite in `CrossReference` only if the instance exists (`new-artifact.sh` checks this for you): + +- **BC** — Objectives the canvas operationalizes; cost/revenue must agree with its Cost–Benefit Assessment +- **SA** — Value Propositions, Customer Segments, Channels — cite S-IDs +- **BPMN** — Key Activities — cite the process that realizes them +- **KPI** — Measures of value proposition / revenue — cite KPI IDs + +## Required sections (after Metadata / Version History) + +1. **Purpose / Scope** — one paragraph. +2. **Canvas** — all 9 building blocks populated, none empty: Key Partners, + Key Activities, Key Resources, Value Propositions, Customer + Relationships, Channels, Customer Segments, Cost Structure, Revenue + Streams. Must stay reviewable as a single, concise overview. +3. **Assumptions** — explicit and testable (how would we know it is wrong?). +4. **Consistency Check** — Revenue Streams vs Cost Structure agree; + Segments/Channels match stakeholder groups from `SA`. + +Cite Business Case objectives (`[BC-001]`) instead of restating them. diff --git a/.agents/skills/artifact/references/BPMN.md b/.agents/skills/artifact/references/BPMN.md new file mode 100644 index 0000000..6c8cda9 --- /dev/null +++ b/.agents/skills/artifact/references/BPMN.md @@ -0,0 +1,22 @@ +# BPMN Process Model (BPMN) + +Cite in `CrossReference` only if the instance exists (`new-artifact.sh` checks this for you): + +- **BC** — The stated business goal/objective the process serves +- **SA** — Participants / lanes — cite S-IDs +- **UCD** — Forward link: actors and goals derived from this process + +## Required sections (after Metadata / Version History) + +1. **Purpose and Business Goal** — the Business Case objective realized + (cite `[BC-001]`). +2. **Participants (Pools / Lanes)** — every participant, mapped to an `SA` + stakeholder ID where one exists. +3. **Process Diagram** — valid BPMN 2.0. Message flows cross pool + boundaries; sequence flows do not. Keep the diagram source next to the + document (BPMN has no native markdown form) so it stays diffable. +4. **Element Table** — `Element | Type | Lane | Description` for every + event, activity and gateway. Every gateway states its type (XOR/AND/OR) + and its matching join. +5. **Path Coverage** — every path runs from a start event to a defined end + event; no dead ends. diff --git a/.agents/skills/artifact/references/DCD.md b/.agents/skills/artifact/references/DCD.md new file mode 100644 index 0000000..c1df83b --- /dev/null +++ b/.agents/skills/artifact/references/DCD.md @@ -0,0 +1,27 @@ +# Design Class Diagram (DCD) (DCD) + +Cite in `CrossReference` only if the instance exists (`new-artifact.sh` checks this for you): + +- **DM** — Concepts each design class refines — names must stay consistent +- **SD** — Messages that become method signatures +- **ERD** — Forward: persistence of the classes' attributes + +## Required sections (after Metadata / Version History) + +1. **Purpose and Scope**. +2. **Diagram** — PlantUML class diagram: visibility markers (`+` `-` `#`) + on every member; association vs aggregation vs composition vs dependency + used per true ownership/lifecycle; multiplicity and navigability on every + association. +3. **Class Table** — `Class | Refines (Domain Model concept) | + Responsibility (one sentence) | Attributes | Operations`. SOLID applied; + no god classes; names consistent with the Domain Model. +4. **Method Traceability** — `Method signature | Operation Contract / SD + message`; every method traces to one. +5. **Pattern Annotations** — `Pattern | Classes | Rationale`, explicit. +6. **Dependency Check** — note confirming no circular class/package + dependencies (or an explicit justification). + +## Terminology + +Class and attribute names are the IT terms from the dictionary (`DICT`), not the PO terms the Domain Model uses. diff --git a/.agents/skills/artifact/references/DICT.md b/.agents/skills/artifact/references/DICT.md new file mode 100644 index 0000000..d9d6872 --- /dev/null +++ b/.agents/skills/artifact/references/DICT.md @@ -0,0 +1,31 @@ +# Domain Dictionary (DICT) + +Cite in `CrossReference` only if the instance exists (`new-artifact.sh` checks this for you): + +- **BC** — The business goals the vocabulary serves +- **SA** — The Product Owner (and other business stakeholders) whose terms are recorded +- **DM** — Concepts whose PO terms are recorded + +## Required sections (after Metadata / Version History) + +1. **Purpose and Scope** — the PO language and domain (from the registry's + `Languages` section, also in the `Language` and `Domain` Metadata rows) and + what the dictionary covers. +2. **Dictionary** — one row per term: + `PO term | Language | IT term | Definition | Used as PO term in | Used as IT term in`. + The definition is written in the PO language. "Used as PO term in" and + "Used as IT term in" list artifact types (for example `DM` and `OC, SD, + DCD, ERD`). +3. **Rules** — the register split (PO term in the Domain Model, use cases and + user stories; IT term in the Operation Contract, Sequence Diagram, Design + Class Diagram and ERD) and one IT term per PO term. + +One dictionary has one domain: the PO terms are the domain's own words (for +example `medical`), the IT terms are professional IT. A project whose PO terms +come from two domains keeps one dictionary per domain, each with its own +`Domain` row; a term never appears in two. + +Keep the dictionary in step with the Domain Model: a new concept gets a row +in the same change. When the PO language is English, the PO and IT columns can +still differ (a business word against a technical one); keep the file anyway +when the two registers use different words. diff --git a/.agents/skills/artifact/references/DM.md b/.agents/skills/artifact/references/DM.md new file mode 100644 index 0000000..de35ff6 --- /dev/null +++ b/.agents/skills/artifact/references/DM.md @@ -0,0 +1,26 @@ +# Domain Model (DM) + +Cite in `CrossReference` only if the instance exists (`new-artifact.sh` checks this for you): + +- **UC** — Source of every concept (noun phrases) — cite each `UC-*` used +- **UCD** — Scope check: actors/goals the model must cover +- **SSD** — Forward: system operations that act on these concepts + +## Required sections (after Metadata / Version History) + +1. **Purpose and Scope** — which use cases the model covers. +2. **Diagram** — PlantUML class diagram (or linked source) showing + **concepts, attributes and associations only — no operations**. + Business language throughout ("Sale", not "SaleTable"/"SaleClass"). +3. **Concept Table** — `Concept | Definition | Attributes | Source (use + case noun phrase / glossary)`. Every concept traces to a noun in a use + case or glossary. Attributes are simple domain data, not foreign-key-like + references (model those as associations). +4. **Association Table** — `From | Association name (with reading + direction) | To | Multiplicity (both ends)`. All multiplicities present. +5. **Generalizations** — only true "is-a" relationships, never inheritance + for code reuse. + +## Terminology + +Concept names are the PO terms recorded in the dictionary (`DICT`); add a row there for each new concept. diff --git a/.agents/skills/artifact/references/ERD.md b/.agents/skills/artifact/references/ERD.md new file mode 100644 index 0000000..27a98ac --- /dev/null +++ b/.agents/skills/artifact/references/ERD.md @@ -0,0 +1,22 @@ +# Entity Relationship Diagram (ERD) (ERD) + +Cite in `CrossReference` only if the instance exists (`new-artifact.sh` checks this for you): + +- **DCD** — **Required source**: classes/attributes each entity persists; data types must match + +## Required sections (after Metadata / Version History) + +1. **Purpose and Scope**. +2. **Diagram** — PlantUML entity diagram with PK/FK marked on every entity and + cardinality (1:1, 1:N) on every relationship; N:M relationships resolved + through explicit junction entities. +3. **Entity Table** — per entity: `Attribute | Type | PK/FK | Nullable | + Source (DCD class.attribute)`. Types consistent with the DCD; consistent + naming, no implementation-specific abbreviations. +4. **Relationship Table** — `Entity | Cardinality | Entity | FK | Rule`. +5. **Normalization Notes** — 3NF confirmed; any denormalization documented + with its performance justification. + +## Terminology + +Entity and column names follow the IT terms from the dictionary (`DICT`), not the PO terms the Domain Model uses. diff --git a/.agents/skills/artifact/references/GOV.md b/.agents/skills/artifact/references/GOV.md new file mode 100644 index 0000000..d441bc6 --- /dev/null +++ b/.agents/skills/artifact/references/GOV.md @@ -0,0 +1,16 @@ +# Governance / ARB Workflow (GOV) + +One per project: `docs/sqa/governance.md`. Sections: Purpose, ARB Review +Workflow (submission → QC review → `RC-*` record → Go/No-Go → sign-off → +Traceability update), RACI by Artifact Category, Escalation Rules, Cadence. +The template has the standard text; fill the RACI. + +**RACI cells use exact stakeholder IDs from the project's Stakeholder +Analysis (`S`), never role names.** + +Related singletons (edit the existing file, no scaffold needed): +- `PRC` — `framework/process/review-checklist-process.md`, the narrative + review procedure. Framework-level; do not add project data. +- `CSG` — `docs/sqa/coding-standards-governance.md`. Scope is *defining and + governing* (not enforcing) language standards and style guides, as set by + the project Business Case's scope. diff --git a/.agents/skills/artifact/references/KPI.md b/.agents/skills/artifact/references/KPI.md new file mode 100644 index 0000000..7e5b01c --- /dev/null +++ b/.agents/skills/artifact/references/KPI.md @@ -0,0 +1,20 @@ +# KPI Definitions (KPI) + +Cite in `CrossReference` only if the instance exists (`new-artifact.sh` checks this for you): + +- **BC** — The Success Criteria row each KPI is aligned to (`[BC-001]`) + +## Required sections (after Metadata / Version History) + +1. **Purpose** — which Business Case success criteria this document + operationalizes. +2. **KPI Definitions** — one row per KPI: `KPI ID | Name | SMART statement | + Baseline | Target | Business Case Success Criterion | Owner | Frequency & + Method | Data Source`. +3. **Thresholds** — per KPI: acceptable / at-risk / failing bounds. +4. **Reporting** — where results are reported and to whom. + +Rules: every KPI is SMART (reject goals/activities like "improve quality"); +baseline *and* target are both present; `Owner` is a stakeholder ID from +the project's Stakeholder Analysis (e.g. `S07`), never free text; give KPIs stable IDs (`KPI-01`, …) so +Milestones can cite them. diff --git a/.agents/skills/artifact/references/MIL.md b/.agents/skills/artifact/references/MIL.md new file mode 100644 index 0000000..9a8e621 --- /dev/null +++ b/.agents/skills/artifact/references/MIL.md @@ -0,0 +1,48 @@ +# Milestone / Gateway (MIL) + +Cite in `CrossReference` only if the instance exists (`new-artifact.sh` checks this for you): + +- **BC** — The objective / constraint (e.g. project duration) the milestone traces to +- **KPI** — The KPI IDs evaluated at this gate +- **US** — Forward: the user stories (`US-.`) that deliver this gateway + +## Required sections (after Metadata / Version History) + +1. **Purpose** — what decision this gate supports. +2. **Deliverable** — the concrete, tangible output evaluated (never just a date). +3. **Go / No-Go Criteria** — objectively checkable, one per row. +4. **Dependencies** — other milestones that must precede this one. +5. **Traceability** — the Business Case objective and/or KPI ID(s) it maps to. +6. **Ownership** — owner and approving reviewer as `SA` stakeholder IDs. +7. **Target Date** — consistent with Business Case constraints. +8. **Tasks** — the implementation-level breakdown for this phase, one row + per task: `# | Task | Summary | Needs its own Use Case/User Story? | + Reference`. `Task` is a short title (becomes the Issue title on sync); + `Summary` is one to three sentences of real context — what the task + actually involves and why, grounded in this project's own documents, not + a restatement of the title — so someone reading the Issue on Gitea/GitHub + understands it without opening this file (becomes the Issue body). + +## Breaking a phase into tasks + +Not every task needs a use case — only model one when the task is something +a user, or another system, actually does: + +- **Needs a use case/user story** — "User resets password", "Admin exports + customer report", "Payment service processes refund". Set the column to + `Yes` and put the `US-…`/`UC-…` ID in Reference. +- **Plain task, no use case** — "Refactor authentication middleware", "Add + database index", "Upgrade React version", "Fix null-pointer bug", "Add + unit tests", "Configure CI pipeline", "Optimize SQL query". Set the column + to `No` and leave Reference blank, or point at the design artifact it + implements (`DCD-…`, `OC-…`). + +The hierarchy is: Business goal → Feature/requirement → Use case/user story +→ Tasks. The use case explains *why* a feature exists; tasks explain *how* +the team implements it — most tasks stay at that level. + +## Syncing to Gitea/GitHub + +Each `MIL-*` gateway becomes one Milestone on the git host; its `## Tasks` +row become Issues assigned to that milestone. Use the `project-planning` +skill and `framework/scripts/sync-project.sh` — do not create these by hand. diff --git a/.agents/skills/artifact/references/OC.md b/.agents/skills/artifact/references/OC.md new file mode 100644 index 0000000..3b74009 --- /dev/null +++ b/.agents/skills/artifact/references/OC.md @@ -0,0 +1,27 @@ +# Operation Contract (OC) + +Cite in `CrossReference` only if the instance exists (`new-artifact.sh` checks this for you): + +- **SSD** — **Required source**: each contract traces to exactly one SSD message +- **DM** — Classes/associations named in pre/postconditions +- **SD** — Forward: the design realizing each contract's postconditions + +## Required sections (after Metadata / Version History) + +One block per system operation, each containing: + +1. **Operation** — complete signature: name, parameter types, return type + (must match the SSD message). +2. **Cross References** — the SSD message it traces to (one contract per + message) and the Domain Model concepts touched. +3. **Preconditions** — required state before execution, expressed in Domain + Model terms. +4. **Postconditions** — state changes only, in Larman's style: *instance + created / instance associated / attribute modified*. Declarative ("what"), + never algorithmic ("how"); avoid vague text like "system processes the + request". +5. **Exceptions** — error conditions, each with the failing precondition. + +## Terminology + +Use the IT terms from the dictionary (`DICT`), not the PO terms the Domain Model uses. diff --git a/.agents/skills/artifact/references/PP.md b/.agents/skills/artifact/references/PP.md new file mode 100644 index 0000000..80784fe --- /dev/null +++ b/.agents/skills/artifact/references/PP.md @@ -0,0 +1,64 @@ +# Project Plan (PP) + +One per project: `docs/project-plan.md`. Schedules the phases (`MIL-*` +gateways) over the Business Case's timeline/duration constraint. + +Cite in `CrossReference` only if the instance exists (`new-artifact.sh` +checks this for you): + +- **BC** — the duration/constraint and objectives the plan schedules against +- **SA** — the communication cadence (e.g. sync frequency) the phase length follows +- **MIL** — every phase gateway the plan schedules (add each as it is created) +- **US** — the gateway user stories, once they exist + +## Required sections (after Metadata / Version History) + +1. **Purpose** — what the plan schedules and over what constraint. +2. **Planning Assumptions** — start date, phase length, any resolved + conflicts the phasing follows (cite `SA`/`BC` where relevant). +3. **Gateway Schedule** — one row per phase: `Gateway | Document | Window | + Decision date | Owner | Stories | Main deliverable | Milestone`. One row + per `MIL-*`. `Milestone` links to that phase's Gitea/GitHub Milestone once + `sync-project.sh` has created it (see "Phases, tasks and the git host" + below); leave it blank until then. +4. **Timeline diagram** — a PlantUML Gantt chart, one bar per phase plus a + milestone marker per Go/No-Go decision. +5. **Scope Coverage** — maps each Business Case scope item to the gateway + that delivers it. +6. **Dependencies** — the gateway order (usually a simple chain) and what a + No-Go does to later dates. +7. **Plan Risks** — risks specific to the plan (schedule slip, dependency + risk), separate from the Business Case's own Risks table. +8. **Open Issues** — anything unresolved (start date to confirm, ambiguous + targets, missing checklists needed by a later phase). + +## Phases, tasks and the git host + +Each phase is a `MIL-*` gateway document (see `references/MIL.md`), which +also holds that phase's task breakdown in its own `## Tasks` section. The +Project Plan does not repeat the tasks — it only lists the phases and their +schedule, plus a link to each phase's Milestone once synced (see above). Use +the `project-planning` skill to break a phase into tasks and sync phases (as +Milestones) and tasks (as Issues) to Gitea/GitHub: + +```bash +bash framework/scripts/sync-project.sh # dry run — prints the plan, no network calls +bash framework/scripts/sync-project.sh --apply # creates/updates Milestones and Issues +``` + +`--apply` needs a token: `GITEA_TOKEN` (Gitea, a personal access token — not +a deploy key) or `gh auth login` (GitHub). `GITEA_TOKEN` can come from a +`.env` file at the project root (copy `.env.example`, never commit it). If +`.env` is missing or has no token when a sync is needed, ask the user for +one and create `.env` from `.env.example` with it rather than skipping the +sync or inventing a value. + +After a real `--apply` run, copy each Milestone's URL into the Gateway +Schedule's `Milestone` column (a content update, not a status change — it +does not need a new `## Version History` row). + +## Validating + +`PP` has no QC checklist yet (open item) — validate a plan against the +Business Case constraint it schedules and against `## Go / No-Go Criteria` +in each `MIL-*` it lists, rather than a dedicated checklist. diff --git a/.agents/skills/artifact/references/QC.md b/.agents/skills/artifact/references/QC.md new file mode 100644 index 0000000..8395a60 --- /dev/null +++ b/.agents/skills/artifact/references/QC.md @@ -0,0 +1,55 @@ +# Quality Criteria checklist (QC) + +A QC checklist is the reusable review checklist for one artifact **type**. +It lives in the framework (`framework/qc/qc-.md`), is +project-independent, and **must never name or link a real artifact +instance** (no `[BC-001]`, no `RC-*`, no stakeholder IDs). Refer to types +generically ("the Stakeholder Analysis"). + +- **ID:** `QC--` (e.g. `QC-BC-001`); the version starts + at `001` and only changes when the checklist itself is revised. +- **Create:** `new-artifact.sh QC --id QC-XX-001 --file framework/qc/qc-.md + --cite QC-=framework/qc/qc-.md ...` +- **CrossReference:** the QC checklists immediately backward and forward in + Larman's chain, in both directions: + +``` +QC-SA → QC-BC → { QC-BMC, QC-BPMN, QC-KPI } → QC-MIL +QC-BC, QC-SA → QC-UCD → { QC-US, QC-UC } +QC-UC → QC-DM → QC-SSD → QC-OC → QC-SD → QC-DCD → QC-ERD +QC-ADR ↔ QC-DCD, QC-ERD +QC-DCD, QC-ADR → { QC-PY, QC-CL, QC-CPP, QC-CS } (language code checklists) +``` + +## Cross-cutting checklists + +`QC-LANG-001` (`framework/qc/qc-language-domain.md`, language and domain) is +not tied to one artifact type. Apply it together with the checklist of the +artifact's own type to every type the registry marks "Written in the PO +language"; the review record (`RC`) lists both checklists and keeps the rows of +each. It has an ID in the `QC-` form like the others, but the short +name `LANG` is not an artifact type: there is no `LANG` instance, template or +catalog row. Add another cross-cutting checklist only when a rule applies to +several types and does not belong in any one of their checklists. + +## Version History statuses + +The statuses are `Proposed`, `Accepted`, `Rejected` and `Deprecated`, as for every +artifact type (rule in the `artifact` skill, "Version History rule"). + +## Required sections (after Metadata / Version History) + +- **Purpose** — why this type matters, what decision it supports. +- **Quality Criteria Checklist** — `# | Criterion | Level | ISO/IEC 25010 + Characteristic(s) | Notes`. `Level` is `Mandatory` (baseline every instance + must meet) or `Optional` (advanced, may be deferred); a checklist with an + extra column (e.g. `Format`) keeps `Level` right after `Criterion`. Every criterion is tagged with at least one of + the eight ISO/IEC 25010:2023 characteristics (Functional Suitability, + Performance Efficiency, Compatibility, Usability, Reliability, Security, + Maintainability, Portability). Never add an untagged criterion. +- **Common Defects** — anti-patterns a reviewer rejects on sight. +- **Traceability Rule** — Backward / Forward bullets with the same `[QC-*]` + labels as `CrossReference`. + +Also add an entry to `framework/CHANGELOG.md`. Reviews of real instances are +recorded in the project as `RC-*` records, not in the checklist. diff --git a/.agents/skills/artifact/references/RC.md b/.agents/skills/artifact/references/RC.md new file mode 100644 index 0000000..e89eed5 --- /dev/null +++ b/.agents/skills/artifact/references/RC.md @@ -0,0 +1,45 @@ +# SQA Review Record (RC) + +One record per review of a specific artifact instance against its QC +checklist. Create one for **every** artifact instance in the project. + +- **File:** `docs/sqa/reviews/rc--.md` +- **ID:** `RC-NNN`, sequential across all artifact types (the registry's + Next Available Version for `RC`). +- **Create:** `new-artifact.sh RC --file docs/sqa/reviews/rc-NNN-.md + --cite = --cite QC--001=framework/qc/.md` + +## Required sections (after Metadata / Version History) + +- **Artifact Under Review** — links to the instance and to the QC checklist + used, the scope (`full review`, or `delta re-review` with the criteria + covered, the reason and the earlier record), the artifact's language and + domain (its `Language` and `Domain` rows, `n/a` for a technical type) and + the language reviewer (a stakeholder ID, or `none`). +- **Checklist Results** — `# | Criterion | Status (Pass/Fail/N-A) | + Evidence/Notes`, one row per criterion copied from the QC checklist, in + the same order. +- **Language and Domain Results** — only for an artifact of a type written in + the PO language: the rows of `QC-LANG-001`, same columns and order. `N-A` is + not allowed for criteria 3, 5 and 9. +- **Overall Verdict** — Go / Go-with-conditions / No-Go, with rationale. +- **Action Items** — `Action | Owner | Due`. `Owner` is a stakeholder ID from + the project's Stakeholder Analysis, never a role name. Every `Fail` and + every condition gets an item. + +## After the review + +- The reviewer must not be the artifact's author (see governance). For a + PO-language artifact the reviewer must read its language and know its + domain, or a second reviewer, the language reviewer, does and is named on + the record; see `process/review-checklist-process.md`. +- The record is in English. Quote evidence that is the artifact's own wording + in its language, with a short gloss. +- Add or update the instance's row in the Traceability Matrix, including + this `RC-*` in "Last Reviewed". +- On **Go**, set the reviewed artifact's latest `## Version History` row to + `Accepted` and the row before it to `Deprecated` (`Approved` is not a + status). On Go-with-conditions the status stays `Proposed` until the action + items are closed. If the change is refused for good, set the row to + `Rejected` (the earlier `Accepted` row stays). +- Step-by-step narrative: `framework/process/review-checklist-process.md`. diff --git a/.agents/skills/artifact/references/SA.md b/.agents/skills/artifact/references/SA.md new file mode 100644 index 0000000..a7307d4 --- /dev/null +++ b/.agents/skills/artifact/references/SA.md @@ -0,0 +1,27 @@ +# Stakeholder Analysis (SA) + +Cite in `CrossReference` only if the instance exists (`new-artifact.sh` checks this for you): + +- **BC** — Business Case objectives each stakeholder concern traces to (Business Goal Alignment section) + +## Required sections (after Metadata / Version History) + +1. **Purpose** — why the analysis exists and the methodology it follows. +2. **Stakeholder Summary Table** — `ID | Name | Role/Title | Organization | + Power Level | Interest Level | Quadrant | Primary Concern (Business + Language)`. Every row fully filled; no unclassified stakeholder. +3. **Power/Interest Classification Rationale** — narrative per quadrant, + consistent with the table. +4. **Primary Concerns and FURPS+ Mapping** — each concern in business + language *and* mapped to a FURPS+ attribute. +5. **Communication Requirements** — channel, frequency, deliverable type, + tied to a project phase or milestone. +6. **Conflicting Interests and Mitigations** — every conflict has a + mitigation. +7. **Traceability Analysis** — stakeholder → actor/use case mapping, and + business-goal alignment citing Business Case (`[BC-001]`) objectives. +8. **Sign-Off**. + +Stakeholder IDs (`S01`, `S02`, …) are **stable: never renumbered or reused**. +Every other artifact cites them for RACI, ownership and review assignment +(`AGENTS.md` rule 3). Add new stakeholders with the next free `S`. diff --git a/.agents/skills/artifact/references/SD.md b/.agents/skills/artifact/references/SD.md new file mode 100644 index 0000000..a8b2476 --- /dev/null +++ b/.agents/skills/artifact/references/SD.md @@ -0,0 +1,26 @@ +# Sequence Diagram (Design) (SD) + +Cite in `CrossReference` only if the instance exists (`new-artifact.sh` checks this for you): + +- **OC** — **Required source**: the contract whose postconditions each diagram realizes +- **DCD** — Forward: classes/methods these messages become + +## Required sections (after Metadata / Version History) + +One block per realized Operation Contract: + +1. **Realizes** — the contract (`[OC-…]`) and its operation name. +2. **Diagram** — PlantUML sequence diagram: sync (solid filled arrow), + async (open arrow), returns (dashed); activations matching the call + nesting; `create` / `destroy` shown for transient objects; + `loop` / `alt` / `opt` fragments for conditional/repeated behavior. +3. **Pattern Annotations** — table `Pattern (GRASP/GoF) | Applied to | + Rationale`. Patterns are labelled, never implicit. +4. **Postcondition Coverage** — `Postcondition | Satisfied by message`; + every postcondition of the contract must be covered. +5. **Responsibility Check** — a short note showing no god-object receives + all messages (low coupling, high cohesion). + +## Terminology + +Use the IT terms from the dictionary (`DICT`), not the PO terms the Domain Model uses. diff --git a/.agents/skills/artifact/references/SSD.md b/.agents/skills/artifact/references/SSD.md new file mode 100644 index 0000000..16e8f94 --- /dev/null +++ b/.agents/skills/artifact/references/SSD.md @@ -0,0 +1,21 @@ +# System Sequence Diagram (SSD) (SSD) + +Cite in `CrossReference` only if the instance exists (`new-artifact.sh` checks this for you): + +- **UC** — **Required source** of every SSD: cite the use case (name and ID) it depicts +- **DM** — Concepts behind message parameters / returned values +- **OC** — Forward: contract per system operation shown + +## Required sections (after Metadata / Version History) + +1. **Source Use Case** — name and ID (`[UC-…]`) and the specific scenario. +2. **Diagram** — PlantUML sequence diagram with just the actor and + `:System`; **no internal objects**. Dashed return arrows for operations + that produce a result. One scenario per diagram — separate diagrams for + alternate/exception flows (or state them out of scope). +3. **System Operations Table** — `Step | Message (verb phrase) | Parameters + | Return | Use case step`. Messages match the use case's main success + scenario step-for-step; justify any deviation. Message names become the + Operation Contract names. +4. **Lifecycle Notes** — creation/destruction of the System instance where + relevant (session/transaction scope). diff --git a/.agents/skills/artifact/references/TM.md b/.agents/skills/artifact/references/TM.md new file mode 100644 index 0000000..e09ceef --- /dev/null +++ b/.agents/skills/artifact/references/TM.md @@ -0,0 +1,18 @@ +# Traceability Matrix (TM) + +One matrix per project: `docs/sqa/traceability-matrix.md`. It makes the +Business Case's cross-artifact traceability target measurable. + +## Required sections (after Metadata / Version History) + +- **Purpose**. +- **Traceability Table** — one row per artifact instance: + `Artifact Instance | Type | Language | Domain | Upstream (Backward Link) | + Downstream (Forward Link) | Last Reviewed (RC-ID)`. `Language` and `Domain` + copy the artifact's Metadata rows so a reviewer can pick the right reviewer + from the matrix; they are `-` for a technical type (OC, SD, DCD, ERD, ADR, + TM, RC, QC, source code). `check-languages.sh --list` prints the same values. + Add or update a row whenever an instance is created or reviewed. +- **Coverage Notes** — which types have no instance yet, and how to read + `-`: in Upstream it means foundational; in Downstream it means nothing + is built on it yet; in Last Reviewed it means no `RC-*` exists yet. diff --git a/.agents/skills/artifact/references/TRN.md b/.agents/skills/artifact/references/TRN.md new file mode 100644 index 0000000..64b2b7d --- /dev/null +++ b/.agents/skills/artifact/references/TRN.md @@ -0,0 +1,18 @@ +# Reviewer Training (TRN) + +The reusable training material for reviewers. It mitigates the "resistance to +standardized reviews" risk of the Business Case. Framework-level, like `PRC`: +no project data, no stakeholder IDs, no links to project artifacts. The +*record* that a session happened (date, attendees, result) is a project +document, written after the session. + +- **File:** `framework/process/reviewer-training.md` (singleton, version `001`). +- **Create:** `new-artifact.sh TRN`. +- **CrossReference:** `PRC` (the procedure the training teaches). + +## Required sections (after Metadata / Version History) + +Purpose, Audience and Prerequisites, Learning Objectives, Agenda (modules with +minutes), Module Notes, Exercises (each with input and expected result), +Assessment (how and pass criteria), Session Record (what to capture). +Exercises use a seeded, generic example, not a real project artifact. diff --git a/.agents/skills/artifact/references/TRR.md b/.agents/skills/artifact/references/TRR.md new file mode 100644 index 0000000..70f083e --- /dev/null +++ b/.agents/skills/artifact/references/TRR.md @@ -0,0 +1,23 @@ +# Reviewer Training Record (TRR) + +The project's record that a reviewer training session happened: the evidence +that mitigates the "resistance to standardized reviews" risk and satisfies a +"training delivered and recorded" gateway criterion. It records one session +of the framework's training material (`TRN`); it holds project data +(stakeholder IDs, dates), so it lives in the project, not in the framework. + +- **File:** `docs/sqa/reviewer-training-record.md` (one per project; add a new + row under `## Attendees and Assessment` and a Version History row for each + further session). +- **Create:** `new-artifact.sh TRR --file docs/sqa/reviewer-training-record.md + --cite TRN-001=framework/process/reviewer-training.md`. +- **CrossReference:** `TRN` (the material that was taught). + +## Required sections (after Metadata / Version History) + +Session (material, date, facilitator, format), Attendees and Assessment +(stakeholder IDs, attended, Pass or Not yet against the assessment in the +material, and the languages the reviewer reads and the domains they know, for +example `da, en; it, medical`: the review process uses it to choose a reviewer +for a PO-language artifact), Feedback, Follow-ups (action, owner as a stakeholder ID, due). +Fill the record after the session; never before. diff --git a/.agents/skills/artifact/references/UC.md b/.agents/skills/artifact/references/UC.md new file mode 100644 index 0000000..fcb5da8 --- /dev/null +++ b/.agents/skills/artifact/references/UC.md @@ -0,0 +1,35 @@ +# Use Case (UC) + +Cite in `CrossReference` only if the instance exists (`new-artifact.sh` checks this for you): + +- **UCD** — Actor and use-case names must match it exactly +- **US** — Stories this use case decomposes into +- **SA** — Stakeholders & Interests — cite S-IDs +- **DM** — Forward: concepts derived from this use case's nouns +- **SSD** — Forward: the SSD depicting this use case's main scenario + +## Location + +`docs/uc-NNN/uc.md`, one folder per use case (create with +`new-artifact.sh UC --file docs/uc-NNN/uc.md`). The artifacts this use case +affects are saved in the same folder; see the `project-planning` skill, "Use +cases get their own folder". + +## Required sections (after Metadata / Version History) + +Pick the format explicitly (`Format: Brief | Casual | Fully Dressed`) and +state the **scope/level** (summary, user-goal, subfunction). Always: primary +actor, pre/postconditions, goal-perspective wording with no UI or +implementation detail. + +- **Brief** — a single paragraph summarizing only the main success scenario. +- **Casual** — informal multi-paragraph narrative; may mention some + alternate flows. +- **Fully Dressed** — all sections, in order: Scope, Level, Primary Actor, + Stakeholders and Interests (cite `SA` S-IDs), Preconditions, + Postconditions (success guarantee), Main Success Scenario (numbered + steps), Extensions / Alternative Flows (reference `<>` / + `<>` use cases), Special Requirements / Business Rules (per step), + Open Issues. + +Title and actor names must match `UCD` and `US` exactly. diff --git a/.agents/skills/artifact/references/UCD.md b/.agents/skills/artifact/references/UCD.md new file mode 100644 index 0000000..c7ce5bd --- /dev/null +++ b/.agents/skills/artifact/references/UCD.md @@ -0,0 +1,24 @@ +# Use Case Diagram (UCD) + +Cite in `CrossReference` only if the instance exists (`new-artifact.sh` checks this for you): + +- **SA** — Each actor traces to a stakeholder need — cite S-IDs +- **BC** — Scope / objectives the boundary reflects +- **US** — Forward: stories whose role must match an actor here +- **UC** — Forward: the use cases detailing each goal shown + +## Required sections (after Metadata / Version History) + +1. **Purpose and Scope** — the system boundary in words. +2. **Diagram** — actors with correct stereotypes (`<>`, + `<>`), a labelled system boundary, `<>` / `<>` + used per UML 2.5.1 (not as generic "uses"). Embed PlantUML or link the + diagram source; no UI or implementation detail. +3. **Actor Table** — `Actor | Stereotype | Stakeholder ID (SA) | Goals + (use cases)`. No orphan actors: every actor appears in at least one use + case. +4. **Use Case Table** — `Use Case | Actor(s) | Goal`, names as **verb + phrases describing actor goals** ("Place Order"), not system operations + ("Validate Input"). +5. **Relationships** — every `<>` / `<>` with a one-line + justification. diff --git a/.agents/skills/artifact/references/US.md b/.agents/skills/artifact/references/US.md new file mode 100644 index 0000000..554f93a --- /dev/null +++ b/.agents/skills/artifact/references/US.md @@ -0,0 +1,22 @@ +# User Story (US) + +Cite in `CrossReference` only if the instance exists (`new-artifact.sh` checks this for you): + +- **UCD** — The story's role must match an actor defined here +- **UC** — The use case each story traces to +- **BC** — Objective / epic the story ultimately supports +- **MIL** — The gateway (epic) each story delivers — one or more stories per gateway + +## Required sections (after Metadata / Version History) + +1. **Purpose and Scope** — the epic(s) covered. +2. **Story List** — each story with a stable ID `US-.` (e.g. + `US-001.01`, so it cannot be confused with the document ID `US-001`): + - Statement: **As a** ``, **I want** ``, **so that** + `` — one goal per story, no implementation detail. + - **Acceptance Criteria** — clear and testable (Given/When/Then works). + - **Traces to** — the use case (`UC-…`) or epic it comes from; a gateway + (`MIL-…`) is an epic. + - **Size** — fits a single iteration. +3. **INVEST Check** — one line confirming Independent, Negotiable, + Valuable, Estimable, Small, Testable (flag any exception with reason). diff --git a/.agents/skills/artifact/templates/ADR.md b/.agents/skills/artifact/templates/ADR.md new file mode 100644 index 0000000..05a4acf --- /dev/null +++ b/.agents/skills/artifact/templates/ADR.md @@ -0,0 +1,42 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Proposed | @AUTHOR@ | | Initial version | pending | + +Allowed Status values: `Proposed`, `Accepted`, `Rejected`, `Deprecated`, `Superseded by ADR-NNNN`. + +--- + +## Context + + + +## Decision + + + +## Consequences + +**Positive:** + +- + +**Negative:** + +- + +## Affected Artifacts + +- [] — , or a single "-" if none + +--- + +@LINKS@ diff --git a/.agents/skills/artifact/templates/BC.md b/.agents/skills/artifact/templates/BC.md new file mode 100644 index 0000000..653014e --- /dev/null +++ b/.agents/skills/artifact/templates/BC.md @@ -0,0 +1,72 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | +| Language | @LANGUAGE@ | +| Domain | @DOMAIN@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Proposed | @AUTHOR@ | | Initial version | pending | + +--- + +## Executive Summary + +## Methodological and Standards Foundation + +## Problem Statement + +## Business Opportunity + +## Objectives + +## Scope + +### In Scope + +### Out of Scope + +## Expected Benefits + +### Tangible Benefits + +### Intangible Benefits + +## Strategic Alignment + +## Success Criteria + +| # | Criterion | Target | Measure | +| --- | --- | --- | --- | + +## Risks + +| Risk | Impact | Mitigation | +| --- | --- | --- | + +## Assumptions + +## Constraints + +## Cost–Benefit Assessment + +| Costs | Benefits | +| --- | --- | + +## Stakeholders + +| Stakeholder ID (SA) | Interest in this project | +| --- | --- | + +## Recommendation + + — + +--- + +@LINKS@ diff --git a/.agents/skills/artifact/templates/BMC.md b/.agents/skills/artifact/templates/BMC.md new file mode 100644 index 0000000..a4f14fb --- /dev/null +++ b/.agents/skills/artifact/templates/BMC.md @@ -0,0 +1,115 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | +| Language | @LANGUAGE@ | +| Domain | @DOMAIN@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Proposed | @AUTHOR@ | | Initial version | pending | + +--- + +## Purpose / Scope + +Operationalizes: ([BC-]) + +## Canvas + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Key PartnersKey ActivitiesValue PropositionsCustomer RelationshipsCustomer Segments
+ +
    +
  • +
+ 		+ +
    +
  • +
+ 		+ +
    +
  • +
+ 		+ +
    +
  • +
+ 		+ +
    +
  • +
+
Key ResourcesChannels
+ +
    +
  • +
+ 		+ +
    +
  • +
+
Cost StructureRevenue Streams
+ +
    +
  • +
+ 		+ +
    +
  • +
+
+ + +## Assumptions + +| # | Assumption | How it can be tested | +| --- | --- | --- | + +## Consistency Check + +--- + +@LINKS@ diff --git a/.agents/skills/artifact/templates/BPMN.md b/.agents/skills/artifact/templates/BPMN.md new file mode 100644 index 0000000..0cbe4ce --- /dev/null +++ b/.agents/skills/artifact/templates/BPMN.md @@ -0,0 +1,43 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | +| Language | @LANGUAGE@ | +| Domain | @DOMAIN@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Proposed | @AUTHOR@ | | Initial version | pending | + +--- + +## Purpose and Business Goal + +Realizes: ([BC-]) + +## Participants + +| Pool / Lane | Participant | Stakeholder ID (SA) | +| --- | --- | --- | + +## Process Diagram + + + +## Element Table + +| Element | Type (event / activity / gateway) | Lane | Description | +| --- | --- | --- | --- | + +## Path Coverage + +| Path | Start event | End event | +| --- | --- | --- | + +--- + +@LINKS@ diff --git a/.agents/skills/artifact/templates/DCD.md b/.agents/skills/artifact/templates/DCD.md new file mode 100644 index 0000000..7ee1c17 --- /dev/null +++ b/.agents/skills/artifact/templates/DCD.md @@ -0,0 +1,50 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Proposed | @AUTHOR@ | | Initial version | pending | + +--- + +## Purpose and Scope + +## Diagram + +```plantuml +@startuml +class Controller { + -repo : Repository + +operationName(param : Type) : ReturnType +} +class Entity +Controller --> Entity : uses +@enduml +``` + +## Class Table + +| Class | Refines (Domain Model concept) | Responsibility | Attributes | Operations | +| --- | --- | --- | --- | --- | + +## Method Traceability + +| Method signature | Operation Contract / SD message | +| --- | --- | + +## Pattern Annotations + +| Pattern | Classes | Rationale | +| --- | --- | --- | + +## Dependency Check + +--- + +@LINKS@ diff --git a/.agents/skills/artifact/templates/DICT.md b/.agents/skills/artifact/templates/DICT.md new file mode 100644 index 0000000..da5f2b8 --- /dev/null +++ b/.agents/skills/artifact/templates/DICT.md @@ -0,0 +1,37 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | +| Language | @LANGUAGE@ | +| Domain | @DOMAIN@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Proposed | @AUTHOR@ | | Initial version | pending | + +--- + +## Purpose and Scope + +Maps each Product Owner (PO) term to its professional IT term. PO language: +. + +## Dictionary + +| PO term | Language | IT term | Definition | Used as PO term in | Used as IT term in | +| --- | --- | --- | --- | --- | --- | +| | | | | DM | OC, SD, DCD, ERD | + +## Rules + +- The Domain Model, use cases and user stories use the PO term; the Operation + Contract, Sequence Diagram, Design Class Diagram and ERD use the IT term. +- One IT term per PO term and one PO term per IT term; no synonyms. + +--- + +@LINKS@ diff --git a/.agents/skills/artifact/templates/DM.md b/.agents/skills/artifact/templates/DM.md new file mode 100644 index 0000000..8e46404 --- /dev/null +++ b/.agents/skills/artifact/templates/DM.md @@ -0,0 +1,56 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | +| Language | @LANGUAGE@ | +| Domain | @DOMAIN@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Proposed | @AUTHOR@ | | Initial version | pending | + +--- + +## Purpose and Scope + +Covers: + +## Diagram + +Concepts, attributes and associations only — no operations. + +```plantuml +@startuml +class Order { + date + status +} +class Customer { + name +} +Customer "1" --> "0..*" Order : places +@enduml +``` + +## Concept Table + +| Concept | Definition | Attributes | Source (use case / glossary) | +| --- | --- | --- | --- | + +## Association Table + +| From | Association (reading direction) | To | Multiplicity | +| --- | --- | --- | --- | + +## Generalizations + +| General | Specializations | Is-a justification | +| --- | --- | --- | + +--- + +@LINKS@ diff --git a/.agents/skills/artifact/templates/ERD.md b/.agents/skills/artifact/templates/ERD.md new file mode 100644 index 0000000..4a3c5bc --- /dev/null +++ b/.agents/skills/artifact/templates/ERD.md @@ -0,0 +1,53 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Proposed | @AUTHOR@ | | Initial version | pending | + +--- + +## Purpose and Scope + +## Diagram + +```plantuml +@startuml +hide circle +entity CUSTOMER { + * id : int <> + -- + name : string +} +entity ORDER { + * id : int <> + -- + * customer_id : int <> +} +CUSTOMER ||--o{ ORDER : places +@enduml +``` + +## Entity Table + +### + +| Attribute | Type | PK/FK | Nullable | Source (DCD class.attribute) | +| --- | --- | --- | --- | --- | + +## Relationship Table + +| Entity | Cardinality | Entity | FK | Rule | +| --- | --- | --- | --- | --- | + +## Normalization Notes + +--- + +@LINKS@ diff --git a/.agents/skills/artifact/templates/GOV.md b/.agents/skills/artifact/templates/GOV.md new file mode 100644 index 0000000..8f58c1d --- /dev/null +++ b/.agents/skills/artifact/templates/GOV.md @@ -0,0 +1,70 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | +| Language | @LANGUAGE@ | +| Domain | @DOMAIN@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Proposed | @AUTHOR@ | | Initial version | pending | + +--- + +## Purpose + +Defines how this project applies Quality Criteria (QC) checklists to real +artifact instances, producing SQA Review Records and Go/No-Go decisions. + +## ARB Review Workflow + +1. **Submission** — the artifact owner submits an instance for review, + identifying its type's QC checklist (`framework/qc/qc-*.md`). +2. **QC Checklist Review** — the assigned reviewer (see RACI) applies the + checklist criterion by criterion. +3. **Review Record** — the reviewer documents the outcome as an SQA Review + Record (`RC-*` under `docs/sqa/reviews/`). +4. **Go/No-Go Decision** — the Accountable role for the artifact category + decides; contested or cross-cutting cases escalate to the ARB Chair. +5. **Sign-off** — on **Go**, the artifact's `## Version History` gets an + `Accepted` row (the previous row becomes `Deprecated`). On **Go-with-conditions**, status stays `Proposed` until + the Action Items are closed. On **No-Go**, the artifact returns to its + owner. +6. **Traceability Update** — the Traceability Matrix is updated with the + instance and its `RC-*` reference. + +## RACI by Artifact Category + +Fill every cell with stakeholder IDs from the Stakeholder Analysis (`S`), +never role names. + +| Artifact Category | Responsible (runs the review) | Accountable (Go/No-Go owner) | Consulted | Informed | +| --- | --- | --- | --- | --- | +| Strategic (Stakeholder Analysis, Business Case, BMC) | S | S | S | S | +| Process/Business (BPMN, KPI, Milestones/Gateways) | S | S | S | S | +| Requirements (Use Case Diagram, User Story, Use Case) | S | S | S | S | +| Modeling/Design (Domain Model, SSD, Operation Contract, Sequence Diagram, DCD, ERD) | S | S | S | S | + +Cross-cutting escalations and disputed verdicts are Accountable to the ARB +Chair (`S`), overriding the category-level Accountable role. + +## Escalation Rules + +- A **No-Go** verdict, or any disagreement between the Responsible reviewer + and the category's Accountable owner, escalates to the ARB Chair. +- A reviewer may not review an instance they authored. +- Repeated No-Go verdicts (2 or more) on the same artifact type trigger a + review of the corresponding `QC-*` checklist itself. + +## Cadence + +- Reviews are triggered per artifact instance as it is produced or revised. +- QC checklists are reviewed annually. + +--- + +@LINKS@ diff --git a/.agents/skills/artifact/templates/KPI.md b/.agents/skills/artifact/templates/KPI.md new file mode 100644 index 0000000..2cfad59 --- /dev/null +++ b/.agents/skills/artifact/templates/KPI.md @@ -0,0 +1,37 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | +| Language | @LANGUAGE@ | +| Domain | @DOMAIN@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Proposed | @AUTHOR@ | | Initial version | pending | + +--- + +## Purpose + + + +## KPI Definitions + +| KPI ID | Name | SMART statement | Baseline | Target | Business Case success criterion | Owner (S-ID) | Frequency & method | Data source | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| KPI-01 | | | | | | | | | + +## Thresholds + +| KPI ID | Acceptable | At risk | Failing | +| --- | --- | --- | --- | + +## Reporting + +--- + +@LINKS@ diff --git a/.agents/skills/artifact/templates/MIL.md b/.agents/skills/artifact/templates/MIL.md new file mode 100644 index 0000000..794a2d7 --- /dev/null +++ b/.agents/skills/artifact/templates/MIL.md @@ -0,0 +1,60 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | +| Language | @LANGUAGE@ | +| Domain | @DOMAIN@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Proposed | @AUTHOR@ | | Initial version | pending | + +--- + +## Purpose + + + +## Deliverable + + + +## Go / No-Go Criteria + +| # | Criterion (objectively checkable) | Go | No-Go | +| --- | --- | --- | --- | + +## Dependencies + +| Depends on | Reason | +| --- | --- | + +## Traceability + +| Business Case objective / KPI / user story | Reference | +| --- | --- | + +## Ownership + +| Role | Stakeholder ID (SA) | +| --- | --- | +| Owner | | +| Approving reviewer | | + +## Target Date + +YYYY-MM-DD — + +## Tasks + +| # | Task | Summary | Needs its own Use Case/User Story? | Reference | +| --- | --- | --- | --- | --- | +| 1 | | | No | | + +--- + +@LINKS@ diff --git a/.agents/skills/artifact/templates/OC.md b/.agents/skills/artifact/templates/OC.md new file mode 100644 index 0000000..87a4220 --- /dev/null +++ b/.agents/skills/artifact/templates/OC.md @@ -0,0 +1,41 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Proposed | @AUTHOR@ | | Initial version | pending | + +--- + +## Contract: + +| Item | Value | +| --- | --- | +| Operation | `operationName(param: Type): ReturnType` | +| Traces to | in [SSD-] | +| Domain Model concepts | ([DM-]) | + +**Preconditions** + +- + +**Postconditions** + +- A instance was created. +- was associated with . +- . was set to . + +**Exceptions** + +| Condition (failing precondition) | Outcome | +| --- | --- | + +--- + +@LINKS@ diff --git a/.agents/skills/artifact/templates/PP.md b/.agents/skills/artifact/templates/PP.md new file mode 100644 index 0000000..1e3487b --- /dev/null +++ b/.agents/skills/artifact/templates/PP.md @@ -0,0 +1,63 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | +| Language | @LANGUAGE@ | +| Domain | @DOMAIN@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Proposed | @AUTHOR@ | | Initial version | pending | + +--- + +## Purpose + + + +## Planning Assumptions + +- Week 1 starts ; the plan ends by , per the Business Case constraint. +- Phase length: . + +## Gateway Schedule + +| Gateway | Document | Window | Decision date | Owner | Stories | Main deliverable | Milestone | +| --- | --- | --- | --- | --- | --- | --- | --- | +| | [MIL-] | | | | | | | + +```plantuml +@startgantt +Project starts +[Phase 1] starts and ends +[Phase 1 Go/No-Go] happens +@endgantt +``` + +## Scope Coverage + +| Business Case scope item | Gateway | +| --- | --- | + +## Dependencies + +``` + → → ... +``` + +## Plan Risks + +| Risk | Impact | Mitigation | +| --- | --- | --- | + +## Open Issues + +- + +--- + +@LINKS@ diff --git a/.agents/skills/artifact/templates/QC.md b/.agents/skills/artifact/templates/QC.md new file mode 100644 index 0000000..4e37af3 --- /dev/null +++ b/.agents/skills/artifact/templates/QC.md @@ -0,0 +1,42 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Proposed | @AUTHOR@ | | Initial version | pending | + +Allowed Status values: `Proposed`, `Accepted`, `Rejected`, `Deprecated`. The latest reviewed row is `Accepted`; the row before it is `Deprecated`. + +--- + +## Purpose + + + +## Quality Criteria Checklist + +Level: **Mandatory** criteria are the baseline every instance must meet; **Optional** criteria are advanced and may be deferred. + +| # | Criterion | Level | ISO/IEC 25010 Characteristic(s) | Notes | +| --- | --- | --- | --- | --- | +| 1 | | Mandatory | | | + +## Common Defects + +- +- + +## Traceability Rule + +- Backward: ([QC--]) +- Forward: ([QC--]) + +--- + +@LINKS@ diff --git a/.agents/skills/artifact/templates/RC.md b/.agents/skills/artifact/templates/RC.md new file mode 100644 index 0000000..a4dcdb7 --- /dev/null +++ b/.agents/skills/artifact/templates/RC.md @@ -0,0 +1,51 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Proposed | @AUTHOR@ | | Initial version | pending | + +--- + +## Artifact Under Review + +- Instance reviewed: [] +- Checklist used: [] (`QC--`, e.g. `QC-BC-001`) +- Scope: , reason, earlier record []> +- Language and domain: / (the artifact's Metadata rows), or `n/a` for a technical type +- Language reviewer: , or `none` when the reviewer reads the language and knows the domain + +## Checklist Results + +| # | Criterion | Status | Evidence/Notes | +| --- | --- | --- | --- | +| 1 | | Pass/Fail/N-A | | + +## Language and Domain Results + +Only for an artifact of a type written in the PO language: the rows of +`QC-LANG-001`, in order. Delete this section for a technical type. + +| # | Criterion | Status | Evidence/Notes | +| --- | --- | --- | --- | +| 1 | | Pass/Fail/N-A | | + +## Overall Verdict + + — + +## Action Items + +| Action | Owner | Due | +| --- | --- | --- | +| | | | + +--- + +@LINKS@ diff --git a/.agents/skills/artifact/templates/SA.md b/.agents/skills/artifact/templates/SA.md new file mode 100644 index 0000000..2b18ecc --- /dev/null +++ b/.agents/skills/artifact/templates/SA.md @@ -0,0 +1,56 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | +| Language | @LANGUAGE@ | +| Domain | @DOMAIN@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Proposed | @AUTHOR@ | | Initial version | pending | + +--- + +## Purpose + + + +## Stakeholder Summary Table + +| ID | Name | Role/Title | Organization | Power Level | Interest Level | Quadrant | Primary Concern (Business Language) | +| --- | --- | --- | --- | --- | --- | --- | --- | +| S01 | | | | HIGH / MEDIUM / LOW | HIGH / MEDIUM / LOW | Manage Closely / Keep Satisfied / Keep Informed / Monitor | | + +## Power/Interest Classification Rationale + +## Primary Concerns and FURPS+ Mapping + +| ID | Concern | FURPS+ attribute | +| --- | --- | --- | + +## Communication Requirements + +| ID | Channel | Frequency | Deliverable | Phase / Milestone | +| --- | --- | --- | --- | --- | + +## Conflicting Interests and Mitigations + +| Conflict | Stakeholders | Mitigation | +| --- | --- | --- | + +## Traceability Analysis + +### Business Goal Alignment + +| Stakeholder | Concern | Business Case objective | +| --- | --- | --- | + +## Sign-Off + +--- + +@LINKS@ diff --git a/.agents/skills/artifact/templates/SD.md b/.agents/skills/artifact/templates/SD.md new file mode 100644 index 0000000..70a02af --- /dev/null +++ b/.agents/skills/artifact/templates/SD.md @@ -0,0 +1,47 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Proposed | @AUTHOR@ | | Initial version | pending | + +--- + +## Sequence: + +**Realizes:** `operationName` in [OC-] + +### Diagram + +```plantuml +@startuml +participant ":Controller" as C +participant ":Collaborator" as X +C -> X : message(args) +activate X +X --> C : result +deactivate X +@enduml +``` + +### Pattern Annotations + +| Pattern (GRASP / GoF) | Applied to | Rationale | +| --- | --- | --- | + +### Postcondition Coverage + +| Postcondition (from contract) | Satisfied by message | +| --- | --- | + +### Responsibility Check + +--- + +@LINKS@ diff --git a/.agents/skills/artifact/templates/SSD.md b/.agents/skills/artifact/templates/SSD.md new file mode 100644 index 0000000..7856d4c --- /dev/null +++ b/.agents/skills/artifact/templates/SSD.md @@ -0,0 +1,42 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | +| Language | @LANGUAGE@ | +| Domain | @DOMAIN@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Proposed | @AUTHOR@ | | Initial version | pending | + +--- + +## Source Use Case + + ([UC-]) — scenario:
+ +## Diagram + +```plantuml +@startuml +actor Actor as A +participant ":System" as S +A -> S : verbPhrase(param) +S --> A : result +@enduml +``` + +## System Operations + +| Step | Message | Parameters | Return | Use case step | +| --- | --- | --- | --- | --- | + +## Lifecycle Notes + +--- + +@LINKS@ diff --git a/.agents/skills/artifact/templates/TM.md b/.agents/skills/artifact/templates/TM.md new file mode 100644 index 0000000..6e08eba --- /dev/null +++ b/.agents/skills/artifact/templates/TM.md @@ -0,0 +1,30 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Proposed | @AUTHOR@ | | Initial version | pending | + +--- + +## Purpose + +Tracks backward/forward links between artifact instances so that the Business Case's +cross-artifact traceability success criterion is measurable. A row is added or +updated whenever an artifact instance is created or reviewed. + +## Traceability Table + +| Artifact Instance | Type | Language | Domain | Upstream (Backward Link) | Downstream (Forward Link) | Last Reviewed (RC-ID) | +| --- | --- | --- | --- | --- | --- | --- | +| [] | | | | [] | [] | [] | + +--- + +@LINKS@ diff --git a/.agents/skills/artifact/templates/TRN.md b/.agents/skills/artifact/templates/TRN.md new file mode 100644 index 0000000..8dd6170 --- /dev/null +++ b/.agents/skills/artifact/templates/TRN.md @@ -0,0 +1,60 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Proposed | @AUTHOR@ | | Initial version | pending | + +--- + +## Purpose + + + +## Audience and Prerequisites + + + +## Learning Objectives + +By the end, a participant can: + +- + +## Agenda + +| Module | Topic | Minutes | +| --- | --- | --- | +| 1 | | | + +## Module Notes + +### Module 1: + + + +## Exercises + +### Exercise 1: + + + +## Assessment + + + +## Session Record + +What is recorded after each session, in the project (never in the framework): +date, facilitator, attendees, result against the assessment, feedback and +follow-ups. + +--- + +@LINKS@ diff --git a/.agents/skills/artifact/templates/TRR.md b/.agents/skills/artifact/templates/TRR.md new file mode 100644 index 0000000..f73f357 --- /dev/null +++ b/.agents/skills/artifact/templates/TRR.md @@ -0,0 +1,43 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Proposed | @AUTHOR@ | | Initial version | pending | + +--- + +## Session + +| Item | Value | +| --- | --- | +| Training material | [] | +| Date | | +| Facilitator | | +| Format and place | | + +## Attendees and Assessment + +| Stakeholder ID (SA) | Attended | Assessment (Pass / Not yet) | Languages and domains | Notes | +| --- | --- | --- | --- | --- | +| | | | | | + +## Feedback + + + +## Follow-ups + +| Action | Owner | Due | +| --- | --- | --- | +| | | | + +--- + +@LINKS@ diff --git a/.agents/skills/artifact/templates/UC.md b/.agents/skills/artifact/templates/UC.md new file mode 100644 index 0000000..b8b3388 --- /dev/null +++ b/.agents/skills/artifact/templates/UC.md @@ -0,0 +1,57 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | +| Language | @LANGUAGE@ | +| Domain | @DOMAIN@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Proposed | @AUTHOR@ | | Initial version | pending | + +--- + +**Format:** Brief | Casual | Fully Dressed (delete the unused sections below) + +## Brief + + + +## Casual + + + +## Fully Dressed + +- **Scope:** +- **Level:** summary | user-goal | subfunction +- **Primary Actor:** ]> +- **Stakeholders and Interests:** + - — +- **Preconditions:** +- **Postconditions (success guarantee):** + +### Main Success Scenario + +1. +2. + +### Extensions (Alternative / Exception Flows) + +- 2a. : + 1. (`<>` / `<>` ) + +### Special Requirements / Business Rules + +| Step | Rule | +| --- | --- | + +### Open Issues + +--- + +@LINKS@ diff --git a/.agents/skills/artifact/templates/UCD.md b/.agents/skills/artifact/templates/UCD.md new file mode 100644 index 0000000..2fd7867 --- /dev/null +++ b/.agents/skills/artifact/templates/UCD.md @@ -0,0 +1,52 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | +| Language | @LANGUAGE@ | +| Domain | @DOMAIN@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Proposed | @AUTHOR@ | | Initial version | pending | + +--- + +## Purpose and Scope + + + +## Diagram + +```plantuml +@startuml +left to right direction +actor "Name" as A1 +rectangle "System Name" { + usecase "Verb-phrase goal" as UC1 +} +A1 --> UC1 +@enduml +``` + +## Actor Table + +| Actor | Stereotype | Stakeholder ID (SA) | Goals (use cases) | +| --- | --- | --- | --- | + +## Use Case Table + +| Use Case | Actor(s) | Goal | +| --- | --- | --- | + +## Relationships + +| From | Relationship (`<>` / `<>`) | To | Justification | +| --- | --- | --- | --- | + +--- + +@LINKS@ diff --git a/.agents/skills/artifact/templates/US.md b/.agents/skills/artifact/templates/US.md new file mode 100644 index 0000000..f0fa723 --- /dev/null +++ b/.agents/skills/artifact/templates/US.md @@ -0,0 +1,38 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | +| Language | @LANGUAGE@ | +| Domain | @DOMAIN@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Proposed | @AUTHOR@ | | Initial version | pending | + +--- + +## Purpose and Scope + +## Story List + +### @ID@.01 — + +**As a** ]>, **I want** , **so that** . + +**Acceptance Criteria** + +- Given , when , then . + +| Traces to | Size | INVEST exceptions | +| --- | --- | --- | +| [UC-] or [MIL-] | fits one iteration | none | + +## INVEST Check + +--- + +@LINKS@ diff --git a/.agents/skills/coding-conventions/SKILL.md b/.agents/skills/coding-conventions/SKILL.md new file mode 100644 index 0000000..d207710 --- /dev/null +++ b/.agents/skills/coding-conventions/SKILL.md @@ -0,0 +1,98 @@ +--- +name: coding-conventions +description: Programming conventions for writing or reviewing source code — naming, layout, formatting and language idioms — for Python, C, C++, C# and Shell (bash). Use when writing, editing, reviewing or refactoring code in one of those languages, choosing names, setting up a formatter/linter config, or adding conventions for another language. Holds the rules shared by every language and points to a per-language sub-skill. +--- + +# Coding Conventions + +One skill for all languages. This file holds what is true in every language; +everything specific to one language is in a sub-skill that is read only when +that language is in hand: + +| Language | Sub-skill | QC checklist | +| --- | --- | --- | +| Python | `references/python.md` | `framework/qc/qc-programming-python.md` (`QC-PY-001`) | +| C | `references/c.md` | `framework/qc/qc-programming-c.md` (`QC-CL-001`) | +| C++ | `references/cpp.md` | `framework/qc/qc-programming-cpp.md` (`QC-CPP-001`) | +| C# | `references/csharp.md` | `framework/qc/qc-programming-csharp.md` (`QC-CS-001`) | +| Shell (bash) | `references/shell.md` | `framework/qc/qc-programming-shell.md` (`QC-SH-001`) | + +Read the sub-skill for the language you are working in, then write or review +the code. To review, use the language's QC checklist and record the result as +an `RC-*` (see the `artifact` skill). + +## Precondition: a planned task + +Before writing or editing code under `src/` or `tests/`, name the task row +(`MIL-NNN`, task N) or the synced issue, and the use case or design artifact +it implements, or say it is a plain technical task. If you cannot, refuse and +use the `project-planning` skill instead (rule: `framework/process/plan-first-gate.md`). +The task's milestone must be `Accepted` with a `Go` review record; if it is +still `Proposed`, or its latest review is conditional or No-Go, stop and say so. +Reviewing code needs no task. Before the pull request, code is reviewed against +the checklist of its language (`qc-programming-*`) and the result is recorded +as an `RC-*`. + +## Rules for every language + +1. **The existing code wins.** In a file or project that already has a + convention, follow it, even if the sub-skill says otherwise. Do not mix + styles within a file; do not reformat code you are not changing. +2. **Naming follows the language, not your habits.** Casing differs per + language (table below). Never carry one language's casing into another. +3. **A name says what, not how.** Name by purpose in the domain's language + (IT Professional English, as the registry's `Languages` section says), not by + type or implementation (`customer_list`, not `arr2`). +4. **Length follows scope.** Short names (`i`, `n`) only for tiny scopes; + wider scope, longer name. No abbreviations except ones the whole domain + uses (`id`, `url`, `http`). +5. **Booleans read as a question:** `is_valid`, `has_items`, `can_retry` + (cased per language). No negated names (`is_not_ready`). +6. **Functions are verbs, types are nouns.** A function that returns a value + without side effects may be a noun (`total`, `Total`) where the language + community does so. +7. **Formatting is done by the formatter,** not by hand and not in review + comments. Each sub-skill names the formatter and linter; commit its + configuration file with the code. +8. **Comments say why,** never what the code already says. Public APIs get + the language's documentation-comment form. +9. **No dead or commented-out code, no unexplained magic numbers.** Name the + constant. +10. **Errors are handled or propagated, never swallowed.** Each sub-skill says + how its language does this. + +## Casing at a glance + +| Element | Python | C | C++ | C# | +| --- | --- | --- | --- | --- | +| Type / class | `PascalCase` | `snake_case_t` | `PascalCase` | `PascalCase` | +| Function / method | `snake_case` | `snake_case` | `snake_case` | `PascalCase` | +| Variable / parameter | `snake_case` | `snake_case` | `snake_case` | `camelCase` | +| Constant | `UPPER_SNAKE` | `UPPER_SNAKE` | `kPascalCase` | `PascalCase` | +| Private member | `_leading` | file-scope `static` | `trailing_` | `_camelCase` | +| Namespace / module | `snake_case` module | `mod_` prefix | `snake_case` | `PascalCase` | +| File | `snake_case.py` | `snake_case.c/.h` | `snake_case.cpp/.h` | `PascalCase.cs` | + +The table is a summary; the sub-skill is authoritative. Shell (bash) is not in +the table: functions and variables are `snake_case`, constants and environment +variables `UPPER_SNAKE`, files `kebab-case.sh`. + +## Governance boundary + +Conventions are **defined and governed** here but **not enforced** by this +framework: writing a linter or CI job that enforces them is outside the +framework's scope. The formatter and linter names in each sub-skill are the +recommended tools, not a pipeline. A new or changed convention follows the +process in the project's Coding Standards Governance document and is recorded +in `framework/CHANGELOG.md`. No project data belongs in this skill. + +## Adding a language + +1. Add `references/.md` with these sections: Standard base, Naming, + Formatting, Language rules, Errors, Tests, Tooling. +2. Add `framework/qc/qc-.md` (`QC--001`) using the `QC` type + of the `artifact` skill, tagging every criterion with an ISO/IEC 25010:2023 + characteristic and a Level. +3. Add the row to the table above, the casing table, and a row for the + language in `framework/registry/artifact-catalog.md`; note it in + `framework/CHANGELOG.md`; run `bash framework/scripts/install-skills.sh`. diff --git a/.agents/skills/coding-conventions/references/c.md b/.agents/skills/coding-conventions/references/c.md new file mode 100644 index 0000000..14375ca --- /dev/null +++ b/.agents/skills/coding-conventions/references/c.md @@ -0,0 +1,71 @@ +# C conventions + +C has no single official style guide. This sub-skill fixes one consistent +style built on common practice; MISRA C and SEI CERT C are the references for +safety-critical or security-sensitive code. + +## Standard base + +ISO C11 or C17 as set by the project's compiler flag (`-std=c11`). Compile +with warnings on (`-Wall -Wextra -Wpedantic`); treat warnings as errors in +release builds. + +## Naming + +| Element | Convention | Example | +| --- | --- | --- | +| Function, variable, parameter | `snake_case` | `parse_header`, `byte_count` | +| Public symbol | module prefix plus `snake_case` (C has no namespaces) | `stay_reader_open()` | +| File-local function / variable | `static`, no prefix needed | `static int next_token(...)` | +| Type (`struct`, `enum`, `typedef`) | `snake_case_t`, module prefix for public types | `stay_reader_t` | +| Enum constant, macro, constant | `UPPER_SNAKE` with the module prefix | `STAY_READER_OK` | +| Header / source file | `snake_case.h` / `snake_case.c`, same base name | `stay_reader.h` | +| Header guard | `MODULE_FILE_H` (or `#pragma once` if the project allows) | `STAY_READER_H` | + +- Do not use reserved identifiers: a leading underscore followed by an + uppercase letter, any double underscore, or a leading underscore at file + scope. +- POSIX reserves the `_t` suffix; keep the module prefix on public types so + they cannot collide. +- Macros are a last resort; prefer `static inline` functions and `enum` or + `const` values. + +## Formatting + +- One formatter configuration for the project (`clang-format`); 4 spaces (or + the project's setting), no tabs mixed in. +- Braces on every `if`, `else`, `for`, `while`, even for one statement. +- One declaration per line; declare variables at first use, initialised. +- Headers: include what you use, only what you use; public headers are + self-contained; add `extern "C"` guards when C++ code consumes them. + +## Language rules + +- Check every return value that can fail; check every allocation. +- Every `malloc`/`open`/`lock` has one clear owner and one matching release; + release on every exit path (single exit or `goto cleanup`). +- Use `size_t` for sizes and indices, fixed-width types (``) for + data layout, `const` wherever data is not modified, `restrict` only with + care. +- Bounds are explicit: pass a length with every buffer; use `snprintf`, + never `sprintf`, `strcpy` or `gets`. +- No undefined behaviour: no signed overflow, no out-of-range shifts, no use + after free, no uninitialised reads. +- Avoid global mutable state; if unavoidable, `static` and documented. + +## Errors + +Return a status code (an `enum`) or `-1`/`NULL` plus an error out-parameter; +document which in the header. Never ignore a failing call. Read `errno` +immediately after the failing call. + +## Tests + +A unit-test framework (for example Unity or CMocka); run under sanitizers +(`-fsanitize=address,undefined`) in at least one build. + +## Tooling + +`clang-format`, `clang-tidy` or `cppcheck`, compiler warnings, sanitizers. + +Review with `QC-CL-001`. diff --git a/.agents/skills/coding-conventions/references/cpp.md b/.agents/skills/coding-conventions/references/cpp.md new file mode 100644 index 0000000..8e164ab --- /dev/null +++ b/.agents/skills/coding-conventions/references/cpp.md @@ -0,0 +1,70 @@ +# C++ conventions + +## Standard base + +ISO C++17 or later as set by the project (`-std=c++20`); the C++ Core +Guidelines are the rule source. C++ has no official naming style, so the +style below is used unless the project already has another (rule 1 of the +overall skill). + +## Naming + +| Element | Convention | Example | +| --- | --- | --- | +| Class, struct, enum, concept, type alias | `PascalCase` | `StayReader`, `Stay` | +| Function, method, variable, parameter | `snake_case` | `read_stays()`, `byte_count` | +| Data member (private) | `snake_case` with trailing underscore | `buffer_` | +| Struct public data member | `snake_case`, no underscore | `check_in` | +| Constant (`constexpr`, namespace-scope `const`) | `kPascalCase` | `kMaxRetries` | +| Enum class value | `PascalCase` | `Status::NotFound` | +| Namespace | short `snake_case`; no `using namespace` in headers | `billing` | +| Template parameter | `PascalCase` | `typename ItemT` | +| Macro | `UPPER_SNAKE` with project prefix; avoid macros | `BILLING_ASSERT` | +| Header / source file | `snake_case.h` / `snake_case.cpp`, same base name | `stay_reader.h` | +| Header guard | `#pragma once` (or `PROJECT_PATH_FILE_H`) | | + +## Formatting + +- `clang-format` with one checked-in config; 4 spaces (or the project's + setting); braces on every control-flow body. +- Include order: matching header, project headers, third party, standard + library; each group sorted. +- One declaration per line; declare at first use, initialise with `{}`. + +## Language rules + +- **Ownership:** RAII everywhere. No owning raw pointers, no naked + `new`/`delete`; use `std::unique_ptr` by default, `std::shared_ptr` only for + real shared ownership, created with `std::make_unique`/`make_shared`. +- Follow the rule of zero; if you define one of destructor, copy or move, + define or delete all five. +- Pass by `const&` (large, read-only) or by value (small or sink); use + `std::span` and `std::string_view` for non-owning views, `std::optional` for + "maybe", `std::variant` for alternatives. +- `const` and `constexpr` by default; mark single-argument constructors + `explicit`; mark `override`/`final`; `[[nodiscard]]` on results that must + be used. +- Prefer algorithms and range-for over hand-written loops; `enum class` over + plain `enum`; `nullptr` over `NULL` or `0`; `using` over `typedef`. +- No C-style casts; use `static_cast` and friends. No mutable global state. +- Headers are self-contained and contain declarations, templates and + `inline` definitions only. + +## Errors + +Use exceptions for exceptional failures, or `std::expected` and error codes +where the project forbids exceptions; one choice per project. Destructors +never throw. Catch by `const&`; never `catch (...)` without rethrowing or +logging. + +## Tests + +GoogleTest, Catch2 or doctest; run under sanitizers (`address`, `undefined`) +in at least one build. + +## Tooling + +`clang-format`, `clang-tidy` with the Core Guidelines checks, compiler +warnings (`-Wall -Wextra -Wpedantic`), sanitizers. + +Review with `QC-CPP-001`. diff --git a/.agents/skills/coding-conventions/references/csharp.md b/.agents/skills/coding-conventions/references/csharp.md new file mode 100644 index 0000000..88abb3b --- /dev/null +++ b/.agents/skills/coding-conventions/references/csharp.md @@ -0,0 +1,72 @@ +# C# conventions + +## Standard base + +Microsoft's C# coding conventions and .NET Framework Design Guidelines, with +the analyzers that ship in the SDK. Target the language version of the +project's `LangVersion` / target framework. + +## Naming + +| Element | Convention | Example | +| --- | --- | --- | +| Namespace | `PascalCase`, matches folder path | `Billing.Stays` | +| Class, struct, record, enum, delegate | `PascalCase` (nouns) | `StayReader` | +| Interface | `I` + `PascalCase` | `IStayReader` | +| Method, property, event, public field | `PascalCase` | `ReadStays()`, `CheckIn` | +| Constant, `static readonly` | `PascalCase` | `MaxRetries` | +| Enum value | `PascalCase`; `[Flags]` enums are plural | `Status.NotFound` | +| Parameter, local variable | `camelCase` | `byteCount` | +| Private / internal field | `_camelCase` | `_buffer` | +| Generic type parameter | `T` or `T` + `PascalCase` | `T`, `TKey` | +| Async method | ends in `Async` | `ReadStaysAsync()` | +| Exception, attribute | end in `Exception` / `Attribute` | `InvalidDateException` | +| Boolean | `Is`, `Has`, `Can` prefix | `IsActive` | +| File | the type's name, one top-level type per file | `StayReader.cs` | + +- Two-letter acronyms are upper case (`IO`); longer ones are `PascalCase` + (`Xml`, `Http`). + +## Formatting + +- `.editorconfig` checked in; `dotnet format` applies it. 4 spaces, Allman + braces, braces on every control-flow body. +- File-scoped namespaces (`namespace X;`); `using` directives outside the + namespace, `System` first. +- `var` when the type is obvious from the right-hand side, explicit type + otherwise. + +## Language rules + +- Enable nullable reference types (`enable`) and treat + nullable warnings as errors; do not suppress with `!` without a comment. +- `IDisposable` owners use `using`; implement the dispose pattern only when + needed. +- `async`/`await` all the way; no `.Result` or `.Wait()`; no `async void` + except event handlers; pass `CancellationToken` through public async APIs. +- Prefer properties over public fields, `readonly` and `init` for + immutability, `record` for value-like data, pattern matching and switch + expressions over long `if` chains. +- LINQ for queries, loops for side effects; do not enumerate a sequence twice. +- String interpolation over concatenation; `StringBuilder` in loops; + `DateTimeOffset` over `DateTime` for points in time; `decimal` for money. +- XML documentation comments (`///`) on public types and members. + +## Errors + +Throw specific exceptions (`ArgumentNullException`, custom types); validate +arguments at the public boundary (`ArgumentNullException.ThrowIfNull`). Catch +the narrowest type; `throw;` (not `throw ex;`) to rethrow. Never an empty +`catch`. + +## Tests + +xUnit, NUnit or MSTest; names like `Method_Condition_Expected`; one behaviour +per test; no dependence on order, time or the network. + +## Tooling + +`dotnet format`, the .NET analyzers (`AnalysisLevel`, `EnforceCodeStyleInBuild`) +and optionally StyleCop.Analyzers, configured in `.editorconfig`. + +Review with `QC-CS-001`. diff --git a/.agents/skills/coding-conventions/references/python.md b/.agents/skills/coding-conventions/references/python.md new file mode 100644 index 0000000..e262961 --- /dev/null +++ b/.agents/skills/coding-conventions/references/python.md @@ -0,0 +1,66 @@ +# Python conventions + +## Standard base + +PEP 8 (style), PEP 257 (docstrings), PEP 484 and later (type hints). Target +the Python version declared in `pyproject.toml`. + +## Naming + +| Element | Convention | Example | +| --- | --- | --- | +| Package / module | short `snake_case` | `billing`, `stay_reader.py` | +| Class, exception | `PascalCase`; exceptions end in `Error` | `StayReader`, `InvalidDateError` | +| Function, method, variable, parameter | `snake_case` | `total_price`, `read_stays()` | +| Constant (module level) | `UPPER_SNAKE` | `MAX_RETRIES` | +| Internal (not public API) | one leading underscore | `_parse_row` | +| Type variable | short `PascalCase`; `_co` / `_contra` for variance | `T`, `KeyT`, `ItemT_co` | +| Boolean | `is_`, `has_`, `can_` prefix | `is_active` | +| Test file / function | `test_.py` / `test__` | `test_total_when_empty` | + +- Avoid name mangling (`__name`) unless you need it to prevent a subclass clash. +- Never use `l`, `O` or `I` as single-letter names. +- Do not shadow builtins (`list`, `id`, `type`); add a trailing underscore + (`type_`) only as a last resort. + +## Formatting + +- 4 spaces, no tabs. Maximum line length set once in the formatter config + (88 with `ruff format`; 79 if the project follows PEP 8 strictly). +- Imports at the top, grouped standard library / third party / local, one + blank line between groups, no wildcard imports. +- Double quotes for strings unless the formatter says otherwise. +- Trailing commas in multi-line literals and calls. + +## Language rules + +- Annotate every function signature (parameters and return, `-> None` too). + Modern syntax: `X | None`, `list[str]`. Avoid `Any` without a comment. +- `pathlib` over `os.path`; f-strings over `%` or `.format`; `enum` over + magic strings; `dataclass` (frozen where possible) over ad-hoc dicts. +- No mutable default arguments; no bare `except:`; no `print` for logging + (use `logging`). +- Use context managers (`with`) for files, locks and connections. +- Prefer comprehensions over `map`/`filter` with lambdas; keep them simple. +- Docstrings (PEP 257) on public modules, classes and functions; say what, + not how. + +## Errors + +Raise specific exceptions; catch the narrowest type; re-raise with +`raise ... from err` to keep the cause. Do not use exceptions for normal +control flow. + +## Tests + +`pytest`; one behaviour per test; `tmp_path` for files; fakes over mocks where +a simple fake is possible; tests do not depend on order or on the network. + +## Tooling + +`ruff` (lint and format) and `mypy --strict` (types), configured in +`pyproject.toml`. Architecture rules (layers, ports, dataframes) are in +`.agents/rules/python.md` and the `python-developer` agent; this sub-skill +covers naming and style only. + +Review with `QC-PY-001`. diff --git a/.agents/skills/coding-conventions/references/shell.md b/.agents/skills/coding-conventions/references/shell.md new file mode 100644 index 0000000..aa8a728 --- /dev/null +++ b/.agents/skills/coding-conventions/references/shell.md @@ -0,0 +1,62 @@ +# Shell conventions (bash) + +## Standard base + +Bash 4 or later, POSIX `test` semantics through `[[ ]]`. Start every script +with `#!/usr/bin/env bash` and `set -euo pipefail`. State the bash version and +the external tools it needs in the header comment. + +## Naming + +| Element | Convention | Example | +| --- | --- | --- | +| Script file | `kebab-case.sh`, executable | `check-plan.sh`, `new-artifact.sh` | +| Function | `snake_case`, a verb | `read_registry`, `die` | +| Local variable, parameter | `snake_case`, declared with `local` | `msgfile`, `changed` | +| Constant, environment variable | `UPPER_SNAKE` | `PLAN_GATE`, `PROJECT_ROOT` | +| Boolean | `is_` / `has_` prefix, value `0` or `1` | `is_enabled=1` | + +- Name a script and its functions by what they do, not how. +- Do not shadow a command with a function of the same name. + +## Formatting + +- 2 spaces, no tabs. One command per line; `then` and `do` on the same line as + `if` and `for`. Keep lines near 80 characters; break long pipelines at `|`. +- Format with `shfmt -i 2 -ci`; lint with `shellcheck`. Commit the project's + `.editorconfig` or `.shellcheckrc` with the code. + +## Language rules + +- **Quote every expansion** (`"$var"`, `"${arr[@]}"`); use arrays, not + space-separated strings, for lists. Use `[[ ]]`, not `[ ]`, and `$(...)`, + not backticks. +- Declare function variables `local`; no globals except constants. +- Parse options with `case` and `shift`, check required arguments with + `"${1:?usage: ...}"`, and print a usage line on bad input. +- Read input with `read -r`; iterate files with globs or `find -print0`, never + by parsing `ls`. +- Use `mktemp` for temporary files and remove them with `trap ... EXIT`; never + a fixed `/tmp` name. + +## Errors and exit codes + +- Errors go to standard error, start with `error:`, say what is wrong and what + to do, and end the script with a non-zero exit code (`die` helper). +- `0` is success, `1` a failed check or bad input, `2` a usage error; document + any other code in the header. +- Never swallow a failure with `|| true` without a comment that says why. + +## Safety + +- A script that changes state outside its own directory defaults to a dry run + or asks for an explicit flag (`--apply`, `--force`); say so in the header. +- Never echo a token or password, put one on a command line, or commit one; + read secrets from the environment or a gitignored file. +- Do not `eval` input; do not build a command from unvalidated text. + +## Tools + +Formatter `shfmt`, linter `shellcheck`, syntax check `bash -n`. These are the +recommended tools, not a pipeline: enforcing them in CI is outside this +framework's scope. diff --git a/.agents/skills/project-planning/SKILL.md b/.agents/skills/project-planning/SKILL.md new file mode 100644 index 0000000..561235c --- /dev/null +++ b/.agents/skills/project-planning/SKILL.md @@ -0,0 +1,283 @@ +--- +name: project-planning +description: Plan a project (or a new phase of one) in phases with tasks, and sync those phases and tasks to Gitea or GitHub as Milestones and Issues. Use when starting a new project, adding or updating a phase/gateway, breaking a phase down into tasks, deciding whether a task needs its own use case or user story, or asked to create/update project milestones or issues on the git host. +--- + +# Project Planning + +Plans a project as phases (gateways), each phase as a set of tasks, and +keeps those phases and tasks in sync with the git host's own project +management (Milestones and Issues). It builds on the `artifact` skill's +`PP` (Project Plan) and `MIL` (Milestone/Gateway) types. + +## Domain language first + +Before planning, find the Product Owner's (PO's) domain language. Take it from +the first of these that states it: + +1. the user's prompt; +2. a file the user included or that the project already has (the `Languages` + section of `docs/artifact-registry.md`). + +If none states it, **ask the user for it** and stop planning until it is +answered; never assume one. Record the answer in the registry's `Languages` +section. The artifact types the registry marks "Written in the PO language" +are written in it, once, with no translated copy. + +## Start here + +Before planning or building anything, check that the baseline exists (the +`docs/artifact-registry.md` rows and files): the Business Case (`BC`), the +Stakeholder Analysis (`SA`), the Project Plan (`PP`) and at least one +milestone (`MIL`). If one is missing, create it first, in that order, with +`new-artifact.sh` (it refuses when a type in the catalog's `Requires` column +is missing). + +Each of these steps ends with a review: the document counts only once its +review record (`RC-*`) says `Go` and its Version History row is `Accepted` +(`process/review-checklist-process.md`). Do not start a step on a document that +is still `Proposed`; ask for the review first. + +A "build X" request is planning-first. Produce the phases, tasks and issues, +show the dry run of `sync-project.sh`, and ask for a go-ahead before any code +is written; running `--apply` is the user's decision. Only the user can waive +the plan, in chat, for that request; the waiver does not carry over. The rule +is defined in `framework/process/plan-first-gate.md`. + +## The hierarchy + +``` +Business goal → Feature/requirement → Use case/user story → Tasks +``` + +The use case/user story explains **why** a feature exists; tasks explain +**how** the team implements it. Not every task needs a use case: + +- **Needs a use case/user story** — the task is something a user, or + another system, actually does: "User resets password", "Admin exports + customer report", "Payment service processes refund". +- **Plain task, no use case** — purely technical/implementation work: + "Refactor authentication middleware", "Add database index", "Upgrade + React version", "Fix null-pointer bug", "Add unit tests", "Configure CI + pipeline", "Optimize SQL query". + +When in doubt, ask: does this row describe a goal an actor is pursuing, or +a step the team takes to build something? Goals get a use case; steps stay +a plain task. + +## Use cases get their own folder + +Each use case lives in `docs/uc-NNN/` (`UC-001` → `docs/uc-001/`), together +with the artifacts that belong to it. Nothing about a use case goes in a +shared `docs/use-cases/` folder. + +1. **Create the folder and the use case:** + `bash framework/scripts/new-artifact.sh UC --file docs/uc-001/uc.md`. +2. **Create only the artifacts this use case affects,** in this order, each in + the same folder with a fixed file name. Skip any it does not touch (no + `erd.md` if nothing is stored; no `dm.md` if it adds no concept). + + | Order | Type | File | Create when the use case… | + | --- | --- | --- | --- | + | 1 | `SSD` | `ssd.md` | has system interaction to show (almost always) | + | 2 | `DM` | `dm.md` | introduces or changes domain concepts | + | 3 | `OC` | `oc.md` | has system operations that change state | + | 4 | `SD` | `sd.md` | needs a collaboration design for an operation | + | 5 | `DCD` | `dcd.md` | adds or changes design classes | + | 6 | `ERD` | `erd.md` | adds or changes persisted data | + + ```bash + bash framework/scripts/new-artifact.sh SSD --file docs/uc-001/ssd.md + bash framework/scripts/new-artifact.sh DM --file docs/uc-001/dm.md --cite UC-001=docs/uc-001/uc.md + ``` + + `new-artifact.sh` cites only the artifacts in the same use-case folder + (and project-level ones); for `DM`, `DCD` and `ERD`, add the use case and + sibling artifacts by hand with `--cite`. Each gets its own ID (the next + version in the registry, e.g. `DM-002`) and its own `RC-*` review. +3. **Reconcile with the project models.** The use-case artifacts are a scoped + view; the project-level `docs/domain-model.md`, `docs/dcd.md` and + `docs/erd.md` are the consolidated truth. When the use case's `DM`, `DCD` + or `ERD` are done, compare each with its project-level document: + - add the new concepts, classes, attributes and entities; change the ones + the use case modified; + - keep names identical to the existing ones, and resolve any conflict + with another use case's model instead of duplicating the element; + - give each project-level document a new `## Version History` row (Change: + which use case caused it), and create it from the first use case's + document if it does not exist yet; + - if nothing needs to change, say so in the use case's task and PR + description ("project DM/DCD/ERD unchanged: "). + +## Planning a project (or a new phase) + +1. **Phases are gateways.** Each phase is a `MIL-*` document (the `artifact` + skill's `MIL` type): purpose, deliverable, Go/No-Go criteria, dependencies, + ownership, target date. Create one with + `bash framework/scripts/new-artifact.sh MIL --file docs/milestones/mil--.md`. +2. **The plan schedules the phases.** `docs/project-plan.md` (the `artifact` + skill's `PP` type) lists every phase with its window and owner, and holds + the overall timeline diagram. Create it once with + `bash framework/scripts/new-artifact.sh PP`. +3. **Break each phase into tasks.** In the phase's `## Tasks` section, add + one row per task using the hierarchy rule above. Tasks that need a use + case or user story get one created first (`UC`/`US` types; a use case + follows "Use cases get their own folder" below), then are referenced from + the Tasks row; plain tasks just describe the work. +4. **Sync to the git host.** Run the sync tool (below) to create or update + the corresponding Milestones and Issues. Do this whenever a phase or its + tasks change — the tool is idempotent (matches by title, never creates a + duplicate). + +## Syncing to Gitea/GitHub + +```bash +bash framework/scripts/sync-project.sh # prints the plan only — no network calls +bash framework/scripts/sync-project.sh --milestone MIL-002 # limit to one phase +bash framework/scripts/sync-project.sh --apply # actually create/update on the git host +``` + +- **Default is a dry run**: it parses `docs/milestones/mil-*.md` and prints + what would be created or updated. Nothing is sent anywhere. +- **`--apply`** performs the real requests. It needs: + - **Gitea** (default — detected from `origin`'s hostname): `GITEA_TOKEN` + env var, a personal access token. This is an HTTP API call (milestones, + issues) — a deploy key cannot be used, since deploy keys only + authenticate SSH git transport (clone/fetch/push), not the REST API. + Scope the token to issues only if your Gitea version supports scoped + tokens, rather than a full-account one. + - **GitHub** (detected when `origin` is on github.com, or pass + `--host github`): the `gh` CLI, already logged in (`gh auth login`). +- **`--with-project`** additionally tries to create/attach a Kanban Project + board. This is best-effort: some Gitea versions (confirmed on 1.27.3) show + Projects/Kanban only in the web UI and expose **no REST API for it at + all**, so this always fails there — check your server's own + `https:///swagger.v1.json` for any `project` path if unsure. GitHub + Projects (v2) needs `gh` with the `project` scope. Either way the script + warns and continues; Milestones and Issues are unaffected. Where there's + no API, create the board by hand at `https://///projects`. +- Read the script's header comment for the full flag list, including + `--owner`, `--repo`, `--api-base` to override auto-detection. + +`--apply` is an outward-facing, hard-to-reverse action (it creates real +Milestones/Issues on the git host) — run it yourself once you're ready, or +ask explicitly for it to be run. + +## Branching before commits + +**Never commit, push or open a PR unless the user asks.** The user reviews +the working-tree changes first; finish the edits, summarise them and stop. +Everything below (branching, closing keywords, resolving commit links, the +PR) describes how to do those steps once the user has asked for them; it is +not permission to start them. + +Never commit directly on `main`. This is enforced locally by a pre-commit +hook (`framework/githooks/pre-commit`) once +`bash framework/scripts/install-git-hooks.sh` has been run in this clone — +run it once per clone; it points `core.hooksPath` at the versioned +`framework/githooks/` instead of the per-clone, untracked `.git/hooks/`. +The hook refuses the commit with a pointer back to this section; a rare, +deliberate exception can bypass it with `ALLOW_MAIN_COMMIT=1 git commit`. + +Before the first commit of a piece of work, create and switch to a new +branch, then commit there: + +```bash +git checkout -b +# ... commits ... +git push -u origin +``` + +- Name the branch for the gateway/task it covers, kebab-case, e.g. + `g2-kpi-bmc-bpmn` or `mil-002-kpi-baseline` — short enough to read in a + PR list, specific enough to say what it's for. +- Open a PR (`gh pr create` on GitHub, or the Gitea equivalent) instead of + merging straight to `main`; this project's own history is a merged PR + per phase (e.g. "Merge pull request 'Close G1 inception baseline...'"), + so keep following that pattern. +- This applies to every commit, not just gateway/task work — if in doubt + whether the current branch is `main`, check (`git branch --show-current`) + before committing. + +## Closing tasks from commits + +When a commit finishes the work for a task that `sync-project.sh` has +already synced as an Issue, reference that Issue number in the commit +message so Gitea/GitHub auto-closes it once that commit lands on the +default branch (`main`) — via the PR merge required by "Branching before +commits" above, not by pushing the closing keyword to a feature branch. +Use `Refs #N` instead when the commit only touches the task without +finishing it — that links the commit without closing. + +- **One issue per commit:** use `Closes #5`. +- **Several issues closed by the same commit:** put one `Closes #N` per + line, not a comma-separated list (`Closes #5, #6, #7` only closed `#5` on + a confirmed live Gitea instance — the comma form is not reliably parsed): + + ``` + Closes #5 + Closes #6 + Closes #7 + ``` +- Get each issue number either from the most recent `sync-project.sh` / + `sync-project.sh --apply` output (it prints `updated issue #N` / + `created issue #N` per task) or, if that's not at hand, from the git + host's issue list for the milestone. +- Match commits to issues by the task row they implement — one task row in + a `MIL-*` document's `## Tasks` section is one Issue, so a commit that + completes that row's work closes that Issue. +- Don't guess an issue number; if it isn't known from a recent sync or a + lookup, ask rather than omit or fabricate one. +- **After pushing a multi-issue closing commit, verify** each issue's state + came back `closed` (e.g. `GET /repos///issues/` with + `GITEA_TOKEN`) rather than assuming the whole list closed; close any that + didn't with a direct `PATCH .../issues/` `{"state":"closed"}` call. + +## Pull requests close the issues they complete + +Every PR must close the Issues its work finishes, so the board matches +reality once it merges. Before opening (or updating) a PR: + +1. **List the issues the branch completes.** Go through the task rows the + branch implements (`git log main..HEAD`, plus the `## Tasks` of the + `MIL-*` it belongs to) and get each Issue number as described in "Closing + tasks from commits". +2. **Put one closing line per issue in the PR description**, one per line, + never comma-separated: + + ``` + Closes #5 + Closes #6 + ``` + + Use `Refs #N` for an issue the PR only touches. A PR that finishes no + issue says so explicitly ("No issue closed: ") instead of saying + nothing. +3. **Ask, don't guess.** If an issue number is unknown or a task is only + partly done, ask rather than omit or invent one. Leave a partly done task + open and note what remains. +4. **After the merge, verify** that each issue is `closed` (the check in + "Closing tasks from commits") and close any stragglers by hand. Also make + sure the finished task rows are reflected in the `MIL-*` document and, when + every task of a phase is closed, that the Milestone is closed too. + +5. **Resolve pending commit links before the PR** (see "Version History rule" + in the `artifact` skill): commit, run + `bash framework/scripts/resolve-pending-commits.sh `, then + commit the result as a follow-up commit. +6. **Never ask for, offer or perform the merge.** A PR needs a reviewer: ask + the user to open the PR / request a review, and stop there. Merging, + enabling auto-merge and "shall I merge?" are not yours to do. + +Closing keywords in the PR description and in commit messages both count on +Gitea and GitHub; they only take effect when the PR merges into the default +branch. + +## Files this skill touches + +- `docs/project-plan.md` — `PP`, via the `artifact` skill. +- `docs/milestones/mil-*.md` — `MIL`, via the `artifact` skill, each with a + `## Tasks` section. +- `docs/uc-NNN/*.md` (the use case and its `SSD`, `DM`, `OC`, `SD`, `DCD`, `ERD`), `docs/user-stories.md` — only for tasks that need one; plus `docs/domain-model.md`, `docs/dcd.md`, `docs/erd.md` when reconciling. +- `framework/scripts/sync-project.sh` — never edited per project; propose + changes upstream in the framework. diff --git a/.claude/skills/.framework-skills b/.claude/skills/.framework-skills new file mode 100644 index 0000000..5dad221 --- /dev/null +++ b/.claude/skills/.framework-skills @@ -0,0 +1,3 @@ +artifact +coding-conventions +project-planning diff --git a/.claude/skills/artifact/SKILL.md b/.claude/skills/artifact/SKILL.md new file mode 100644 index 0000000..283b77d --- /dev/null +++ b/.claude/skills/artifact/SKILL.md @@ -0,0 +1,131 @@ +--- +name: artifact +description: Create, edit or review any project document artifact — Business Case, Stakeholder Analysis, KPI, Business Model Canvas, BPMN, milestones/gateways, use case diagram, user stories, use cases, domain model, SSD, operation contracts, sequence diagrams, DCD, ERD, ADRs, SQA review records, traceability matrix, governance, QC checklists. Scaffolds the file with the correct ID, CrossReference and links, then gives the required sections for that type. +--- + +# Artifact + +Every artifact is a markdown file with `## Metadata` and `## Version History` +tables, a registered short-name ID, and links only at the bottom. Types and +their related types are in `framework/registry/artifact-catalog.md`; this +project's file locations and next versions are in `docs/artifact-registry.md`. + +## Creating an artifact + +1. Find the type's short name (`BC`, `SA`, `MIL`, `DM`, `ADR`, `RC`, …) in + the catalog. If the type is new, add it to the catalog and the registry. +2. Scaffold — this sets the ID, `CrossReference` (only artifacts that exist), + the bottom link block and the registry version: + + ```bash + bash framework/scripts/new-artifact.sh [--file ] [--title ""] [--cite =]... + ``` + + `--file` is required for multi-document types (`MIL`, `UC`, `ADR`, `RC`, + `QC`); single-document types default to the registry's `Primary File`. + The script refuses to overwrite an existing file. +3. Read `framework/.agents/skills/artifact/references/.md` (cite-for + hints and required sections), then fill in the file. Keep the sections in + order and replace every ``. + +## Editing an artifact + +Append a row to `## Version History` on every change (a status change such as +`Proposed` → `Accepted`, or a content change). To re-check `CrossReference`, +run `bash framework/scripts/find-crossreferences.sh `. When the first +instance of a type is created, add it to the `CrossReference` of every +existing artifact that lists that type as a candidate (with a new Version +History row). + +### Version History rule + +The table keeps only the **two latest** changes; git holds the rest. Columns: + +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| 2026-10-01 | Accepted | Jens Tirsvad Nielsen | S02 | Added Risks section
Fixed scope wording | [a1b2c3d] | + +- **Status** — `Proposed`, `Accepted`, `Rejected` or `Deprecated` for every + artifact type (`ADR` also has `Superseded by ADR-NNNN`); `Approved` is not + used. A new row starts `Proposed`. When the review gives Go, that row + becomes `Accepted` and the row before it becomes `Deprecated`, so at most + one row is `Accepted`: the latest reviewed one. If the reviewer refuses the + change for good (not a No-Go that returns it for rework), the row becomes + `Rejected`; the earlier `Accepted` row stays `Accepted` and nothing is + deprecated. +- **Change** — a short summary of what this row changed; several lines are + separated with `
`. +- **Commit** — the commit that made the change, as a reference-style link + defined at the bottom of the file + (`[a1b2c3d]: https://///commit/`; Gitea and + GitHub use the same `/commit/` form). A row cannot contain its own commit + hash, so a new row says `pending` until the commit exists. Leave it + `pending` and do not commit: only when the user asks for a commit, then: + 1. commit the edited documents; + 2. run `bash framework/scripts/resolve-pending-commits.sh ...`, which + replaces `pending` with the link to that commit and adds the definition; + 3. commit the result as a follow-up commit, before opening the PR. Do not + amend: an amend changes the hash, so the link would point at a commit + that is never pushed. +- When adding a third row, delete the oldest row and its now-unused commit + link definition. Never rewrite the content of the two retained rows other + than resolving `pending` and setting Status to `Accepted` / `Deprecated` + after a Go review. +- Every document uses this format, including QC checklists. A file still in the + old four-column format is converted when next edited (old row kept as + `Initial version`, plus a new row for the conversion). + +## Reviewing an artifact + +1. Take the QC checklist named in the catalog (`framework/qc/qc-*.md`). +2. Create the review record: `new-artifact.sh RC …`, following + `references/RC.md`. +3. Add or update the instance's row in the Traceability Matrix. + +## Rules + +- **Links:** all links are reference-style, defined once at the bottom of the + file after a final `---`, labelled by the target's ID (`[SA-001]`), never + inline. No links → omit the block. +- **CrossReference:** cite only artifacts that exist now. Empty if none. +- **People:** use exact stakeholder IDs from the project's Stakeholder + Analysis (`S01`) for owners, reviewers and RACI. Never invent role names. +- **Diagrams** are PlantUML blocks; check them with + `bash framework/scripts/render-diagrams.sh --server ` (or set + `PLANTUML_URL`) before review. +- **QC checklists** are framework files: every criterion is tagged with an + ISO/IEC 25010:2023 characteristic, and they never mention real instances. +- **IDs:** `-`, 3 digits (`BC-001`); `ADR` uses 4 digits; + `RC` is sequential across all types; QC is `QC--`. +- **Language:** the PO language and the register of each artifact type are in + the `Languages` section of `docs/artifact-registry.md` (registers: + `IT Executive English` for high-level, `IT Professional English` for + technical). +- **Language and Domain rows:** every artifact of a type written in the PO + language has `Language` and `Domain` rows in its Metadata table, so a reviewer + sees at once how to read it. `Language` is a BCP 47 code (`da`, `en`); + `Domain` is a value from the domain list in the registry's `Languages` + section (for example `it`, `medical`, `construction`), because the same + language can carry a different professional vocabulary. `new-artifact.sh` + fills both from the registry's `PO language` and `PO domain` settings and + leaves a placeholder (with a warning) when a setting is missing. Technical + types (OC, SD, DCD, ERD, ADR, TM, RC, QC, source code) have no such rows: + they are always professional IT English. To list every document's language + and domain, see `check-languages.sh --list`. +- **One file per artifact:** each type the registry marks "Written in the PO + language" exists once, in that language, under its normal name + (`business-case.md`). There is no translated twin (`business-case.da.md`) + and no authoritative English source; two files drift apart. Use the PO terms + from the dictionary (`DICT`). Types marked "No" (OC, SD, DCD, ERD, ADR, TM, + RC, QC, source code) stay in professional IT English. +- **Structural vocabulary stays English:** Metadata keys, section headings, + IDs and statuses are the same in every language, because the scripts read + them (`find-crossreferences.sh`, `new-artifact.sh`, + `resolve-pending-commits.sh`, `sync-project.sh`, `check-plan.sh`). Only the + content (prose and table cells) is in the PO language. +- **Changing an artifact's language** is a material change: add a Version + History row ("language en to da") and review it again. Git history keeps the + earlier language. +- **Dictionary:** the Domain Model uses the PO term; the Operation Contract, + Sequence Diagram, Design Class Diagram and ERD use the IT term. Every pair is + recorded in `docs/dictionary.md` (`DICT`). diff --git a/.claude/skills/artifact/references/ADR.md b/.claude/skills/artifact/references/ADR.md new file mode 100644 index 0000000..eb9e4c3 --- /dev/null +++ b/.claude/skills/artifact/references/ADR.md @@ -0,0 +1,25 @@ +# Architecture Decision Record (ADR) + +Files: `docs/adr/adr-NNNN-kebab-case-title.md`. `NNNN` is 4-digit and +sequential; the ID is `ADR-NNNN` and must match the filename number (an +intentional exception to the usual 3-digit IDs). Use +`new-artifact.sh ADR --file docs/adr/adr-NNNN-title.md`. + +Cite in `CrossReference` the artifacts this decision is about (pass each +with `--cite =`); ADR has no fixed candidate list. + +## Required sections (after Metadata / Version History) + +- **Context** — the problem, the options evaluated and the forces + (cost, risk, constraints). +- **Decision** — the outcome in one or two sentences, no hedging. +- **Consequences** — two bold labels, **Positive:** and **Negative:**, each + with a bullet list. +- **Affected Artifacts** — other artifacts impacted, as `[ID]` links, or a + single `-` if none. + +Allowed statuses: `Proposed`, `Accepted`, `Rejected`, `Deprecated`, +`Superseded by ADR-NNNN`; no others (an ADR is never `Approved`). Status +changes (`Proposed` → `Accepted` → `Deprecated` / `Superseded by ADR-NNNN`, or +`Proposed` → `Rejected`) are new rows in `## Version History` (only the two +latest are kept; earlier ones stay in git); never rewrite a retained row. diff --git a/.claude/skills/artifact/references/BC.md b/.claude/skills/artifact/references/BC.md new file mode 100644 index 0000000..f3f07da --- /dev/null +++ b/.claude/skills/artifact/references/BC.md @@ -0,0 +1,45 @@ +# Business Case (BC) + +Cite in `CrossReference` only if the instance exists (`new-artifact.sh` checks this for you): + +- **SA** — Stakeholders section — cite S-IDs instead of re-describing roles +- **BMC** — Cost–Benefit Assessment must agree with its cost/revenue blocks +- **BPMN** — Forward: the process that realizes the objectives +- **KPI** — Success Criteria — each criterion is operationalized by a KPI +- **UCD** — Forward: scope expressed as actors and goals + +## Required sections (after Metadata / Version History) + +In this order: + +1. **Executive Summary** — one paragraph framing the problem and the + proposed solution. +2. **Methodological and Standards Foundation** — states the methodology + (e.g. Larman's *Applying UML and Patterns*) and quality standards (e.g. + ISO/IEC 25002/25010/25019) the rest of the document and downstream + artifacts are built on. +3. **Problem Statement** — the recurring problems that justify the project. +4. **Business Opportunity** — what becomes possible if the problem is + solved. +5. **Objectives** — concrete, verifiable statements of what the project + will achieve. +6. **Scope** — split into `## In Scope` and `## Out of Scope` subsections. +7. **Expected Benefits** — split into `### Tangible Benefits` and + `### Intangible Benefits`. +8. **Strategic Alignment** — how the project supports organizational goals. +9. **Success Criteria** — a table with explicit, measurable targets (not + aspirations). +10. **Risks** — a table with `Risk | Impact | Mitigation` columns; every + risk must have a mitigation. +11. **Assumptions** — bullet list, kept distinct from Constraints. +12. **Constraints** — bullet list, kept distinct from Assumptions. +13. **Cost–Benefit Assessment** — a table (`Costs | Benefits`); may be + qualitative if explicitly justified. +14. **Stakeholders** — a table referencing exact stakeholder IDs from the + project's Stakeholder Analysis (e.g. `S01`, `S07`) if `SA` exists per + the CrossReference check above. **Never re-describe stakeholder roles + inline instead of citing their IDs** — this is the single most common + defect found when reviewing Business Cases (see `QC-BC-001`'s Common + Defects). +15. **Recommendation** — a single, unambiguous "proceed" or "do not + proceed" statement. diff --git a/.claude/skills/artifact/references/BMC.md b/.claude/skills/artifact/references/BMC.md new file mode 100644 index 0000000..6fe740d --- /dev/null +++ b/.claude/skills/artifact/references/BMC.md @@ -0,0 +1,21 @@ +# Business Model Canvas (BMC) + +Cite in `CrossReference` only if the instance exists (`new-artifact.sh` checks this for you): + +- **BC** — Objectives the canvas operationalizes; cost/revenue must agree with its Cost–Benefit Assessment +- **SA** — Value Propositions, Customer Segments, Channels — cite S-IDs +- **BPMN** — Key Activities — cite the process that realizes them +- **KPI** — Measures of value proposition / revenue — cite KPI IDs + +## Required sections (after Metadata / Version History) + +1. **Purpose / Scope** — one paragraph. +2. **Canvas** — all 9 building blocks populated, none empty: Key Partners, + Key Activities, Key Resources, Value Propositions, Customer + Relationships, Channels, Customer Segments, Cost Structure, Revenue + Streams. Must stay reviewable as a single, concise overview. +3. **Assumptions** — explicit and testable (how would we know it is wrong?). +4. **Consistency Check** — Revenue Streams vs Cost Structure agree; + Segments/Channels match stakeholder groups from `SA`. + +Cite Business Case objectives (`[BC-001]`) instead of restating them. diff --git a/.claude/skills/artifact/references/BPMN.md b/.claude/skills/artifact/references/BPMN.md new file mode 100644 index 0000000..6c8cda9 --- /dev/null +++ b/.claude/skills/artifact/references/BPMN.md @@ -0,0 +1,22 @@ +# BPMN Process Model (BPMN) + +Cite in `CrossReference` only if the instance exists (`new-artifact.sh` checks this for you): + +- **BC** — The stated business goal/objective the process serves +- **SA** — Participants / lanes — cite S-IDs +- **UCD** — Forward link: actors and goals derived from this process + +## Required sections (after Metadata / Version History) + +1. **Purpose and Business Goal** — the Business Case objective realized + (cite `[BC-001]`). +2. **Participants (Pools / Lanes)** — every participant, mapped to an `SA` + stakeholder ID where one exists. +3. **Process Diagram** — valid BPMN 2.0. Message flows cross pool + boundaries; sequence flows do not. Keep the diagram source next to the + document (BPMN has no native markdown form) so it stays diffable. +4. **Element Table** — `Element | Type | Lane | Description` for every + event, activity and gateway. Every gateway states its type (XOR/AND/OR) + and its matching join. +5. **Path Coverage** — every path runs from a start event to a defined end + event; no dead ends. diff --git a/.claude/skills/artifact/references/DCD.md b/.claude/skills/artifact/references/DCD.md new file mode 100644 index 0000000..c1df83b --- /dev/null +++ b/.claude/skills/artifact/references/DCD.md @@ -0,0 +1,27 @@ +# Design Class Diagram (DCD) (DCD) + +Cite in `CrossReference` only if the instance exists (`new-artifact.sh` checks this for you): + +- **DM** — Concepts each design class refines — names must stay consistent +- **SD** — Messages that become method signatures +- **ERD** — Forward: persistence of the classes' attributes + +## Required sections (after Metadata / Version History) + +1. **Purpose and Scope**. +2. **Diagram** — PlantUML class diagram: visibility markers (`+` `-` `#`) + on every member; association vs aggregation vs composition vs dependency + used per true ownership/lifecycle; multiplicity and navigability on every + association. +3. **Class Table** — `Class | Refines (Domain Model concept) | + Responsibility (one sentence) | Attributes | Operations`. SOLID applied; + no god classes; names consistent with the Domain Model. +4. **Method Traceability** — `Method signature | Operation Contract / SD + message`; every method traces to one. +5. **Pattern Annotations** — `Pattern | Classes | Rationale`, explicit. +6. **Dependency Check** — note confirming no circular class/package + dependencies (or an explicit justification). + +## Terminology + +Class and attribute names are the IT terms from the dictionary (`DICT`), not the PO terms the Domain Model uses. diff --git a/.claude/skills/artifact/references/DICT.md b/.claude/skills/artifact/references/DICT.md new file mode 100644 index 0000000..d9d6872 --- /dev/null +++ b/.claude/skills/artifact/references/DICT.md @@ -0,0 +1,31 @@ +# Domain Dictionary (DICT) + +Cite in `CrossReference` only if the instance exists (`new-artifact.sh` checks this for you): + +- **BC** — The business goals the vocabulary serves +- **SA** — The Product Owner (and other business stakeholders) whose terms are recorded +- **DM** — Concepts whose PO terms are recorded + +## Required sections (after Metadata / Version History) + +1. **Purpose and Scope** — the PO language and domain (from the registry's + `Languages` section, also in the `Language` and `Domain` Metadata rows) and + what the dictionary covers. +2. **Dictionary** — one row per term: + `PO term | Language | IT term | Definition | Used as PO term in | Used as IT term in`. + The definition is written in the PO language. "Used as PO term in" and + "Used as IT term in" list artifact types (for example `DM` and `OC, SD, + DCD, ERD`). +3. **Rules** — the register split (PO term in the Domain Model, use cases and + user stories; IT term in the Operation Contract, Sequence Diagram, Design + Class Diagram and ERD) and one IT term per PO term. + +One dictionary has one domain: the PO terms are the domain's own words (for +example `medical`), the IT terms are professional IT. A project whose PO terms +come from two domains keeps one dictionary per domain, each with its own +`Domain` row; a term never appears in two. + +Keep the dictionary in step with the Domain Model: a new concept gets a row +in the same change. When the PO language is English, the PO and IT columns can +still differ (a business word against a technical one); keep the file anyway +when the two registers use different words. diff --git a/.claude/skills/artifact/references/DM.md b/.claude/skills/artifact/references/DM.md new file mode 100644 index 0000000..de35ff6 --- /dev/null +++ b/.claude/skills/artifact/references/DM.md @@ -0,0 +1,26 @@ +# Domain Model (DM) + +Cite in `CrossReference` only if the instance exists (`new-artifact.sh` checks this for you): + +- **UC** — Source of every concept (noun phrases) — cite each `UC-*` used +- **UCD** — Scope check: actors/goals the model must cover +- **SSD** — Forward: system operations that act on these concepts + +## Required sections (after Metadata / Version History) + +1. **Purpose and Scope** — which use cases the model covers. +2. **Diagram** — PlantUML class diagram (or linked source) showing + **concepts, attributes and associations only — no operations**. + Business language throughout ("Sale", not "SaleTable"/"SaleClass"). +3. **Concept Table** — `Concept | Definition | Attributes | Source (use + case noun phrase / glossary)`. Every concept traces to a noun in a use + case or glossary. Attributes are simple domain data, not foreign-key-like + references (model those as associations). +4. **Association Table** — `From | Association name (with reading + direction) | To | Multiplicity (both ends)`. All multiplicities present. +5. **Generalizations** — only true "is-a" relationships, never inheritance + for code reuse. + +## Terminology + +Concept names are the PO terms recorded in the dictionary (`DICT`); add a row there for each new concept. diff --git a/.claude/skills/artifact/references/ERD.md b/.claude/skills/artifact/references/ERD.md new file mode 100644 index 0000000..27a98ac --- /dev/null +++ b/.claude/skills/artifact/references/ERD.md @@ -0,0 +1,22 @@ +# Entity Relationship Diagram (ERD) (ERD) + +Cite in `CrossReference` only if the instance exists (`new-artifact.sh` checks this for you): + +- **DCD** — **Required source**: classes/attributes each entity persists; data types must match + +## Required sections (after Metadata / Version History) + +1. **Purpose and Scope**. +2. **Diagram** — PlantUML entity diagram with PK/FK marked on every entity and + cardinality (1:1, 1:N) on every relationship; N:M relationships resolved + through explicit junction entities. +3. **Entity Table** — per entity: `Attribute | Type | PK/FK | Nullable | + Source (DCD class.attribute)`. Types consistent with the DCD; consistent + naming, no implementation-specific abbreviations. +4. **Relationship Table** — `Entity | Cardinality | Entity | FK | Rule`. +5. **Normalization Notes** — 3NF confirmed; any denormalization documented + with its performance justification. + +## Terminology + +Entity and column names follow the IT terms from the dictionary (`DICT`), not the PO terms the Domain Model uses. diff --git a/.claude/skills/artifact/references/GOV.md b/.claude/skills/artifact/references/GOV.md new file mode 100644 index 0000000..d441bc6 --- /dev/null +++ b/.claude/skills/artifact/references/GOV.md @@ -0,0 +1,16 @@ +# Governance / ARB Workflow (GOV) + +One per project: `docs/sqa/governance.md`. Sections: Purpose, ARB Review +Workflow (submission → QC review → `RC-*` record → Go/No-Go → sign-off → +Traceability update), RACI by Artifact Category, Escalation Rules, Cadence. +The template has the standard text; fill the RACI. + +**RACI cells use exact stakeholder IDs from the project's Stakeholder +Analysis (`S`), never role names.** + +Related singletons (edit the existing file, no scaffold needed): +- `PRC` — `framework/process/review-checklist-process.md`, the narrative + review procedure. Framework-level; do not add project data. +- `CSG` — `docs/sqa/coding-standards-governance.md`. Scope is *defining and + governing* (not enforcing) language standards and style guides, as set by + the project Business Case's scope. diff --git a/.claude/skills/artifact/references/KPI.md b/.claude/skills/artifact/references/KPI.md new file mode 100644 index 0000000..7e5b01c --- /dev/null +++ b/.claude/skills/artifact/references/KPI.md @@ -0,0 +1,20 @@ +# KPI Definitions (KPI) + +Cite in `CrossReference` only if the instance exists (`new-artifact.sh` checks this for you): + +- **BC** — The Success Criteria row each KPI is aligned to (`[BC-001]`) + +## Required sections (after Metadata / Version History) + +1. **Purpose** — which Business Case success criteria this document + operationalizes. +2. **KPI Definitions** — one row per KPI: `KPI ID | Name | SMART statement | + Baseline | Target | Business Case Success Criterion | Owner | Frequency & + Method | Data Source`. +3. **Thresholds** — per KPI: acceptable / at-risk / failing bounds. +4. **Reporting** — where results are reported and to whom. + +Rules: every KPI is SMART (reject goals/activities like "improve quality"); +baseline *and* target are both present; `Owner` is a stakeholder ID from +the project's Stakeholder Analysis (e.g. `S07`), never free text; give KPIs stable IDs (`KPI-01`, …) so +Milestones can cite them. diff --git a/.claude/skills/artifact/references/MIL.md b/.claude/skills/artifact/references/MIL.md new file mode 100644 index 0000000..9a8e621 --- /dev/null +++ b/.claude/skills/artifact/references/MIL.md @@ -0,0 +1,48 @@ +# Milestone / Gateway (MIL) + +Cite in `CrossReference` only if the instance exists (`new-artifact.sh` checks this for you): + +- **BC** — The objective / constraint (e.g. project duration) the milestone traces to +- **KPI** — The KPI IDs evaluated at this gate +- **US** — Forward: the user stories (`US-.`) that deliver this gateway + +## Required sections (after Metadata / Version History) + +1. **Purpose** — what decision this gate supports. +2. **Deliverable** — the concrete, tangible output evaluated (never just a date). +3. **Go / No-Go Criteria** — objectively checkable, one per row. +4. **Dependencies** — other milestones that must precede this one. +5. **Traceability** — the Business Case objective and/or KPI ID(s) it maps to. +6. **Ownership** — owner and approving reviewer as `SA` stakeholder IDs. +7. **Target Date** — consistent with Business Case constraints. +8. **Tasks** — the implementation-level breakdown for this phase, one row + per task: `# | Task | Summary | Needs its own Use Case/User Story? | + Reference`. `Task` is a short title (becomes the Issue title on sync); + `Summary` is one to three sentences of real context — what the task + actually involves and why, grounded in this project's own documents, not + a restatement of the title — so someone reading the Issue on Gitea/GitHub + understands it without opening this file (becomes the Issue body). + +## Breaking a phase into tasks + +Not every task needs a use case — only model one when the task is something +a user, or another system, actually does: + +- **Needs a use case/user story** — "User resets password", "Admin exports + customer report", "Payment service processes refund". Set the column to + `Yes` and put the `US-…`/`UC-…` ID in Reference. +- **Plain task, no use case** — "Refactor authentication middleware", "Add + database index", "Upgrade React version", "Fix null-pointer bug", "Add + unit tests", "Configure CI pipeline", "Optimize SQL query". Set the column + to `No` and leave Reference blank, or point at the design artifact it + implements (`DCD-…`, `OC-…`). + +The hierarchy is: Business goal → Feature/requirement → Use case/user story +→ Tasks. The use case explains *why* a feature exists; tasks explain *how* +the team implements it — most tasks stay at that level. + +## Syncing to Gitea/GitHub + +Each `MIL-*` gateway becomes one Milestone on the git host; its `## Tasks` +row become Issues assigned to that milestone. Use the `project-planning` +skill and `framework/scripts/sync-project.sh` — do not create these by hand. diff --git a/.claude/skills/artifact/references/OC.md b/.claude/skills/artifact/references/OC.md new file mode 100644 index 0000000..3b74009 --- /dev/null +++ b/.claude/skills/artifact/references/OC.md @@ -0,0 +1,27 @@ +# Operation Contract (OC) + +Cite in `CrossReference` only if the instance exists (`new-artifact.sh` checks this for you): + +- **SSD** — **Required source**: each contract traces to exactly one SSD message +- **DM** — Classes/associations named in pre/postconditions +- **SD** — Forward: the design realizing each contract's postconditions + +## Required sections (after Metadata / Version History) + +One block per system operation, each containing: + +1. **Operation** — complete signature: name, parameter types, return type + (must match the SSD message). +2. **Cross References** — the SSD message it traces to (one contract per + message) and the Domain Model concepts touched. +3. **Preconditions** — required state before execution, expressed in Domain + Model terms. +4. **Postconditions** — state changes only, in Larman's style: *instance + created / instance associated / attribute modified*. Declarative ("what"), + never algorithmic ("how"); avoid vague text like "system processes the + request". +5. **Exceptions** — error conditions, each with the failing precondition. + +## Terminology + +Use the IT terms from the dictionary (`DICT`), not the PO terms the Domain Model uses. diff --git a/.claude/skills/artifact/references/PP.md b/.claude/skills/artifact/references/PP.md new file mode 100644 index 0000000..80784fe --- /dev/null +++ b/.claude/skills/artifact/references/PP.md @@ -0,0 +1,64 @@ +# Project Plan (PP) + +One per project: `docs/project-plan.md`. Schedules the phases (`MIL-*` +gateways) over the Business Case's timeline/duration constraint. + +Cite in `CrossReference` only if the instance exists (`new-artifact.sh` +checks this for you): + +- **BC** — the duration/constraint and objectives the plan schedules against +- **SA** — the communication cadence (e.g. sync frequency) the phase length follows +- **MIL** — every phase gateway the plan schedules (add each as it is created) +- **US** — the gateway user stories, once they exist + +## Required sections (after Metadata / Version History) + +1. **Purpose** — what the plan schedules and over what constraint. +2. **Planning Assumptions** — start date, phase length, any resolved + conflicts the phasing follows (cite `SA`/`BC` where relevant). +3. **Gateway Schedule** — one row per phase: `Gateway | Document | Window | + Decision date | Owner | Stories | Main deliverable | Milestone`. One row + per `MIL-*`. `Milestone` links to that phase's Gitea/GitHub Milestone once + `sync-project.sh` has created it (see "Phases, tasks and the git host" + below); leave it blank until then. +4. **Timeline diagram** — a PlantUML Gantt chart, one bar per phase plus a + milestone marker per Go/No-Go decision. +5. **Scope Coverage** — maps each Business Case scope item to the gateway + that delivers it. +6. **Dependencies** — the gateway order (usually a simple chain) and what a + No-Go does to later dates. +7. **Plan Risks** — risks specific to the plan (schedule slip, dependency + risk), separate from the Business Case's own Risks table. +8. **Open Issues** — anything unresolved (start date to confirm, ambiguous + targets, missing checklists needed by a later phase). + +## Phases, tasks and the git host + +Each phase is a `MIL-*` gateway document (see `references/MIL.md`), which +also holds that phase's task breakdown in its own `## Tasks` section. The +Project Plan does not repeat the tasks — it only lists the phases and their +schedule, plus a link to each phase's Milestone once synced (see above). Use +the `project-planning` skill to break a phase into tasks and sync phases (as +Milestones) and tasks (as Issues) to Gitea/GitHub: + +```bash +bash framework/scripts/sync-project.sh # dry run — prints the plan, no network calls +bash framework/scripts/sync-project.sh --apply # creates/updates Milestones and Issues +``` + +`--apply` needs a token: `GITEA_TOKEN` (Gitea, a personal access token — not +a deploy key) or `gh auth login` (GitHub). `GITEA_TOKEN` can come from a +`.env` file at the project root (copy `.env.example`, never commit it). If +`.env` is missing or has no token when a sync is needed, ask the user for +one and create `.env` from `.env.example` with it rather than skipping the +sync or inventing a value. + +After a real `--apply` run, copy each Milestone's URL into the Gateway +Schedule's `Milestone` column (a content update, not a status change — it +does not need a new `## Version History` row). + +## Validating + +`PP` has no QC checklist yet (open item) — validate a plan against the +Business Case constraint it schedules and against `## Go / No-Go Criteria` +in each `MIL-*` it lists, rather than a dedicated checklist. diff --git a/.claude/skills/artifact/references/QC.md b/.claude/skills/artifact/references/QC.md new file mode 100644 index 0000000..8395a60 --- /dev/null +++ b/.claude/skills/artifact/references/QC.md @@ -0,0 +1,55 @@ +# Quality Criteria checklist (QC) + +A QC checklist is the reusable review checklist for one artifact **type**. +It lives in the framework (`framework/qc/qc-.md`), is +project-independent, and **must never name or link a real artifact +instance** (no `[BC-001]`, no `RC-*`, no stakeholder IDs). Refer to types +generically ("the Stakeholder Analysis"). + +- **ID:** `QC--` (e.g. `QC-BC-001`); the version starts + at `001` and only changes when the checklist itself is revised. +- **Create:** `new-artifact.sh QC --id QC-XX-001 --file framework/qc/qc-.md + --cite QC-=framework/qc/qc-.md ...` +- **CrossReference:** the QC checklists immediately backward and forward in + Larman's chain, in both directions: + +``` +QC-SA → QC-BC → { QC-BMC, QC-BPMN, QC-KPI } → QC-MIL +QC-BC, QC-SA → QC-UCD → { QC-US, QC-UC } +QC-UC → QC-DM → QC-SSD → QC-OC → QC-SD → QC-DCD → QC-ERD +QC-ADR ↔ QC-DCD, QC-ERD +QC-DCD, QC-ADR → { QC-PY, QC-CL, QC-CPP, QC-CS } (language code checklists) +``` + +## Cross-cutting checklists + +`QC-LANG-001` (`framework/qc/qc-language-domain.md`, language and domain) is +not tied to one artifact type. Apply it together with the checklist of the +artifact's own type to every type the registry marks "Written in the PO +language"; the review record (`RC`) lists both checklists and keeps the rows of +each. It has an ID in the `QC-` form like the others, but the short +name `LANG` is not an artifact type: there is no `LANG` instance, template or +catalog row. Add another cross-cutting checklist only when a rule applies to +several types and does not belong in any one of their checklists. + +## Version History statuses + +The statuses are `Proposed`, `Accepted`, `Rejected` and `Deprecated`, as for every +artifact type (rule in the `artifact` skill, "Version History rule"). + +## Required sections (after Metadata / Version History) + +- **Purpose** — why this type matters, what decision it supports. +- **Quality Criteria Checklist** — `# | Criterion | Level | ISO/IEC 25010 + Characteristic(s) | Notes`. `Level` is `Mandatory` (baseline every instance + must meet) or `Optional` (advanced, may be deferred); a checklist with an + extra column (e.g. `Format`) keeps `Level` right after `Criterion`. Every criterion is tagged with at least one of + the eight ISO/IEC 25010:2023 characteristics (Functional Suitability, + Performance Efficiency, Compatibility, Usability, Reliability, Security, + Maintainability, Portability). Never add an untagged criterion. +- **Common Defects** — anti-patterns a reviewer rejects on sight. +- **Traceability Rule** — Backward / Forward bullets with the same `[QC-*]` + labels as `CrossReference`. + +Also add an entry to `framework/CHANGELOG.md`. Reviews of real instances are +recorded in the project as `RC-*` records, not in the checklist. diff --git a/.claude/skills/artifact/references/RC.md b/.claude/skills/artifact/references/RC.md new file mode 100644 index 0000000..e89eed5 --- /dev/null +++ b/.claude/skills/artifact/references/RC.md @@ -0,0 +1,45 @@ +# SQA Review Record (RC) + +One record per review of a specific artifact instance against its QC +checklist. Create one for **every** artifact instance in the project. + +- **File:** `docs/sqa/reviews/rc--.md` +- **ID:** `RC-NNN`, sequential across all artifact types (the registry's + Next Available Version for `RC`). +- **Create:** `new-artifact.sh RC --file docs/sqa/reviews/rc-NNN-.md + --cite = --cite QC--001=framework/qc/.md` + +## Required sections (after Metadata / Version History) + +- **Artifact Under Review** — links to the instance and to the QC checklist + used, the scope (`full review`, or `delta re-review` with the criteria + covered, the reason and the earlier record), the artifact's language and + domain (its `Language` and `Domain` rows, `n/a` for a technical type) and + the language reviewer (a stakeholder ID, or `none`). +- **Checklist Results** — `# | Criterion | Status (Pass/Fail/N-A) | + Evidence/Notes`, one row per criterion copied from the QC checklist, in + the same order. +- **Language and Domain Results** — only for an artifact of a type written in + the PO language: the rows of `QC-LANG-001`, same columns and order. `N-A` is + not allowed for criteria 3, 5 and 9. +- **Overall Verdict** — Go / Go-with-conditions / No-Go, with rationale. +- **Action Items** — `Action | Owner | Due`. `Owner` is a stakeholder ID from + the project's Stakeholder Analysis, never a role name. Every `Fail` and + every condition gets an item. + +## After the review + +- The reviewer must not be the artifact's author (see governance). For a + PO-language artifact the reviewer must read its language and know its + domain, or a second reviewer, the language reviewer, does and is named on + the record; see `process/review-checklist-process.md`. +- The record is in English. Quote evidence that is the artifact's own wording + in its language, with a short gloss. +- Add or update the instance's row in the Traceability Matrix, including + this `RC-*` in "Last Reviewed". +- On **Go**, set the reviewed artifact's latest `## Version History` row to + `Accepted` and the row before it to `Deprecated` (`Approved` is not a + status). On Go-with-conditions the status stays `Proposed` until the action + items are closed. If the change is refused for good, set the row to + `Rejected` (the earlier `Accepted` row stays). +- Step-by-step narrative: `framework/process/review-checklist-process.md`. diff --git a/.claude/skills/artifact/references/SA.md b/.claude/skills/artifact/references/SA.md new file mode 100644 index 0000000..a7307d4 --- /dev/null +++ b/.claude/skills/artifact/references/SA.md @@ -0,0 +1,27 @@ +# Stakeholder Analysis (SA) + +Cite in `CrossReference` only if the instance exists (`new-artifact.sh` checks this for you): + +- **BC** — Business Case objectives each stakeholder concern traces to (Business Goal Alignment section) + +## Required sections (after Metadata / Version History) + +1. **Purpose** — why the analysis exists and the methodology it follows. +2. **Stakeholder Summary Table** — `ID | Name | Role/Title | Organization | + Power Level | Interest Level | Quadrant | Primary Concern (Business + Language)`. Every row fully filled; no unclassified stakeholder. +3. **Power/Interest Classification Rationale** — narrative per quadrant, + consistent with the table. +4. **Primary Concerns and FURPS+ Mapping** — each concern in business + language *and* mapped to a FURPS+ attribute. +5. **Communication Requirements** — channel, frequency, deliverable type, + tied to a project phase or milestone. +6. **Conflicting Interests and Mitigations** — every conflict has a + mitigation. +7. **Traceability Analysis** — stakeholder → actor/use case mapping, and + business-goal alignment citing Business Case (`[BC-001]`) objectives. +8. **Sign-Off**. + +Stakeholder IDs (`S01`, `S02`, …) are **stable: never renumbered or reused**. +Every other artifact cites them for RACI, ownership and review assignment +(`AGENTS.md` rule 3). Add new stakeholders with the next free `S`. diff --git a/.claude/skills/artifact/references/SD.md b/.claude/skills/artifact/references/SD.md new file mode 100644 index 0000000..a8b2476 --- /dev/null +++ b/.claude/skills/artifact/references/SD.md @@ -0,0 +1,26 @@ +# Sequence Diagram (Design) (SD) + +Cite in `CrossReference` only if the instance exists (`new-artifact.sh` checks this for you): + +- **OC** — **Required source**: the contract whose postconditions each diagram realizes +- **DCD** — Forward: classes/methods these messages become + +## Required sections (after Metadata / Version History) + +One block per realized Operation Contract: + +1. **Realizes** — the contract (`[OC-…]`) and its operation name. +2. **Diagram** — PlantUML sequence diagram: sync (solid filled arrow), + async (open arrow), returns (dashed); activations matching the call + nesting; `create` / `destroy` shown for transient objects; + `loop` / `alt` / `opt` fragments for conditional/repeated behavior. +3. **Pattern Annotations** — table `Pattern (GRASP/GoF) | Applied to | + Rationale`. Patterns are labelled, never implicit. +4. **Postcondition Coverage** — `Postcondition | Satisfied by message`; + every postcondition of the contract must be covered. +5. **Responsibility Check** — a short note showing no god-object receives + all messages (low coupling, high cohesion). + +## Terminology + +Use the IT terms from the dictionary (`DICT`), not the PO terms the Domain Model uses. diff --git a/.claude/skills/artifact/references/SSD.md b/.claude/skills/artifact/references/SSD.md new file mode 100644 index 0000000..16e8f94 --- /dev/null +++ b/.claude/skills/artifact/references/SSD.md @@ -0,0 +1,21 @@ +# System Sequence Diagram (SSD) (SSD) + +Cite in `CrossReference` only if the instance exists (`new-artifact.sh` checks this for you): + +- **UC** — **Required source** of every SSD: cite the use case (name and ID) it depicts +- **DM** — Concepts behind message parameters / returned values +- **OC** — Forward: contract per system operation shown + +## Required sections (after Metadata / Version History) + +1. **Source Use Case** — name and ID (`[UC-…]`) and the specific scenario. +2. **Diagram** — PlantUML sequence diagram with just the actor and + `:System`; **no internal objects**. Dashed return arrows for operations + that produce a result. One scenario per diagram — separate diagrams for + alternate/exception flows (or state them out of scope). +3. **System Operations Table** — `Step | Message (verb phrase) | Parameters + | Return | Use case step`. Messages match the use case's main success + scenario step-for-step; justify any deviation. Message names become the + Operation Contract names. +4. **Lifecycle Notes** — creation/destruction of the System instance where + relevant (session/transaction scope). diff --git a/.claude/skills/artifact/references/TM.md b/.claude/skills/artifact/references/TM.md new file mode 100644 index 0000000..e09ceef --- /dev/null +++ b/.claude/skills/artifact/references/TM.md @@ -0,0 +1,18 @@ +# Traceability Matrix (TM) + +One matrix per project: `docs/sqa/traceability-matrix.md`. It makes the +Business Case's cross-artifact traceability target measurable. + +## Required sections (after Metadata / Version History) + +- **Purpose**. +- **Traceability Table** — one row per artifact instance: + `Artifact Instance | Type | Language | Domain | Upstream (Backward Link) | + Downstream (Forward Link) | Last Reviewed (RC-ID)`. `Language` and `Domain` + copy the artifact's Metadata rows so a reviewer can pick the right reviewer + from the matrix; they are `-` for a technical type (OC, SD, DCD, ERD, ADR, + TM, RC, QC, source code). `check-languages.sh --list` prints the same values. + Add or update a row whenever an instance is created or reviewed. +- **Coverage Notes** — which types have no instance yet, and how to read + `-`: in Upstream it means foundational; in Downstream it means nothing + is built on it yet; in Last Reviewed it means no `RC-*` exists yet. diff --git a/.claude/skills/artifact/references/TRN.md b/.claude/skills/artifact/references/TRN.md new file mode 100644 index 0000000..64b2b7d --- /dev/null +++ b/.claude/skills/artifact/references/TRN.md @@ -0,0 +1,18 @@ +# Reviewer Training (TRN) + +The reusable training material for reviewers. It mitigates the "resistance to +standardized reviews" risk of the Business Case. Framework-level, like `PRC`: +no project data, no stakeholder IDs, no links to project artifacts. The +*record* that a session happened (date, attendees, result) is a project +document, written after the session. + +- **File:** `framework/process/reviewer-training.md` (singleton, version `001`). +- **Create:** `new-artifact.sh TRN`. +- **CrossReference:** `PRC` (the procedure the training teaches). + +## Required sections (after Metadata / Version History) + +Purpose, Audience and Prerequisites, Learning Objectives, Agenda (modules with +minutes), Module Notes, Exercises (each with input and expected result), +Assessment (how and pass criteria), Session Record (what to capture). +Exercises use a seeded, generic example, not a real project artifact. diff --git a/.claude/skills/artifact/references/TRR.md b/.claude/skills/artifact/references/TRR.md new file mode 100644 index 0000000..70f083e --- /dev/null +++ b/.claude/skills/artifact/references/TRR.md @@ -0,0 +1,23 @@ +# Reviewer Training Record (TRR) + +The project's record that a reviewer training session happened: the evidence +that mitigates the "resistance to standardized reviews" risk and satisfies a +"training delivered and recorded" gateway criterion. It records one session +of the framework's training material (`TRN`); it holds project data +(stakeholder IDs, dates), so it lives in the project, not in the framework. + +- **File:** `docs/sqa/reviewer-training-record.md` (one per project; add a new + row under `## Attendees and Assessment` and a Version History row for each + further session). +- **Create:** `new-artifact.sh TRR --file docs/sqa/reviewer-training-record.md + --cite TRN-001=framework/process/reviewer-training.md`. +- **CrossReference:** `TRN` (the material that was taught). + +## Required sections (after Metadata / Version History) + +Session (material, date, facilitator, format), Attendees and Assessment +(stakeholder IDs, attended, Pass or Not yet against the assessment in the +material, and the languages the reviewer reads and the domains they know, for +example `da, en; it, medical`: the review process uses it to choose a reviewer +for a PO-language artifact), Feedback, Follow-ups (action, owner as a stakeholder ID, due). +Fill the record after the session; never before. diff --git a/.claude/skills/artifact/references/UC.md b/.claude/skills/artifact/references/UC.md new file mode 100644 index 0000000..fcb5da8 --- /dev/null +++ b/.claude/skills/artifact/references/UC.md @@ -0,0 +1,35 @@ +# Use Case (UC) + +Cite in `CrossReference` only if the instance exists (`new-artifact.sh` checks this for you): + +- **UCD** — Actor and use-case names must match it exactly +- **US** — Stories this use case decomposes into +- **SA** — Stakeholders & Interests — cite S-IDs +- **DM** — Forward: concepts derived from this use case's nouns +- **SSD** — Forward: the SSD depicting this use case's main scenario + +## Location + +`docs/uc-NNN/uc.md`, one folder per use case (create with +`new-artifact.sh UC --file docs/uc-NNN/uc.md`). The artifacts this use case +affects are saved in the same folder; see the `project-planning` skill, "Use +cases get their own folder". + +## Required sections (after Metadata / Version History) + +Pick the format explicitly (`Format: Brief | Casual | Fully Dressed`) and +state the **scope/level** (summary, user-goal, subfunction). Always: primary +actor, pre/postconditions, goal-perspective wording with no UI or +implementation detail. + +- **Brief** — a single paragraph summarizing only the main success scenario. +- **Casual** — informal multi-paragraph narrative; may mention some + alternate flows. +- **Fully Dressed** — all sections, in order: Scope, Level, Primary Actor, + Stakeholders and Interests (cite `SA` S-IDs), Preconditions, + Postconditions (success guarantee), Main Success Scenario (numbered + steps), Extensions / Alternative Flows (reference `<>` / + `<>` use cases), Special Requirements / Business Rules (per step), + Open Issues. + +Title and actor names must match `UCD` and `US` exactly. diff --git a/.claude/skills/artifact/references/UCD.md b/.claude/skills/artifact/references/UCD.md new file mode 100644 index 0000000..c7ce5bd --- /dev/null +++ b/.claude/skills/artifact/references/UCD.md @@ -0,0 +1,24 @@ +# Use Case Diagram (UCD) + +Cite in `CrossReference` only if the instance exists (`new-artifact.sh` checks this for you): + +- **SA** — Each actor traces to a stakeholder need — cite S-IDs +- **BC** — Scope / objectives the boundary reflects +- **US** — Forward: stories whose role must match an actor here +- **UC** — Forward: the use cases detailing each goal shown + +## Required sections (after Metadata / Version History) + +1. **Purpose and Scope** — the system boundary in words. +2. **Diagram** — actors with correct stereotypes (`<>`, + `<>`), a labelled system boundary, `<>` / `<>` + used per UML 2.5.1 (not as generic "uses"). Embed PlantUML or link the + diagram source; no UI or implementation detail. +3. **Actor Table** — `Actor | Stereotype | Stakeholder ID (SA) | Goals + (use cases)`. No orphan actors: every actor appears in at least one use + case. +4. **Use Case Table** — `Use Case | Actor(s) | Goal`, names as **verb + phrases describing actor goals** ("Place Order"), not system operations + ("Validate Input"). +5. **Relationships** — every `<>` / `<>` with a one-line + justification. diff --git a/.claude/skills/artifact/references/US.md b/.claude/skills/artifact/references/US.md new file mode 100644 index 0000000..554f93a --- /dev/null +++ b/.claude/skills/artifact/references/US.md @@ -0,0 +1,22 @@ +# User Story (US) + +Cite in `CrossReference` only if the instance exists (`new-artifact.sh` checks this for you): + +- **UCD** — The story's role must match an actor defined here +- **UC** — The use case each story traces to +- **BC** — Objective / epic the story ultimately supports +- **MIL** — The gateway (epic) each story delivers — one or more stories per gateway + +## Required sections (after Metadata / Version History) + +1. **Purpose and Scope** — the epic(s) covered. +2. **Story List** — each story with a stable ID `US-.` (e.g. + `US-001.01`, so it cannot be confused with the document ID `US-001`): + - Statement: **As a** ``, **I want** ``, **so that** + `` — one goal per story, no implementation detail. + - **Acceptance Criteria** — clear and testable (Given/When/Then works). + - **Traces to** — the use case (`UC-…`) or epic it comes from; a gateway + (`MIL-…`) is an epic. + - **Size** — fits a single iteration. +3. **INVEST Check** — one line confirming Independent, Negotiable, + Valuable, Estimable, Small, Testable (flag any exception with reason). diff --git a/.claude/skills/artifact/templates/ADR.md b/.claude/skills/artifact/templates/ADR.md new file mode 100644 index 0000000..05a4acf --- /dev/null +++ b/.claude/skills/artifact/templates/ADR.md @@ -0,0 +1,42 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Proposed | @AUTHOR@ | | Initial version | pending | + +Allowed Status values: `Proposed`, `Accepted`, `Rejected`, `Deprecated`, `Superseded by ADR-NNNN`. + +--- + +## Context + + + +## Decision + + + +## Consequences + +**Positive:** + +- + +**Negative:** + +- + +## Affected Artifacts + +- [] — , or a single "-" if none + +--- + +@LINKS@ diff --git a/.claude/skills/artifact/templates/BC.md b/.claude/skills/artifact/templates/BC.md new file mode 100644 index 0000000..653014e --- /dev/null +++ b/.claude/skills/artifact/templates/BC.md @@ -0,0 +1,72 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | +| Language | @LANGUAGE@ | +| Domain | @DOMAIN@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Proposed | @AUTHOR@ | | Initial version | pending | + +--- + +## Executive Summary + +## Methodological and Standards Foundation + +## Problem Statement + +## Business Opportunity + +## Objectives + +## Scope + +### In Scope + +### Out of Scope + +## Expected Benefits + +### Tangible Benefits + +### Intangible Benefits + +## Strategic Alignment + +## Success Criteria + +| # | Criterion | Target | Measure | +| --- | --- | --- | --- | + +## Risks + +| Risk | Impact | Mitigation | +| --- | --- | --- | + +## Assumptions + +## Constraints + +## Cost–Benefit Assessment + +| Costs | Benefits | +| --- | --- | + +## Stakeholders + +| Stakeholder ID (SA) | Interest in this project | +| --- | --- | + +## Recommendation + + — + +--- + +@LINKS@ diff --git a/.claude/skills/artifact/templates/BMC.md b/.claude/skills/artifact/templates/BMC.md new file mode 100644 index 0000000..a4f14fb --- /dev/null +++ b/.claude/skills/artifact/templates/BMC.md @@ -0,0 +1,115 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | +| Language | @LANGUAGE@ | +| Domain | @DOMAIN@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Proposed | @AUTHOR@ | | Initial version | pending | + +--- + +## Purpose / Scope + +Operationalizes: ([BC-]) + +## Canvas + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Key PartnersKey ActivitiesValue PropositionsCustomer RelationshipsCustomer Segments
+ +
    +
  • +
+ 		+ +
    +
  • +
+ 		+ +
    +
  • +
+ 		+ +
    +
  • +
+ 		+ +
    +
  • +
+
Key ResourcesChannels
+ +
    +
  • +
+ 		+ +
    +
  • +
+
Cost StructureRevenue Streams
+ +
    +
  • +
+ 		+ +
    +
  • +
+
+ + +## Assumptions + +| # | Assumption | How it can be tested | +| --- | --- | --- | + +## Consistency Check + +--- + +@LINKS@ diff --git a/.claude/skills/artifact/templates/BPMN.md b/.claude/skills/artifact/templates/BPMN.md new file mode 100644 index 0000000..0cbe4ce --- /dev/null +++ b/.claude/skills/artifact/templates/BPMN.md @@ -0,0 +1,43 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | +| Language | @LANGUAGE@ | +| Domain | @DOMAIN@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Proposed | @AUTHOR@ | | Initial version | pending | + +--- + +## Purpose and Business Goal + +Realizes: ([BC-]) + +## Participants + +| Pool / Lane | Participant | Stakeholder ID (SA) | +| --- | --- | --- | + +## Process Diagram + + + +## Element Table + +| Element | Type (event / activity / gateway) | Lane | Description | +| --- | --- | --- | --- | + +## Path Coverage + +| Path | Start event | End event | +| --- | --- | --- | + +--- + +@LINKS@ diff --git a/.claude/skills/artifact/templates/DCD.md b/.claude/skills/artifact/templates/DCD.md new file mode 100644 index 0000000..7ee1c17 --- /dev/null +++ b/.claude/skills/artifact/templates/DCD.md @@ -0,0 +1,50 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Proposed | @AUTHOR@ | | Initial version | pending | + +--- + +## Purpose and Scope + +## Diagram + +```plantuml +@startuml +class Controller { + -repo : Repository + +operationName(param : Type) : ReturnType +} +class Entity +Controller --> Entity : uses +@enduml +``` + +## Class Table + +| Class | Refines (Domain Model concept) | Responsibility | Attributes | Operations | +| --- | --- | --- | --- | --- | + +## Method Traceability + +| Method signature | Operation Contract / SD message | +| --- | --- | + +## Pattern Annotations + +| Pattern | Classes | Rationale | +| --- | --- | --- | + +## Dependency Check + +--- + +@LINKS@ diff --git a/.claude/skills/artifact/templates/DICT.md b/.claude/skills/artifact/templates/DICT.md new file mode 100644 index 0000000..da5f2b8 --- /dev/null +++ b/.claude/skills/artifact/templates/DICT.md @@ -0,0 +1,37 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | +| Language | @LANGUAGE@ | +| Domain | @DOMAIN@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Proposed | @AUTHOR@ | | Initial version | pending | + +--- + +## Purpose and Scope + +Maps each Product Owner (PO) term to its professional IT term. PO language: +. + +## Dictionary + +| PO term | Language | IT term | Definition | Used as PO term in | Used as IT term in | +| --- | --- | --- | --- | --- | --- | +| | | | | DM | OC, SD, DCD, ERD | + +## Rules + +- The Domain Model, use cases and user stories use the PO term; the Operation + Contract, Sequence Diagram, Design Class Diagram and ERD use the IT term. +- One IT term per PO term and one PO term per IT term; no synonyms. + +--- + +@LINKS@ diff --git a/.claude/skills/artifact/templates/DM.md b/.claude/skills/artifact/templates/DM.md new file mode 100644 index 0000000..8e46404 --- /dev/null +++ b/.claude/skills/artifact/templates/DM.md @@ -0,0 +1,56 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | +| Language | @LANGUAGE@ | +| Domain | @DOMAIN@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Proposed | @AUTHOR@ | | Initial version | pending | + +--- + +## Purpose and Scope + +Covers: + +## Diagram + +Concepts, attributes and associations only — no operations. + +```plantuml +@startuml +class Order { + date + status +} +class Customer { + name +} +Customer "1" --> "0..*" Order : places +@enduml +``` + +## Concept Table + +| Concept | Definition | Attributes | Source (use case / glossary) | +| --- | --- | --- | --- | + +## Association Table + +| From | Association (reading direction) | To | Multiplicity | +| --- | --- | --- | --- | + +## Generalizations + +| General | Specializations | Is-a justification | +| --- | --- | --- | + +--- + +@LINKS@ diff --git a/.claude/skills/artifact/templates/ERD.md b/.claude/skills/artifact/templates/ERD.md new file mode 100644 index 0000000..4a3c5bc --- /dev/null +++ b/.claude/skills/artifact/templates/ERD.md @@ -0,0 +1,53 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Proposed | @AUTHOR@ | | Initial version | pending | + +--- + +## Purpose and Scope + +## Diagram + +```plantuml +@startuml +hide circle +entity CUSTOMER { + * id : int <> + -- + name : string +} +entity ORDER { + * id : int <> + -- + * customer_id : int <> +} +CUSTOMER ||--o{ ORDER : places +@enduml +``` + +## Entity Table + +### + +| Attribute | Type | PK/FK | Nullable | Source (DCD class.attribute) | +| --- | --- | --- | --- | --- | + +## Relationship Table + +| Entity | Cardinality | Entity | FK | Rule | +| --- | --- | --- | --- | --- | + +## Normalization Notes + +--- + +@LINKS@ diff --git a/.claude/skills/artifact/templates/GOV.md b/.claude/skills/artifact/templates/GOV.md new file mode 100644 index 0000000..8f58c1d --- /dev/null +++ b/.claude/skills/artifact/templates/GOV.md @@ -0,0 +1,70 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | +| Language | @LANGUAGE@ | +| Domain | @DOMAIN@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Proposed | @AUTHOR@ | | Initial version | pending | + +--- + +## Purpose + +Defines how this project applies Quality Criteria (QC) checklists to real +artifact instances, producing SQA Review Records and Go/No-Go decisions. + +## ARB Review Workflow + +1. **Submission** — the artifact owner submits an instance for review, + identifying its type's QC checklist (`framework/qc/qc-*.md`). +2. **QC Checklist Review** — the assigned reviewer (see RACI) applies the + checklist criterion by criterion. +3. **Review Record** — the reviewer documents the outcome as an SQA Review + Record (`RC-*` under `docs/sqa/reviews/`). +4. **Go/No-Go Decision** — the Accountable role for the artifact category + decides; contested or cross-cutting cases escalate to the ARB Chair. +5. **Sign-off** — on **Go**, the artifact's `## Version History` gets an + `Accepted` row (the previous row becomes `Deprecated`). On **Go-with-conditions**, status stays `Proposed` until + the Action Items are closed. On **No-Go**, the artifact returns to its + owner. +6. **Traceability Update** — the Traceability Matrix is updated with the + instance and its `RC-*` reference. + +## RACI by Artifact Category + +Fill every cell with stakeholder IDs from the Stakeholder Analysis (`S`), +never role names. + +| Artifact Category | Responsible (runs the review) | Accountable (Go/No-Go owner) | Consulted | Informed | +| --- | --- | --- | --- | --- | +| Strategic (Stakeholder Analysis, Business Case, BMC) | S | S | S | S | +| Process/Business (BPMN, KPI, Milestones/Gateways) | S | S | S | S | +| Requirements (Use Case Diagram, User Story, Use Case) | S | S | S | S | +| Modeling/Design (Domain Model, SSD, Operation Contract, Sequence Diagram, DCD, ERD) | S | S | S | S | + +Cross-cutting escalations and disputed verdicts are Accountable to the ARB +Chair (`S`), overriding the category-level Accountable role. + +## Escalation Rules + +- A **No-Go** verdict, or any disagreement between the Responsible reviewer + and the category's Accountable owner, escalates to the ARB Chair. +- A reviewer may not review an instance they authored. +- Repeated No-Go verdicts (2 or more) on the same artifact type trigger a + review of the corresponding `QC-*` checklist itself. + +## Cadence + +- Reviews are triggered per artifact instance as it is produced or revised. +- QC checklists are reviewed annually. + +--- + +@LINKS@ diff --git a/.claude/skills/artifact/templates/KPI.md b/.claude/skills/artifact/templates/KPI.md new file mode 100644 index 0000000..2cfad59 --- /dev/null +++ b/.claude/skills/artifact/templates/KPI.md @@ -0,0 +1,37 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | +| Language | @LANGUAGE@ | +| Domain | @DOMAIN@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Proposed | @AUTHOR@ | | Initial version | pending | + +--- + +## Purpose + + + +## KPI Definitions + +| KPI ID | Name | SMART statement | Baseline | Target | Business Case success criterion | Owner (S-ID) | Frequency & method | Data source | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| KPI-01 | | | | | | | | | + +## Thresholds + +| KPI ID | Acceptable | At risk | Failing | +| --- | --- | --- | --- | + +## Reporting + +--- + +@LINKS@ diff --git a/.claude/skills/artifact/templates/MIL.md b/.claude/skills/artifact/templates/MIL.md new file mode 100644 index 0000000..794a2d7 --- /dev/null +++ b/.claude/skills/artifact/templates/MIL.md @@ -0,0 +1,60 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | +| Language | @LANGUAGE@ | +| Domain | @DOMAIN@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Proposed | @AUTHOR@ | | Initial version | pending | + +--- + +## Purpose + + + +## Deliverable + + + +## Go / No-Go Criteria + +| # | Criterion (objectively checkable) | Go | No-Go | +| --- | --- | --- | --- | + +## Dependencies + +| Depends on | Reason | +| --- | --- | + +## Traceability + +| Business Case objective / KPI / user story | Reference | +| --- | --- | + +## Ownership + +| Role | Stakeholder ID (SA) | +| --- | --- | +| Owner | | +| Approving reviewer | | + +## Target Date + +YYYY-MM-DD — + +## Tasks + +| # | Task | Summary | Needs its own Use Case/User Story? | Reference | +| --- | --- | --- | --- | --- | +| 1 | | | No | | + +--- + +@LINKS@ diff --git a/.claude/skills/artifact/templates/OC.md b/.claude/skills/artifact/templates/OC.md new file mode 100644 index 0000000..87a4220 --- /dev/null +++ b/.claude/skills/artifact/templates/OC.md @@ -0,0 +1,41 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Proposed | @AUTHOR@ | | Initial version | pending | + +--- + +## Contract: + +| Item | Value | +| --- | --- | +| Operation | `operationName(param: Type): ReturnType` | +| Traces to | in [SSD-] | +| Domain Model concepts | ([DM-]) | + +**Preconditions** + +- + +**Postconditions** + +- A instance was created. +- was associated with . +- . was set to . + +**Exceptions** + +| Condition (failing precondition) | Outcome | +| --- | --- | + +--- + +@LINKS@ diff --git a/.claude/skills/artifact/templates/PP.md b/.claude/skills/artifact/templates/PP.md new file mode 100644 index 0000000..1e3487b --- /dev/null +++ b/.claude/skills/artifact/templates/PP.md @@ -0,0 +1,63 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | +| Language | @LANGUAGE@ | +| Domain | @DOMAIN@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Proposed | @AUTHOR@ | | Initial version | pending | + +--- + +## Purpose + + + +## Planning Assumptions + +- Week 1 starts ; the plan ends by , per the Business Case constraint. +- Phase length: . + +## Gateway Schedule + +| Gateway | Document | Window | Decision date | Owner | Stories | Main deliverable | Milestone | +| --- | --- | --- | --- | --- | --- | --- | --- | +| | [MIL-] | | | | | | | + +```plantuml +@startgantt +Project starts +[Phase 1] starts and ends +[Phase 1 Go/No-Go] happens +@endgantt +``` + +## Scope Coverage + +| Business Case scope item | Gateway | +| --- | --- | + +## Dependencies + +``` + → → ... +``` + +## Plan Risks + +| Risk | Impact | Mitigation | +| --- | --- | --- | + +## Open Issues + +- + +--- + +@LINKS@ diff --git a/.claude/skills/artifact/templates/QC.md b/.claude/skills/artifact/templates/QC.md new file mode 100644 index 0000000..4e37af3 --- /dev/null +++ b/.claude/skills/artifact/templates/QC.md @@ -0,0 +1,42 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Proposed | @AUTHOR@ | | Initial version | pending | + +Allowed Status values: `Proposed`, `Accepted`, `Rejected`, `Deprecated`. The latest reviewed row is `Accepted`; the row before it is `Deprecated`. + +--- + +## Purpose + + + +## Quality Criteria Checklist + +Level: **Mandatory** criteria are the baseline every instance must meet; **Optional** criteria are advanced and may be deferred. + +| # | Criterion | Level | ISO/IEC 25010 Characteristic(s) | Notes | +| --- | --- | --- | --- | --- | +| 1 | | Mandatory | | | + +## Common Defects + +- +- + +## Traceability Rule + +- Backward: ([QC--]) +- Forward: ([QC--]) + +--- + +@LINKS@ diff --git a/.claude/skills/artifact/templates/RC.md b/.claude/skills/artifact/templates/RC.md new file mode 100644 index 0000000..a4dcdb7 --- /dev/null +++ b/.claude/skills/artifact/templates/RC.md @@ -0,0 +1,51 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Proposed | @AUTHOR@ | | Initial version | pending | + +--- + +## Artifact Under Review + +- Instance reviewed: [] +- Checklist used: [] (`QC--`, e.g. `QC-BC-001`) +- Scope: , reason, earlier record []> +- Language and domain: / (the artifact's Metadata rows), or `n/a` for a technical type +- Language reviewer: , or `none` when the reviewer reads the language and knows the domain + +## Checklist Results + +| # | Criterion | Status | Evidence/Notes | +| --- | --- | --- | --- | +| 1 | | Pass/Fail/N-A | | + +## Language and Domain Results + +Only for an artifact of a type written in the PO language: the rows of +`QC-LANG-001`, in order. Delete this section for a technical type. + +| # | Criterion | Status | Evidence/Notes | +| --- | --- | --- | --- | +| 1 | | Pass/Fail/N-A | | + +## Overall Verdict + + — + +## Action Items + +| Action | Owner | Due | +| --- | --- | --- | +| | | | + +--- + +@LINKS@ diff --git a/.claude/skills/artifact/templates/SA.md b/.claude/skills/artifact/templates/SA.md new file mode 100644 index 0000000..2b18ecc --- /dev/null +++ b/.claude/skills/artifact/templates/SA.md @@ -0,0 +1,56 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | +| Language | @LANGUAGE@ | +| Domain | @DOMAIN@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Proposed | @AUTHOR@ | | Initial version | pending | + +--- + +## Purpose + + + +## Stakeholder Summary Table + +| ID | Name | Role/Title | Organization | Power Level | Interest Level | Quadrant | Primary Concern (Business Language) | +| --- | --- | --- | --- | --- | --- | --- | --- | +| S01 | | | | HIGH / MEDIUM / LOW | HIGH / MEDIUM / LOW | Manage Closely / Keep Satisfied / Keep Informed / Monitor | | + +## Power/Interest Classification Rationale + +## Primary Concerns and FURPS+ Mapping + +| ID | Concern | FURPS+ attribute | +| --- | --- | --- | + +## Communication Requirements + +| ID | Channel | Frequency | Deliverable | Phase / Milestone | +| --- | --- | --- | --- | --- | + +## Conflicting Interests and Mitigations + +| Conflict | Stakeholders | Mitigation | +| --- | --- | --- | + +## Traceability Analysis + +### Business Goal Alignment + +| Stakeholder | Concern | Business Case objective | +| --- | --- | --- | + +## Sign-Off + +--- + +@LINKS@ diff --git a/.claude/skills/artifact/templates/SD.md b/.claude/skills/artifact/templates/SD.md new file mode 100644 index 0000000..70a02af --- /dev/null +++ b/.claude/skills/artifact/templates/SD.md @@ -0,0 +1,47 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Proposed | @AUTHOR@ | | Initial version | pending | + +--- + +## Sequence: + +**Realizes:** `operationName` in [OC-] + +### Diagram + +```plantuml +@startuml +participant ":Controller" as C +participant ":Collaborator" as X +C -> X : message(args) +activate X +X --> C : result +deactivate X +@enduml +``` + +### Pattern Annotations + +| Pattern (GRASP / GoF) | Applied to | Rationale | +| --- | --- | --- | + +### Postcondition Coverage + +| Postcondition (from contract) | Satisfied by message | +| --- | --- | + +### Responsibility Check + +--- + +@LINKS@ diff --git a/.claude/skills/artifact/templates/SSD.md b/.claude/skills/artifact/templates/SSD.md new file mode 100644 index 0000000..7856d4c --- /dev/null +++ b/.claude/skills/artifact/templates/SSD.md @@ -0,0 +1,42 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | +| Language | @LANGUAGE@ | +| Domain | @DOMAIN@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Proposed | @AUTHOR@ | | Initial version | pending | + +--- + +## Source Use Case + + ([UC-]) — scenario:
+ +## Diagram + +```plantuml +@startuml +actor Actor as A +participant ":System" as S +A -> S : verbPhrase(param) +S --> A : result +@enduml +``` + +## System Operations + +| Step | Message | Parameters | Return | Use case step | +| --- | --- | --- | --- | --- | + +## Lifecycle Notes + +--- + +@LINKS@ diff --git a/.claude/skills/artifact/templates/TM.md b/.claude/skills/artifact/templates/TM.md new file mode 100644 index 0000000..6e08eba --- /dev/null +++ b/.claude/skills/artifact/templates/TM.md @@ -0,0 +1,30 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Proposed | @AUTHOR@ | | Initial version | pending | + +--- + +## Purpose + +Tracks backward/forward links between artifact instances so that the Business Case's +cross-artifact traceability success criterion is measurable. A row is added or +updated whenever an artifact instance is created or reviewed. + +## Traceability Table + +| Artifact Instance | Type | Language | Domain | Upstream (Backward Link) | Downstream (Forward Link) | Last Reviewed (RC-ID) | +| --- | --- | --- | --- | --- | --- | --- | +| [] | | | | [] | [] | [] | + +--- + +@LINKS@ diff --git a/.claude/skills/artifact/templates/TRN.md b/.claude/skills/artifact/templates/TRN.md new file mode 100644 index 0000000..8dd6170 --- /dev/null +++ b/.claude/skills/artifact/templates/TRN.md @@ -0,0 +1,60 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Proposed | @AUTHOR@ | | Initial version | pending | + +--- + +## Purpose + + + +## Audience and Prerequisites + + + +## Learning Objectives + +By the end, a participant can: + +- + +## Agenda + +| Module | Topic | Minutes | +| --- | --- | --- | +| 1 | | | + +## Module Notes + +### Module 1: + + + +## Exercises + +### Exercise 1: + + + +## Assessment + + + +## Session Record + +What is recorded after each session, in the project (never in the framework): +date, facilitator, attendees, result against the assessment, feedback and +follow-ups. + +--- + +@LINKS@ diff --git a/.claude/skills/artifact/templates/TRR.md b/.claude/skills/artifact/templates/TRR.md new file mode 100644 index 0000000..f73f357 --- /dev/null +++ b/.claude/skills/artifact/templates/TRR.md @@ -0,0 +1,43 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Proposed | @AUTHOR@ | | Initial version | pending | + +--- + +## Session + +| Item | Value | +| --- | --- | +| Training material | [] | +| Date | | +| Facilitator | | +| Format and place | | + +## Attendees and Assessment + +| Stakeholder ID (SA) | Attended | Assessment (Pass / Not yet) | Languages and domains | Notes | +| --- | --- | --- | --- | --- | +| | | | | | + +## Feedback + + + +## Follow-ups + +| Action | Owner | Due | +| --- | --- | --- | +| | | | + +--- + +@LINKS@ diff --git a/.claude/skills/artifact/templates/UC.md b/.claude/skills/artifact/templates/UC.md new file mode 100644 index 0000000..b8b3388 --- /dev/null +++ b/.claude/skills/artifact/templates/UC.md @@ -0,0 +1,57 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | +| Language | @LANGUAGE@ | +| Domain | @DOMAIN@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Proposed | @AUTHOR@ | | Initial version | pending | + +--- + +**Format:** Brief | Casual | Fully Dressed (delete the unused sections below) + +## Brief + + + +## Casual + + + +## Fully Dressed + +- **Scope:** +- **Level:** summary | user-goal | subfunction +- **Primary Actor:** ]> +- **Stakeholders and Interests:** + - — +- **Preconditions:** +- **Postconditions (success guarantee):** + +### Main Success Scenario + +1. +2. + +### Extensions (Alternative / Exception Flows) + +- 2a. : + 1. (`<>` / `<>` ) + +### Special Requirements / Business Rules + +| Step | Rule | +| --- | --- | + +### Open Issues + +--- + +@LINKS@ diff --git a/.claude/skills/artifact/templates/UCD.md b/.claude/skills/artifact/templates/UCD.md new file mode 100644 index 0000000..2fd7867 --- /dev/null +++ b/.claude/skills/artifact/templates/UCD.md @@ -0,0 +1,52 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | +| Language | @LANGUAGE@ | +| Domain | @DOMAIN@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Proposed | @AUTHOR@ | | Initial version | pending | + +--- + +## Purpose and Scope + + + +## Diagram + +```plantuml +@startuml +left to right direction +actor "Name" as A1 +rectangle "System Name" { + usecase "Verb-phrase goal" as UC1 +} +A1 --> UC1 +@enduml +``` + +## Actor Table + +| Actor | Stereotype | Stakeholder ID (SA) | Goals (use cases) | +| --- | --- | --- | --- | + +## Use Case Table + +| Use Case | Actor(s) | Goal | +| --- | --- | --- | + +## Relationships + +| From | Relationship (`<>` / `<>`) | To | Justification | +| --- | --- | --- | --- | + +--- + +@LINKS@ diff --git a/.claude/skills/artifact/templates/US.md b/.claude/skills/artifact/templates/US.md new file mode 100644 index 0000000..f0fa723 --- /dev/null +++ b/.claude/skills/artifact/templates/US.md @@ -0,0 +1,38 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | +| Language | @LANGUAGE@ | +| Domain | @DOMAIN@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Proposed | @AUTHOR@ | | Initial version | pending | + +--- + +## Purpose and Scope + +## Story List + +### @ID@.01 — + +**As a** ]>, **I want** , **so that** . + +**Acceptance Criteria** + +- Given , when , then . + +| Traces to | Size | INVEST exceptions | +| --- | --- | --- | +| [UC-] or [MIL-] | fits one iteration | none | + +## INVEST Check + +--- + +@LINKS@ diff --git a/.claude/skills/coding-conventions/SKILL.md b/.claude/skills/coding-conventions/SKILL.md new file mode 100644 index 0000000..d207710 --- /dev/null +++ b/.claude/skills/coding-conventions/SKILL.md @@ -0,0 +1,98 @@ +--- +name: coding-conventions +description: Programming conventions for writing or reviewing source code — naming, layout, formatting and language idioms — for Python, C, C++, C# and Shell (bash). Use when writing, editing, reviewing or refactoring code in one of those languages, choosing names, setting up a formatter/linter config, or adding conventions for another language. Holds the rules shared by every language and points to a per-language sub-skill. +--- + +# Coding Conventions + +One skill for all languages. This file holds what is true in every language; +everything specific to one language is in a sub-skill that is read only when +that language is in hand: + +| Language | Sub-skill | QC checklist | +| --- | --- | --- | +| Python | `references/python.md` | `framework/qc/qc-programming-python.md` (`QC-PY-001`) | +| C | `references/c.md` | `framework/qc/qc-programming-c.md` (`QC-CL-001`) | +| C++ | `references/cpp.md` | `framework/qc/qc-programming-cpp.md` (`QC-CPP-001`) | +| C# | `references/csharp.md` | `framework/qc/qc-programming-csharp.md` (`QC-CS-001`) | +| Shell (bash) | `references/shell.md` | `framework/qc/qc-programming-shell.md` (`QC-SH-001`) | + +Read the sub-skill for the language you are working in, then write or review +the code. To review, use the language's QC checklist and record the result as +an `RC-*` (see the `artifact` skill). + +## Precondition: a planned task + +Before writing or editing code under `src/` or `tests/`, name the task row +(`MIL-NNN`, task N) or the synced issue, and the use case or design artifact +it implements, or say it is a plain technical task. If you cannot, refuse and +use the `project-planning` skill instead (rule: `framework/process/plan-first-gate.md`). +The task's milestone must be `Accepted` with a `Go` review record; if it is +still `Proposed`, or its latest review is conditional or No-Go, stop and say so. +Reviewing code needs no task. Before the pull request, code is reviewed against +the checklist of its language (`qc-programming-*`) and the result is recorded +as an `RC-*`. + +## Rules for every language + +1. **The existing code wins.** In a file or project that already has a + convention, follow it, even if the sub-skill says otherwise. Do not mix + styles within a file; do not reformat code you are not changing. +2. **Naming follows the language, not your habits.** Casing differs per + language (table below). Never carry one language's casing into another. +3. **A name says what, not how.** Name by purpose in the domain's language + (IT Professional English, as the registry's `Languages` section says), not by + type or implementation (`customer_list`, not `arr2`). +4. **Length follows scope.** Short names (`i`, `n`) only for tiny scopes; + wider scope, longer name. No abbreviations except ones the whole domain + uses (`id`, `url`, `http`). +5. **Booleans read as a question:** `is_valid`, `has_items`, `can_retry` + (cased per language). No negated names (`is_not_ready`). +6. **Functions are verbs, types are nouns.** A function that returns a value + without side effects may be a noun (`total`, `Total`) where the language + community does so. +7. **Formatting is done by the formatter,** not by hand and not in review + comments. Each sub-skill names the formatter and linter; commit its + configuration file with the code. +8. **Comments say why,** never what the code already says. Public APIs get + the language's documentation-comment form. +9. **No dead or commented-out code, no unexplained magic numbers.** Name the + constant. +10. **Errors are handled or propagated, never swallowed.** Each sub-skill says + how its language does this. + +## Casing at a glance + +| Element | Python | C | C++ | C# | +| --- | --- | --- | --- | --- | +| Type / class | `PascalCase` | `snake_case_t` | `PascalCase` | `PascalCase` | +| Function / method | `snake_case` | `snake_case` | `snake_case` | `PascalCase` | +| Variable / parameter | `snake_case` | `snake_case` | `snake_case` | `camelCase` | +| Constant | `UPPER_SNAKE` | `UPPER_SNAKE` | `kPascalCase` | `PascalCase` | +| Private member | `_leading` | file-scope `static` | `trailing_` | `_camelCase` | +| Namespace / module | `snake_case` module | `mod_` prefix | `snake_case` | `PascalCase` | +| File | `snake_case.py` | `snake_case.c/.h` | `snake_case.cpp/.h` | `PascalCase.cs` | + +The table is a summary; the sub-skill is authoritative. Shell (bash) is not in +the table: functions and variables are `snake_case`, constants and environment +variables `UPPER_SNAKE`, files `kebab-case.sh`. + +## Governance boundary + +Conventions are **defined and governed** here but **not enforced** by this +framework: writing a linter or CI job that enforces them is outside the +framework's scope. The formatter and linter names in each sub-skill are the +recommended tools, not a pipeline. A new or changed convention follows the +process in the project's Coding Standards Governance document and is recorded +in `framework/CHANGELOG.md`. No project data belongs in this skill. + +## Adding a language + +1. Add `references/.md` with these sections: Standard base, Naming, + Formatting, Language rules, Errors, Tests, Tooling. +2. Add `framework/qc/qc-.md` (`QC--001`) using the `QC` type + of the `artifact` skill, tagging every criterion with an ISO/IEC 25010:2023 + characteristic and a Level. +3. Add the row to the table above, the casing table, and a row for the + language in `framework/registry/artifact-catalog.md`; note it in + `framework/CHANGELOG.md`; run `bash framework/scripts/install-skills.sh`. diff --git a/.claude/skills/coding-conventions/references/c.md b/.claude/skills/coding-conventions/references/c.md new file mode 100644 index 0000000..14375ca --- /dev/null +++ b/.claude/skills/coding-conventions/references/c.md @@ -0,0 +1,71 @@ +# C conventions + +C has no single official style guide. This sub-skill fixes one consistent +style built on common practice; MISRA C and SEI CERT C are the references for +safety-critical or security-sensitive code. + +## Standard base + +ISO C11 or C17 as set by the project's compiler flag (`-std=c11`). Compile +with warnings on (`-Wall -Wextra -Wpedantic`); treat warnings as errors in +release builds. + +## Naming + +| Element | Convention | Example | +| --- | --- | --- | +| Function, variable, parameter | `snake_case` | `parse_header`, `byte_count` | +| Public symbol | module prefix plus `snake_case` (C has no namespaces) | `stay_reader_open()` | +| File-local function / variable | `static`, no prefix needed | `static int next_token(...)` | +| Type (`struct`, `enum`, `typedef`) | `snake_case_t`, module prefix for public types | `stay_reader_t` | +| Enum constant, macro, constant | `UPPER_SNAKE` with the module prefix | `STAY_READER_OK` | +| Header / source file | `snake_case.h` / `snake_case.c`, same base name | `stay_reader.h` | +| Header guard | `MODULE_FILE_H` (or `#pragma once` if the project allows) | `STAY_READER_H` | + +- Do not use reserved identifiers: a leading underscore followed by an + uppercase letter, any double underscore, or a leading underscore at file + scope. +- POSIX reserves the `_t` suffix; keep the module prefix on public types so + they cannot collide. +- Macros are a last resort; prefer `static inline` functions and `enum` or + `const` values. + +## Formatting + +- One formatter configuration for the project (`clang-format`); 4 spaces (or + the project's setting), no tabs mixed in. +- Braces on every `if`, `else`, `for`, `while`, even for one statement. +- One declaration per line; declare variables at first use, initialised. +- Headers: include what you use, only what you use; public headers are + self-contained; add `extern "C"` guards when C++ code consumes them. + +## Language rules + +- Check every return value that can fail; check every allocation. +- Every `malloc`/`open`/`lock` has one clear owner and one matching release; + release on every exit path (single exit or `goto cleanup`). +- Use `size_t` for sizes and indices, fixed-width types (``) for + data layout, `const` wherever data is not modified, `restrict` only with + care. +- Bounds are explicit: pass a length with every buffer; use `snprintf`, + never `sprintf`, `strcpy` or `gets`. +- No undefined behaviour: no signed overflow, no out-of-range shifts, no use + after free, no uninitialised reads. +- Avoid global mutable state; if unavoidable, `static` and documented. + +## Errors + +Return a status code (an `enum`) or `-1`/`NULL` plus an error out-parameter; +document which in the header. Never ignore a failing call. Read `errno` +immediately after the failing call. + +## Tests + +A unit-test framework (for example Unity or CMocka); run under sanitizers +(`-fsanitize=address,undefined`) in at least one build. + +## Tooling + +`clang-format`, `clang-tidy` or `cppcheck`, compiler warnings, sanitizers. + +Review with `QC-CL-001`. diff --git a/.claude/skills/coding-conventions/references/cpp.md b/.claude/skills/coding-conventions/references/cpp.md new file mode 100644 index 0000000..8e164ab --- /dev/null +++ b/.claude/skills/coding-conventions/references/cpp.md @@ -0,0 +1,70 @@ +# C++ conventions + +## Standard base + +ISO C++17 or later as set by the project (`-std=c++20`); the C++ Core +Guidelines are the rule source. C++ has no official naming style, so the +style below is used unless the project already has another (rule 1 of the +overall skill). + +## Naming + +| Element | Convention | Example | +| --- | --- | --- | +| Class, struct, enum, concept, type alias | `PascalCase` | `StayReader`, `Stay` | +| Function, method, variable, parameter | `snake_case` | `read_stays()`, `byte_count` | +| Data member (private) | `snake_case` with trailing underscore | `buffer_` | +| Struct public data member | `snake_case`, no underscore | `check_in` | +| Constant (`constexpr`, namespace-scope `const`) | `kPascalCase` | `kMaxRetries` | +| Enum class value | `PascalCase` | `Status::NotFound` | +| Namespace | short `snake_case`; no `using namespace` in headers | `billing` | +| Template parameter | `PascalCase` | `typename ItemT` | +| Macro | `UPPER_SNAKE` with project prefix; avoid macros | `BILLING_ASSERT` | +| Header / source file | `snake_case.h` / `snake_case.cpp`, same base name | `stay_reader.h` | +| Header guard | `#pragma once` (or `PROJECT_PATH_FILE_H`) | | + +## Formatting + +- `clang-format` with one checked-in config; 4 spaces (or the project's + setting); braces on every control-flow body. +- Include order: matching header, project headers, third party, standard + library; each group sorted. +- One declaration per line; declare at first use, initialise with `{}`. + +## Language rules + +- **Ownership:** RAII everywhere. No owning raw pointers, no naked + `new`/`delete`; use `std::unique_ptr` by default, `std::shared_ptr` only for + real shared ownership, created with `std::make_unique`/`make_shared`. +- Follow the rule of zero; if you define one of destructor, copy or move, + define or delete all five. +- Pass by `const&` (large, read-only) or by value (small or sink); use + `std::span` and `std::string_view` for non-owning views, `std::optional` for + "maybe", `std::variant` for alternatives. +- `const` and `constexpr` by default; mark single-argument constructors + `explicit`; mark `override`/`final`; `[[nodiscard]]` on results that must + be used. +- Prefer algorithms and range-for over hand-written loops; `enum class` over + plain `enum`; `nullptr` over `NULL` or `0`; `using` over `typedef`. +- No C-style casts; use `static_cast` and friends. No mutable global state. +- Headers are self-contained and contain declarations, templates and + `inline` definitions only. + +## Errors + +Use exceptions for exceptional failures, or `std::expected` and error codes +where the project forbids exceptions; one choice per project. Destructors +never throw. Catch by `const&`; never `catch (...)` without rethrowing or +logging. + +## Tests + +GoogleTest, Catch2 or doctest; run under sanitizers (`address`, `undefined`) +in at least one build. + +## Tooling + +`clang-format`, `clang-tidy` with the Core Guidelines checks, compiler +warnings (`-Wall -Wextra -Wpedantic`), sanitizers. + +Review with `QC-CPP-001`. diff --git a/.claude/skills/coding-conventions/references/csharp.md b/.claude/skills/coding-conventions/references/csharp.md new file mode 100644 index 0000000..88abb3b --- /dev/null +++ b/.claude/skills/coding-conventions/references/csharp.md @@ -0,0 +1,72 @@ +# C# conventions + +## Standard base + +Microsoft's C# coding conventions and .NET Framework Design Guidelines, with +the analyzers that ship in the SDK. Target the language version of the +project's `LangVersion` / target framework. + +## Naming + +| Element | Convention | Example | +| --- | --- | --- | +| Namespace | `PascalCase`, matches folder path | `Billing.Stays` | +| Class, struct, record, enum, delegate | `PascalCase` (nouns) | `StayReader` | +| Interface | `I` + `PascalCase` | `IStayReader` | +| Method, property, event, public field | `PascalCase` | `ReadStays()`, `CheckIn` | +| Constant, `static readonly` | `PascalCase` | `MaxRetries` | +| Enum value | `PascalCase`; `[Flags]` enums are plural | `Status.NotFound` | +| Parameter, local variable | `camelCase` | `byteCount` | +| Private / internal field | `_camelCase` | `_buffer` | +| Generic type parameter | `T` or `T` + `PascalCase` | `T`, `TKey` | +| Async method | ends in `Async` | `ReadStaysAsync()` | +| Exception, attribute | end in `Exception` / `Attribute` | `InvalidDateException` | +| Boolean | `Is`, `Has`, `Can` prefix | `IsActive` | +| File | the type's name, one top-level type per file | `StayReader.cs` | + +- Two-letter acronyms are upper case (`IO`); longer ones are `PascalCase` + (`Xml`, `Http`). + +## Formatting + +- `.editorconfig` checked in; `dotnet format` applies it. 4 spaces, Allman + braces, braces on every control-flow body. +- File-scoped namespaces (`namespace X;`); `using` directives outside the + namespace, `System` first. +- `var` when the type is obvious from the right-hand side, explicit type + otherwise. + +## Language rules + +- Enable nullable reference types (`enable`) and treat + nullable warnings as errors; do not suppress with `!` without a comment. +- `IDisposable` owners use `using`; implement the dispose pattern only when + needed. +- `async`/`await` all the way; no `.Result` or `.Wait()`; no `async void` + except event handlers; pass `CancellationToken` through public async APIs. +- Prefer properties over public fields, `readonly` and `init` for + immutability, `record` for value-like data, pattern matching and switch + expressions over long `if` chains. +- LINQ for queries, loops for side effects; do not enumerate a sequence twice. +- String interpolation over concatenation; `StringBuilder` in loops; + `DateTimeOffset` over `DateTime` for points in time; `decimal` for money. +- XML documentation comments (`///`) on public types and members. + +## Errors + +Throw specific exceptions (`ArgumentNullException`, custom types); validate +arguments at the public boundary (`ArgumentNullException.ThrowIfNull`). Catch +the narrowest type; `throw;` (not `throw ex;`) to rethrow. Never an empty +`catch`. + +## Tests + +xUnit, NUnit or MSTest; names like `Method_Condition_Expected`; one behaviour +per test; no dependence on order, time or the network. + +## Tooling + +`dotnet format`, the .NET analyzers (`AnalysisLevel`, `EnforceCodeStyleInBuild`) +and optionally StyleCop.Analyzers, configured in `.editorconfig`. + +Review with `QC-CS-001`. diff --git a/.claude/skills/coding-conventions/references/python.md b/.claude/skills/coding-conventions/references/python.md new file mode 100644 index 0000000..e262961 --- /dev/null +++ b/.claude/skills/coding-conventions/references/python.md @@ -0,0 +1,66 @@ +# Python conventions + +## Standard base + +PEP 8 (style), PEP 257 (docstrings), PEP 484 and later (type hints). Target +the Python version declared in `pyproject.toml`. + +## Naming + +| Element | Convention | Example | +| --- | --- | --- | +| Package / module | short `snake_case` | `billing`, `stay_reader.py` | +| Class, exception | `PascalCase`; exceptions end in `Error` | `StayReader`, `InvalidDateError` | +| Function, method, variable, parameter | `snake_case` | `total_price`, `read_stays()` | +| Constant (module level) | `UPPER_SNAKE` | `MAX_RETRIES` | +| Internal (not public API) | one leading underscore | `_parse_row` | +| Type variable | short `PascalCase`; `_co` / `_contra` for variance | `T`, `KeyT`, `ItemT_co` | +| Boolean | `is_`, `has_`, `can_` prefix | `is_active` | +| Test file / function | `test_.py` / `test__` | `test_total_when_empty` | + +- Avoid name mangling (`__name`) unless you need it to prevent a subclass clash. +- Never use `l`, `O` or `I` as single-letter names. +- Do not shadow builtins (`list`, `id`, `type`); add a trailing underscore + (`type_`) only as a last resort. + +## Formatting + +- 4 spaces, no tabs. Maximum line length set once in the formatter config + (88 with `ruff format`; 79 if the project follows PEP 8 strictly). +- Imports at the top, grouped standard library / third party / local, one + blank line between groups, no wildcard imports. +- Double quotes for strings unless the formatter says otherwise. +- Trailing commas in multi-line literals and calls. + +## Language rules + +- Annotate every function signature (parameters and return, `-> None` too). + Modern syntax: `X | None`, `list[str]`. Avoid `Any` without a comment. +- `pathlib` over `os.path`; f-strings over `%` or `.format`; `enum` over + magic strings; `dataclass` (frozen where possible) over ad-hoc dicts. +- No mutable default arguments; no bare `except:`; no `print` for logging + (use `logging`). +- Use context managers (`with`) for files, locks and connections. +- Prefer comprehensions over `map`/`filter` with lambdas; keep them simple. +- Docstrings (PEP 257) on public modules, classes and functions; say what, + not how. + +## Errors + +Raise specific exceptions; catch the narrowest type; re-raise with +`raise ... from err` to keep the cause. Do not use exceptions for normal +control flow. + +## Tests + +`pytest`; one behaviour per test; `tmp_path` for files; fakes over mocks where +a simple fake is possible; tests do not depend on order or on the network. + +## Tooling + +`ruff` (lint and format) and `mypy --strict` (types), configured in +`pyproject.toml`. Architecture rules (layers, ports, dataframes) are in +`.agents/rules/python.md` and the `python-developer` agent; this sub-skill +covers naming and style only. + +Review with `QC-PY-001`. diff --git a/.claude/skills/coding-conventions/references/shell.md b/.claude/skills/coding-conventions/references/shell.md new file mode 100644 index 0000000..aa8a728 --- /dev/null +++ b/.claude/skills/coding-conventions/references/shell.md @@ -0,0 +1,62 @@ +# Shell conventions (bash) + +## Standard base + +Bash 4 or later, POSIX `test` semantics through `[[ ]]`. Start every script +with `#!/usr/bin/env bash` and `set -euo pipefail`. State the bash version and +the external tools it needs in the header comment. + +## Naming + +| Element | Convention | Example | +| --- | --- | --- | +| Script file | `kebab-case.sh`, executable | `check-plan.sh`, `new-artifact.sh` | +| Function | `snake_case`, a verb | `read_registry`, `die` | +| Local variable, parameter | `snake_case`, declared with `local` | `msgfile`, `changed` | +| Constant, environment variable | `UPPER_SNAKE` | `PLAN_GATE`, `PROJECT_ROOT` | +| Boolean | `is_` / `has_` prefix, value `0` or `1` | `is_enabled=1` | + +- Name a script and its functions by what they do, not how. +- Do not shadow a command with a function of the same name. + +## Formatting + +- 2 spaces, no tabs. One command per line; `then` and `do` on the same line as + `if` and `for`. Keep lines near 80 characters; break long pipelines at `|`. +- Format with `shfmt -i 2 -ci`; lint with `shellcheck`. Commit the project's + `.editorconfig` or `.shellcheckrc` with the code. + +## Language rules + +- **Quote every expansion** (`"$var"`, `"${arr[@]}"`); use arrays, not + space-separated strings, for lists. Use `[[ ]]`, not `[ ]`, and `$(...)`, + not backticks. +- Declare function variables `local`; no globals except constants. +- Parse options with `case` and `shift`, check required arguments with + `"${1:?usage: ...}"`, and print a usage line on bad input. +- Read input with `read -r`; iterate files with globs or `find -print0`, never + by parsing `ls`. +- Use `mktemp` for temporary files and remove them with `trap ... EXIT`; never + a fixed `/tmp` name. + +## Errors and exit codes + +- Errors go to standard error, start with `error:`, say what is wrong and what + to do, and end the script with a non-zero exit code (`die` helper). +- `0` is success, `1` a failed check or bad input, `2` a usage error; document + any other code in the header. +- Never swallow a failure with `|| true` without a comment that says why. + +## Safety + +- A script that changes state outside its own directory defaults to a dry run + or asks for an explicit flag (`--apply`, `--force`); say so in the header. +- Never echo a token or password, put one on a command line, or commit one; + read secrets from the environment or a gitignored file. +- Do not `eval` input; do not build a command from unvalidated text. + +## Tools + +Formatter `shfmt`, linter `shellcheck`, syntax check `bash -n`. These are the +recommended tools, not a pipeline: enforcing them in CI is outside this +framework's scope. diff --git a/.claude/skills/project-planning/SKILL.md b/.claude/skills/project-planning/SKILL.md new file mode 100644 index 0000000..561235c --- /dev/null +++ b/.claude/skills/project-planning/SKILL.md @@ -0,0 +1,283 @@ +--- +name: project-planning +description: Plan a project (or a new phase of one) in phases with tasks, and sync those phases and tasks to Gitea or GitHub as Milestones and Issues. Use when starting a new project, adding or updating a phase/gateway, breaking a phase down into tasks, deciding whether a task needs its own use case or user story, or asked to create/update project milestones or issues on the git host. +--- + +# Project Planning + +Plans a project as phases (gateways), each phase as a set of tasks, and +keeps those phases and tasks in sync with the git host's own project +management (Milestones and Issues). It builds on the `artifact` skill's +`PP` (Project Plan) and `MIL` (Milestone/Gateway) types. + +## Domain language first + +Before planning, find the Product Owner's (PO's) domain language. Take it from +the first of these that states it: + +1. the user's prompt; +2. a file the user included or that the project already has (the `Languages` + section of `docs/artifact-registry.md`). + +If none states it, **ask the user for it** and stop planning until it is +answered; never assume one. Record the answer in the registry's `Languages` +section. The artifact types the registry marks "Written in the PO language" +are written in it, once, with no translated copy. + +## Start here + +Before planning or building anything, check that the baseline exists (the +`docs/artifact-registry.md` rows and files): the Business Case (`BC`), the +Stakeholder Analysis (`SA`), the Project Plan (`PP`) and at least one +milestone (`MIL`). If one is missing, create it first, in that order, with +`new-artifact.sh` (it refuses when a type in the catalog's `Requires` column +is missing). + +Each of these steps ends with a review: the document counts only once its +review record (`RC-*`) says `Go` and its Version History row is `Accepted` +(`process/review-checklist-process.md`). Do not start a step on a document that +is still `Proposed`; ask for the review first. + +A "build X" request is planning-first. Produce the phases, tasks and issues, +show the dry run of `sync-project.sh`, and ask for a go-ahead before any code +is written; running `--apply` is the user's decision. Only the user can waive +the plan, in chat, for that request; the waiver does not carry over. The rule +is defined in `framework/process/plan-first-gate.md`. + +## The hierarchy + +``` +Business goal → Feature/requirement → Use case/user story → Tasks +``` + +The use case/user story explains **why** a feature exists; tasks explain +**how** the team implements it. Not every task needs a use case: + +- **Needs a use case/user story** — the task is something a user, or + another system, actually does: "User resets password", "Admin exports + customer report", "Payment service processes refund". +- **Plain task, no use case** — purely technical/implementation work: + "Refactor authentication middleware", "Add database index", "Upgrade + React version", "Fix null-pointer bug", "Add unit tests", "Configure CI + pipeline", "Optimize SQL query". + +When in doubt, ask: does this row describe a goal an actor is pursuing, or +a step the team takes to build something? Goals get a use case; steps stay +a plain task. + +## Use cases get their own folder + +Each use case lives in `docs/uc-NNN/` (`UC-001` → `docs/uc-001/`), together +with the artifacts that belong to it. Nothing about a use case goes in a +shared `docs/use-cases/` folder. + +1. **Create the folder and the use case:** + `bash framework/scripts/new-artifact.sh UC --file docs/uc-001/uc.md`. +2. **Create only the artifacts this use case affects,** in this order, each in + the same folder with a fixed file name. Skip any it does not touch (no + `erd.md` if nothing is stored; no `dm.md` if it adds no concept). + + | Order | Type | File | Create when the use case… | + | --- | --- | --- | --- | + | 1 | `SSD` | `ssd.md` | has system interaction to show (almost always) | + | 2 | `DM` | `dm.md` | introduces or changes domain concepts | + | 3 | `OC` | `oc.md` | has system operations that change state | + | 4 | `SD` | `sd.md` | needs a collaboration design for an operation | + | 5 | `DCD` | `dcd.md` | adds or changes design classes | + | 6 | `ERD` | `erd.md` | adds or changes persisted data | + + ```bash + bash framework/scripts/new-artifact.sh SSD --file docs/uc-001/ssd.md + bash framework/scripts/new-artifact.sh DM --file docs/uc-001/dm.md --cite UC-001=docs/uc-001/uc.md + ``` + + `new-artifact.sh` cites only the artifacts in the same use-case folder + (and project-level ones); for `DM`, `DCD` and `ERD`, add the use case and + sibling artifacts by hand with `--cite`. Each gets its own ID (the next + version in the registry, e.g. `DM-002`) and its own `RC-*` review. +3. **Reconcile with the project models.** The use-case artifacts are a scoped + view; the project-level `docs/domain-model.md`, `docs/dcd.md` and + `docs/erd.md` are the consolidated truth. When the use case's `DM`, `DCD` + or `ERD` are done, compare each with its project-level document: + - add the new concepts, classes, attributes and entities; change the ones + the use case modified; + - keep names identical to the existing ones, and resolve any conflict + with another use case's model instead of duplicating the element; + - give each project-level document a new `## Version History` row (Change: + which use case caused it), and create it from the first use case's + document if it does not exist yet; + - if nothing needs to change, say so in the use case's task and PR + description ("project DM/DCD/ERD unchanged: "). + +## Planning a project (or a new phase) + +1. **Phases are gateways.** Each phase is a `MIL-*` document (the `artifact` + skill's `MIL` type): purpose, deliverable, Go/No-Go criteria, dependencies, + ownership, target date. Create one with + `bash framework/scripts/new-artifact.sh MIL --file docs/milestones/mil--.md`. +2. **The plan schedules the phases.** `docs/project-plan.md` (the `artifact` + skill's `PP` type) lists every phase with its window and owner, and holds + the overall timeline diagram. Create it once with + `bash framework/scripts/new-artifact.sh PP`. +3. **Break each phase into tasks.** In the phase's `## Tasks` section, add + one row per task using the hierarchy rule above. Tasks that need a use + case or user story get one created first (`UC`/`US` types; a use case + follows "Use cases get their own folder" below), then are referenced from + the Tasks row; plain tasks just describe the work. +4. **Sync to the git host.** Run the sync tool (below) to create or update + the corresponding Milestones and Issues. Do this whenever a phase or its + tasks change — the tool is idempotent (matches by title, never creates a + duplicate). + +## Syncing to Gitea/GitHub + +```bash +bash framework/scripts/sync-project.sh # prints the plan only — no network calls +bash framework/scripts/sync-project.sh --milestone MIL-002 # limit to one phase +bash framework/scripts/sync-project.sh --apply # actually create/update on the git host +``` + +- **Default is a dry run**: it parses `docs/milestones/mil-*.md` and prints + what would be created or updated. Nothing is sent anywhere. +- **`--apply`** performs the real requests. It needs: + - **Gitea** (default — detected from `origin`'s hostname): `GITEA_TOKEN` + env var, a personal access token. This is an HTTP API call (milestones, + issues) — a deploy key cannot be used, since deploy keys only + authenticate SSH git transport (clone/fetch/push), not the REST API. + Scope the token to issues only if your Gitea version supports scoped + tokens, rather than a full-account one. + - **GitHub** (detected when `origin` is on github.com, or pass + `--host github`): the `gh` CLI, already logged in (`gh auth login`). +- **`--with-project`** additionally tries to create/attach a Kanban Project + board. This is best-effort: some Gitea versions (confirmed on 1.27.3) show + Projects/Kanban only in the web UI and expose **no REST API for it at + all**, so this always fails there — check your server's own + `https:///swagger.v1.json` for any `project` path if unsure. GitHub + Projects (v2) needs `gh` with the `project` scope. Either way the script + warns and continues; Milestones and Issues are unaffected. Where there's + no API, create the board by hand at `https://///projects`. +- Read the script's header comment for the full flag list, including + `--owner`, `--repo`, `--api-base` to override auto-detection. + +`--apply` is an outward-facing, hard-to-reverse action (it creates real +Milestones/Issues on the git host) — run it yourself once you're ready, or +ask explicitly for it to be run. + +## Branching before commits + +**Never commit, push or open a PR unless the user asks.** The user reviews +the working-tree changes first; finish the edits, summarise them and stop. +Everything below (branching, closing keywords, resolving commit links, the +PR) describes how to do those steps once the user has asked for them; it is +not permission to start them. + +Never commit directly on `main`. This is enforced locally by a pre-commit +hook (`framework/githooks/pre-commit`) once +`bash framework/scripts/install-git-hooks.sh` has been run in this clone — +run it once per clone; it points `core.hooksPath` at the versioned +`framework/githooks/` instead of the per-clone, untracked `.git/hooks/`. +The hook refuses the commit with a pointer back to this section; a rare, +deliberate exception can bypass it with `ALLOW_MAIN_COMMIT=1 git commit`. + +Before the first commit of a piece of work, create and switch to a new +branch, then commit there: + +```bash +git checkout -b +# ... commits ... +git push -u origin +``` + +- Name the branch for the gateway/task it covers, kebab-case, e.g. + `g2-kpi-bmc-bpmn` or `mil-002-kpi-baseline` — short enough to read in a + PR list, specific enough to say what it's for. +- Open a PR (`gh pr create` on GitHub, or the Gitea equivalent) instead of + merging straight to `main`; this project's own history is a merged PR + per phase (e.g. "Merge pull request 'Close G1 inception baseline...'"), + so keep following that pattern. +- This applies to every commit, not just gateway/task work — if in doubt + whether the current branch is `main`, check (`git branch --show-current`) + before committing. + +## Closing tasks from commits + +When a commit finishes the work for a task that `sync-project.sh` has +already synced as an Issue, reference that Issue number in the commit +message so Gitea/GitHub auto-closes it once that commit lands on the +default branch (`main`) — via the PR merge required by "Branching before +commits" above, not by pushing the closing keyword to a feature branch. +Use `Refs #N` instead when the commit only touches the task without +finishing it — that links the commit without closing. + +- **One issue per commit:** use `Closes #5`. +- **Several issues closed by the same commit:** put one `Closes #N` per + line, not a comma-separated list (`Closes #5, #6, #7` only closed `#5` on + a confirmed live Gitea instance — the comma form is not reliably parsed): + + ``` + Closes #5 + Closes #6 + Closes #7 + ``` +- Get each issue number either from the most recent `sync-project.sh` / + `sync-project.sh --apply` output (it prints `updated issue #N` / + `created issue #N` per task) or, if that's not at hand, from the git + host's issue list for the milestone. +- Match commits to issues by the task row they implement — one task row in + a `MIL-*` document's `## Tasks` section is one Issue, so a commit that + completes that row's work closes that Issue. +- Don't guess an issue number; if it isn't known from a recent sync or a + lookup, ask rather than omit or fabricate one. +- **After pushing a multi-issue closing commit, verify** each issue's state + came back `closed` (e.g. `GET /repos///issues/` with + `GITEA_TOKEN`) rather than assuming the whole list closed; close any that + didn't with a direct `PATCH .../issues/` `{"state":"closed"}` call. + +## Pull requests close the issues they complete + +Every PR must close the Issues its work finishes, so the board matches +reality once it merges. Before opening (or updating) a PR: + +1. **List the issues the branch completes.** Go through the task rows the + branch implements (`git log main..HEAD`, plus the `## Tasks` of the + `MIL-*` it belongs to) and get each Issue number as described in "Closing + tasks from commits". +2. **Put one closing line per issue in the PR description**, one per line, + never comma-separated: + + ``` + Closes #5 + Closes #6 + ``` + + Use `Refs #N` for an issue the PR only touches. A PR that finishes no + issue says so explicitly ("No issue closed: ") instead of saying + nothing. +3. **Ask, don't guess.** If an issue number is unknown or a task is only + partly done, ask rather than omit or invent one. Leave a partly done task + open and note what remains. +4. **After the merge, verify** that each issue is `closed` (the check in + "Closing tasks from commits") and close any stragglers by hand. Also make + sure the finished task rows are reflected in the `MIL-*` document and, when + every task of a phase is closed, that the Milestone is closed too. + +5. **Resolve pending commit links before the PR** (see "Version History rule" + in the `artifact` skill): commit, run + `bash framework/scripts/resolve-pending-commits.sh `, then + commit the result as a follow-up commit. +6. **Never ask for, offer or perform the merge.** A PR needs a reviewer: ask + the user to open the PR / request a review, and stop there. Merging, + enabling auto-merge and "shall I merge?" are not yours to do. + +Closing keywords in the PR description and in commit messages both count on +Gitea and GitHub; they only take effect when the PR merges into the default +branch. + +## Files this skill touches + +- `docs/project-plan.md` — `PP`, via the `artifact` skill. +- `docs/milestones/mil-*.md` — `MIL`, via the `artifact` skill, each with a + `## Tasks` section. +- `docs/uc-NNN/*.md` (the use case and its `SSD`, `DM`, `OC`, `SD`, `DCD`, `ERD`), `docs/user-stories.md` — only for tasks that need one; plus `docs/domain-model.md`, `docs/dcd.md`, `docs/erd.md` when reconciling. +- `framework/scripts/sync-project.sh` — never edited per project; propose + changes upstream in the framework. diff --git a/.gitea/workflows/ci.yml b/.gitea/workflows/ci.yml new file mode 100644 index 0000000..9b34484 --- /dev/null +++ b/.gitea/workflows/ci.yml @@ -0,0 +1,26 @@ +# Runs on Gitea Actions (Gitea reads .gitea/workflows). +name: CI + +on: + push: + pull_request: + +jobs: + test: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: "3.13" + - name: Install + run: | + python -m venv .venv + .venv/bin/python -m pip install --upgrade pip + .venv/bin/python -m pip install -e ".[dev]" + - name: Lint + run: .venv/bin/ruff check . + - name: Type check + run: .venv/bin/mypy + - name: Test + run: .venv/bin/python -m pytest diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..ef1a1da --- /dev/null +++ b/.gitignore @@ -0,0 +1,179 @@ +# ---> Python +# Byte-compiled / optimized / DLL files +__pycache__/ +*.py[cod] +*$py.class + +# C extensions +*.so + +# Distribution / packaging +.Python +build/ +develop-eggs/ +dist/ +downloads/ +eggs/ +.eggs/ +lib/ +lib64/ +parts/ +sdist/ +var/ +wheels/ +share/python-wheels/ +*.egg-info/ +.installed.cfg +*.egg +MANIFEST + +# PyInstaller +# Usually these files are written by a python script from a template +# before PyInstaller builds the exe, so as to inject date/other infos into it. +*.manifest +*.spec + +# Installer logs +pip-log.txt +pip-delete-this-directory.txt + +# Unit test / coverage reports +htmlcov/ +.tox/ +.nox/ +.coverage +.coverage.* +.cache +nosetests.xml +coverage.xml +*.cover +*.py,cover +.hypothesis/ +.pytest_cache/ +cover/ + +# Translations +*.mo +*.pot + +# Django stuff: +*.log +local_settings.py +db.sqlite3 +db.sqlite3-journal + +# Flask stuff: +instance/ +.webassets-cache + +# Scrapy stuff: +.scrapy + +# Sphinx documentation +docs/_build/ + +# PyBuilder +.pybuilder/ +target/ + +# Jupyter Notebook +.ipynb_checkpoints + +# IPython +profile_default/ +ipython_config.py + +# pyenv +# For a library or package, you might want to ignore these files since the code is +# intended to run in multiple environments; otherwise, check them in: +# .python-version + +# pipenv +# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control. +# However, in case of collaboration, if having platform-specific dependencies or dependencies +# having no cross-platform support, pipenv may install dependencies that don't work, or not +# install all needed dependencies. +#Pipfile.lock + +# UV +# Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control. +# This is especially recommended for binary packages to ensure reproducibility, and is more +# commonly ignored for libraries. +#uv.lock + +# poetry +# Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control. +# This is especially recommended for binary packages to ensure reproducibility, and is more +# commonly ignored for libraries. +# https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control +#poetry.lock + +# pdm +# Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control. +#pdm.lock +# pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it +# in version control. +# https://pdm.fming.dev/latest/usage/project/#working-with-version-control +.pdm.toml +.pdm-python +.pdm-build/ + +# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm +__pypackages__/ + +# Celery stuff +celerybeat-schedule +celerybeat.pid + +# SageMath parsed files +*.sage.py + +# Environments +.env +.venv +env/ +venv/ +ENV/ +env.bak/ +venv.bak/ + +# Spyder project settings +.spyderproject +.spyproject + +# Rope project settings +.ropeproject + +# mkdocs documentation +/site + +# mypy +.mypy_cache/ +.dmypy.json +dmypy.json + +# Pyre type checker +.pyre/ + +# pytype static type analyzer +.pytype/ + +# Cython debug symbols +cython_debug/ + +# PyCharm +# JetBrains specific template is maintained in a separate JetBrains.gitignore that can +# be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore +# and can be added to the global gitignore or merged into this file. For a more nuclear +# option (not recommended) you can uncomment the following to ignore the entire idea folder. +#.idea/ + +# Ruff stuff: +.ruff_cache/ + +# PyPI configuration file +.pypirc + + +# Doxygen output +docs/doxygen/ diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 0000000..a759dc9 --- /dev/null +++ b/.gitmodules @@ -0,0 +1,3 @@ +[submodule "framework"] + path = framework + url = ssh://git@git.tirsystem.com:10022/TirSystem/SQA-QC-Framework.git diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..8437b2b --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,60 @@ +# AGENTS.md + +This project uses the SQA and QC framework mounted at `framework/`. + +For any document under `docs/` (create, edit or review) use the `artifact` +skill. For planning a project or a phase into tasks, and syncing phases and +tasks to Gitea/GitHub as Milestones and Issues, use the `project-planning` +skill. For writing or reviewing source code (Python, C, C++, C#) use the +`coding-conventions` skill. Skills are read from `.agents/skills/` (this harness and Codex CLI) +and `.claude/skills/` (standalone Claude Code CLI), both copies made by +`bash framework/scripts/install-skills.sh` — re-run it after updating the +framework. + +**Never commit, push or open a PR unless asked.** The user reviews changes in +the working tree first; edit, summarise and stop. The commit/PR rules below +apply once a commit has been asked for. + +## Workflow order + +Business Case, Stakeholder Analysis, Project Plan, milestones, tasks synced as +issues, then code, each step reviewed before the next (an artifact is done when +its `RC-*` says `Go` and its row is `Accepted`; code is reviewed against its +`qc-programming-*` checklist before the pull request). Nothing goes under `src/` +or `tests/` unless a milestone document (`MIL-*`) is accepted, its latest review +is a `Go`, and the task is a row in it (ideally a synced issue). If those are missing, plan with the `project-planning` skill, show the +dry-run output of `bash framework/scripts/sync-project.sh`, and stop. The rule +is defined once in `framework/process/plan-first-gate.md`. + +A "build X" request is planning-first: produce the plan and issues, then ask +for a go-ahead. Only the user can waive the plan, in chat, for that request. +Before planning, find the Product Owner's language (the prompt, or the +`Languages` section of `docs/artifact-registry.md`); if neither states it, ask. +Each artifact type the registry marks "Written in the PO language" exists once, +in that language, under its normal name; there is no translated twin. Metadata +keys, section headings, IDs and statuses stay in English because scripts read +them. + +To enforce the gate at commit time, run +`bash framework/scripts/install-git-hooks.sh --enable-plan-gate`: a commit that +changes `src/` or `tests/` then needs a `Task: MIL-NNN#N` trailer for an +accepted, reviewed milestone. + +Rules that apply to every document: + +1. Get the short name from `framework/registry/artifact-catalog.md` and the + next version from `docs/artifact-registry.md`. Create files with + `bash framework/scripts/new-artifact.sh `. +2. Owners, reviewers and RACI use stakeholder IDs from the project's + Stakeholder Analysis, never invented role names. +3. Every QC criterion is tagged with an ISO/IEC 25010:2023 characteristic. +4. Every reviewed instance gets an `RC-*` record in `docs/sqa/reviews/`. +5. Do not edit `framework/` from this project; propose changes upstream. +6. Every PR description closes the issues its work completes, one + `Closes #N` per line (`Refs #N` for partial work); see the + `project-planning` skill. +7. Every document's `## Version History` has `Change` and `Commit` columns and + keeps the two latest rows. After committing, run + `framework/scripts/resolve-pending-commits.sh` and commit the result before + opening the PR (no amend). Never ask for or perform the merge: a reviewer + merges. diff --git a/Doxyfile b/Doxyfile new file mode 100644 index 0000000..88acf99 --- /dev/null +++ b/Doxyfile @@ -0,0 +1,16 @@ +# Doxygen configuration. Run `doxygen Doxyfile` from the repository root. +PROJECT_NAME = "Pretty Table" +PROJECT_BRIEF = "Udemy 100 Days of Code: Pokemon type table with PrettyTable" +OUTPUT_DIRECTORY = docs/doxygen +INPUT = src README.md +USE_MDFILE_AS_MAINPAGE = README.md +FILE_PATTERNS = *.py *.md +RECURSIVE = YES +OPTIMIZE_OUTPUT_JAVA = YES +EXTRACT_ALL = YES +EXTRACT_PRIVATE = NO +GENERATE_HTML = YES +GENERATE_LATEX = NO +QUIET = YES +WARN_IF_UNDOCUMENTED = YES +WARN_AS_ERROR = NO diff --git a/README.md b/README.md index 104828b..a326095 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,146 @@ -# 016-pretty_table +# Pretty Table +A table of Pokémon and their types, printed with the PrettyTable package from PyPI. +It is an assignment of Udemy's *100 Days of Code: The Complete Python Pro Bootcamp* +about adding Python packages. The functions use the assignment's style: `create_table` +builds the `PrettyTable` and `main` prints it. PrettyTable is the only runtime dependency. + +## Requirements + +- Python 3.13 or newer. +- `venv` and `pip`, which come with Python (on Debian they are separate packages). +- Git, to clone the repository. +- Optional: [Doxygen](https://www.doxygen.nl/) to build the source documentation. + +`prettytable` is installed from PyPI with the project. `pytest`, `ruff` and `mypy` +are installed only for development, through the `dev` extra. + +## Set up + +Clone the repository and change into it: + +```bash +git clone https://git.tirsystem.com/Tirsvad-Udemy-100_days_of_code/016-pretty_table.git +cd 016-pretty_table +``` + +Then create a local virtual environment named `.venv`, upgrade `pip` and install +the project in it. + +### Windows powershell + +```powershell +python -m venv .venv +.\.venv\Scripts\Activate.ps1 +python -m pip install --upgrade pip +python -m pip install -e ".[dev]" +``` + +If PowerShell refuses to run the activation script, allow it for this window only +with `Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass`. + +### Linux debian + +```bash +sudo apt install python3 python3-venv python3-pip git +python3 -m venv .venv +source .venv/bin/activate +python -m pip install --upgrade pip +python -m pip install -e ".[dev]" +``` + +Debian 13 (trixie) ships Python 3.13. On an older release, install Python 3.13 +first (for example with `pyenv`) and use it to create the `.venv`. + +### MacOS + +```bash +brew install python@3.13 git +python3.13 -m venv .venv +source .venv/bin/activate +python -m pip install --upgrade pip +python -m pip install -e ".[dev]" +``` + +To leave the virtual environment, run `deactivate`. + +## Run + +With the virtual environment active: + +```bash +python -m pretty_table +``` + +The installed command does the same: + +```bash +pretty-table +``` + +Output: + +```text ++--------------+----------+ +| Pokemon Name | Type | ++--------------+----------+ +| Pikachu | Electric | +| Squirtle | Water | +| Charmander | Fire | ++--------------+----------+ +``` + +## Run the tests + +With the virtual environment active: + +```bash +python -m pytest +``` + +The linter and the strict type check that the project also uses: + +```bash +ruff check . +mypy +``` + +## Continuous integration + +The workflow in `.gitea/workflows/ci.yml` runs on Gitea Actions on every push and +pull request. It creates a virtual environment on Python 3.13, upgrades `pip`, +installs the project with the `dev` extra and runs `ruff check .`, `mypy` and +`python -m pytest`. GitHub does not read the `.gitea` folder, so a GitHub mirror +does not run it. + +## Build the source documentation + +The source uses Doxygen comments and the `Doxyfile` in the repository root. Install +Doxygen (`winget install DimitriVanHeesch.Doxygen` on Windows, +`sudo apt install doxygen` on Debian, `brew install doxygen` on MacOS), then run: + +```bash +doxygen Doxyfile +``` + +The HTML documentation is written to `docs/doxygen/html/`; open `index.html` in a +browser. The output folder is ignored by git. + +## Project layout + +```text +. +├── src/pretty_table/ The program +│ ├── constants.py Column titles and the Pokémon rows +│ ├── main.py create_table and main +│ └── __main__.py Entry point for python -m pretty_table +├── tests/ pytest tests +├── docs/ Project documents (business case, plan, reviews) +├── .gitea/workflows/ Continuous integration workflow +├── Doxyfile Doxygen configuration +└── pyproject.toml Project configuration +``` + +## License + +GNU Affero General Public License v3.0; see [LICENSE](LICENSE). diff --git a/docs/artifact-registry.md b/docs/artifact-registry.md new file mode 100644 index 0000000..4ba60b2 --- /dev/null +++ b/docs/artifact-registry.md @@ -0,0 +1,58 @@ +# Artifact Registry + +This project's artifact state. Types, short names and `CrossReference +Candidates` come from the framework catalog +(`framework/registry/artifact-catalog.md`); this file only records where +each document lives in *this* project and the next version to use. + +Delete rows for types you don't use. Add a row the first time you create a +document of a type. `Primary File` may contain a glob (e.g. +`docs/uc-*/uc.md`); `framework/scripts/find-crossreferences.sh` reads it. + +| Short Name | Artifact Type | Primary File | Next Available Version | +| --- | --- | --- | --- | +| BC | Business Case | docs/business-case.md | 002 | +| SA | Stakeholder Analysis | docs/stakeholder-analysis.md | 002 | +| PP | Project Plan | docs/project-plan.md | 002 | +| MIL | Milestone / Gateway | docs/milestones/*.md | 002 | +| RC | SQA Review Record | docs/sqa/reviews/rc-*.md | 004 | + +## Languages + +Set the PO language when the project starts; `project-planning` asks for it +if it is missing. An artifact of a type marked "Written in the PO language" +exists once, in that language, under its normal name (`business-case.md`); the +`artifact` skill ("One file per artifact") has the rule. + +| Setting | Value | +| --- | --- | +| PO language | en | +| PO domain | it | +| High-level register | IT Executive English | +| Technical register | IT Professional English | + +Every artifact of a type marked "Yes" below states its language and domain in +its `Language` and `Domain` Metadata rows; `new-artifact.sh` fills them from +`PO language` and `PO domain`. `Language` is a BCP 47 code (`da`, `en`). +`Domain` is a value from this list; add a row to introduce a domain, so a +reviewer can see at once which professional vocabulary a document uses. + +| Domain | Meaning | +| --- | --- | +| it | Software and IT | +| medical | Healthcare and medical devices | +| construction | Construction and civil engineering | + +| Artifact types | Register | Written in the PO language | +| --- | --- | --- | +| BC, KPI, PP, MIL | IT Executive English | Yes | +| SA, BMC, BPMN, UCD, US, UC, SSD, DM, RA, GOV, DICT | IT Professional English | Yes | +| OC, SD, DCD, ERD, ADR, TM, RC, QC, source code | IT Professional English | No | + +## Notes + +- "Next Available Version" is the zero-padded (3-digit) version to use the + *next* time a new document of that type is created. Increment it only when + a brand-new document is created, not when an existing document's + `## Version History` gets a row. +- `ADR` uses 4 digits (`0001`); `RC` is sequential across all artifact types. diff --git a/docs/business-case.md b/docs/business-case.md new file mode 100644 index 0000000..1643395 --- /dev/null +++ b/docs/business-case.md @@ -0,0 +1,121 @@ +# Business Case + +## Metadata +| Key | Value | +| --- | --- | +| ID | BC-001 | +| CrossReference | [SA-001] | +| Language | en | +| Domain | it | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| 2026-10-07 | Accepted | Jens Tirsvad Nielsen | S01 | Initial version | pending | + +--- + +## Executive Summary + +This project delivers the Udemy "100 Days of Code" lesson on adding Python packages from PyPI. It is a small, runnable Python program that builds a table of Pokémon names and types with the PrettyTable package, packaged as a clean, tested and documented repository that other course participants and GitHub visitors can read and run. The effort is deliberately small, and the single runtime dependency is the one the assignment teaches. + +## Methodological and Standards Foundation + +The work follows the SQA and QC framework mounted at `framework/` (Business Case, Stakeholder Analysis, Project Plan, milestones, tasks as issues, then code). Quality characteristics follow ISO/IEC 25010:2023. Code follows the framework's `coding-conventions` skill for Python and is reviewed against its `qc-programming-*` checklist. + +## Problem Statement + +The assignment solution exists only as lesson material. Without a repository there is nothing to share, compare or reuse, and the install-and-import workflow for PyPI packages is not documented in a reproducible form (virtual environment, dependency declaration, tests). + +## Business Opportunity + +A clear, runnable reference solution lets other course participants compare their code, and gives GitHub viewers a tidy example of a small Python project with tests, documentation and project configuration. + +## Objectives + +1. O1: Provide a Python program that prints the Pokémon type table with PrettyTable, using the assignment's function names. +2. O2: Document how to create and use a local `.venv`, upgrade pip, run the program and run the tests. +3. O3: Provide pytest tests, a `pyproject.toml`, constants in `constants.py`, Doxygen comments and a Doxyfile. +4. O4: Publish the repository with a description and topics. + +## Scope + +### In Scope + +- Python 3.13 or newer source under `src/`, tests under `tests/`, documents under `docs/`. +- `pyproject.toml`, Python `.gitignore`, `Doxyfile`, and a README built from the template. +- Repository description and topics on the git host. + +### Out of Scope + +- Features beyond the lesson (the PrettyTable styling exercises of later lessons). +- Publishing the package to PyPI. +- Using, importing or testing the `.env` file; it is personal and only used to reach the git host. + +## Expected Benefits + +### Tangible Benefits + +- A runnable, tested repository that others can clone and run in minutes. +- A reproducible environment recipe for Windows, Linux and macOS. + +### Intangible Benefits + +- A consistent portfolio of course assignments. +- Practice with packages, PyPI and project hygiene. + +## Strategic Alignment + +The project supports the participant's goal of completing the bootcamp with consistent, reviewable work, and the community goal of sharing readable solutions. + +## Success Criteria + +| # | Criterion | Target | Measure | +| --- | --- | --- | --- | +| 1 | Program prints the Pokémon table | Exit code 0 and the expected table text | pytest test of the rendered table | +| 2 | Tests pass | 100% of tests pass in a fresh `.venv` | `python -m pytest` | +| 3 | README steps work | A new reader runs the program using only the README | Manual walkthrough on one OS | +| 4 | Repository metadata | Description and at least 3 topics set | Inspect the repository page | + +## Risks + +| Risk | Impact | Mitigation | +| --- | --- | --- | +| PrettyTable API changes | Output or tests break | Declare a minimum version in `pyproject.toml` and test the rendered output | +| Token leaks into the repository | Credential exposure | `.env` is git-ignored and never imported or tested | +| Over-engineering a tiny assignment | Wasted effort | Keep one runtime dependency and a minimal layout | + +## Assumptions + +- Python 3.13 or newer is installed by the reader. +- PyPI is reachable when installing PrettyTable. +- The git host accepts a description and topics through its API. + +## Constraints + +- Python 3.13 or newer, `venv` for environments, pytest for tests. +- Constants live in `constants.py`; source uses Doxygen comments. +- Configuration lives in `pyproject.toml`. +- Only the user performs commits, pushes and merges. + +## Cost–Benefit Assessment + +| Costs | Benefits | +| --- | --- | +| A few hours of the participant's time; no licence or hosting cost | A shareable, tested reference solution and a reusable project template | + +## Stakeholders + +| Stakeholder ID (SA) | Interest in this project | +| --- | --- | +| S01 | Owns the work and wants an accepted, reviewed result | +| S02 | Wants readable, runnable code with the assignment's function names | +| S03 | Wants a clear description, topics and README, with no runtime dependencies beyond the lesson's | + +## Recommendation + +Proceed — the scope is small, the cost is minimal and the result is directly reusable. + +--- + +[SA-001]: ./stakeholder-analysis.md diff --git a/docs/milestones/mil-001-pretty-table-project.md b/docs/milestones/mil-001-pretty-table-project.md new file mode 100644 index 0000000..87a4fa7 --- /dev/null +++ b/docs/milestones/mil-001-pretty-table-project.md @@ -0,0 +1,81 @@ +# G1 Project delivery + +## Metadata +| Key | Value | +| --- | --- | +| ID | MIL-001 | +| CrossReference | [BC-001], [SA-001] | +| Language | en | +| Domain | it | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| 2026-10-07 | Accepted | Jens Tirsvad Nielsen | S01 | Initial version | pending | + +--- + +## Purpose + +Decide whether the Pretty Table project is complete enough to publish: runnable, tested, documented and described on the git host. + +## Deliverable + +A Python 3.13+ project with `src/`, `tests/`, `docs/`, `pyproject.toml`, `constants.py`, `Doxyfile`, a Python `.gitignore` and a README built from the template, plus a repository description and topics. + +## Go / No-Go Criteria + +| # | Criterion (objectively checkable) | Go | No-Go | +| --- | --- | --- | --- | +| 1 | `python -m pytest` passes in a fresh `.venv` | All tests pass | Any failure | +| 2 | The program prints the Pokémon type table | Output matches the tested table | Output differs or the run fails | +| 3 | The README follows the template and its steps work | Each section is filled and the steps run | A section is missing or a step fails | +| 4 | Runtime dependencies | Only PrettyTable | Any other runtime dependency | +| 5 | Repository description and at least 3 topics are set | Visible on the repository page | Missing | +| 6 | Code review record against `qc-programming-python` | `RC-*` says Go | No review or No-Go | + +## Dependencies + +| Depends on | Reason | +| --- | --- | +| [BC-001] | Scope and success criteria | +| [SA-001] | Stakeholders S01, S02, S03 | + +## Traceability + +| Business Case objective / KPI / user story | Reference | +| --- | --- | +| O1 Pokémon table program | Tasks 3, 4 | +| O2 Documented run, venv and tests | Tasks 1, 6 | +| O3 Tests, pyproject, constants, Doxygen | Tasks 1, 2, 4, 5 | +| O4 Repository published with description and topics | Task 8 | + +## Ownership + +| Role | Stakeholder ID (SA) | +| --- | --- | +| Owner | S01 | +| Approving reviewer | S01 | + +## Target Date + +2026-10-14 — one week from the start, consistent with the Business Case's small scope. + +## Tasks + +| # | Task | Summary | Needs its own Use Case/User Story? | Reference | +| --- | --- | --- | --- | --- | +| 1 | Configure project files | Create `pyproject.toml` (Python 3.13 or newer, PrettyTable runtime dependency, pytest as a dev dependency) and a Python `.gitignore` that also ignores `.env` and `.venv`. Supports O2 and O3. | No | | +| 2 | Add constants module | Create `src/constants.py` holding the Pokémon names, types and column titles so no literals are scattered in the code. Supports O3. | No | | +| 3 | Implement the Pokémon table | Create the program in `src/` that builds and prints the PrettyTable of Pokémon and their types (for example Pikachu Electric, Squirtle Water), with the assignment's function names and Doxygen comments. Supports O1. | No | | +| 4 | Add pytest tests | Create tests in `tests/` that check the rendered table and the program's output, run with `python -m pytest`. Supports O1 and O3. | No | | +| 5 | Add Doxyfile | Create a `Doxyfile` that builds the source documentation from `src/`. Supports O3. | No | | +| 6 | Write the README | Write `README.md` from the template: requirements, local `.venv` and `python -m pip install --upgrade pip` for Windows PowerShell, Linux Debian and macOS, running, testing, CI, Doxygen and layout. Supports O2. | No | | +| 7 | Describe continuous integration | Add a CI workflow that installs the project and runs pytest, and explain it in the README CI section. Supports O2. | No | | +| 8 | Set repository description and topics | Use the token from the personal `.env` (never committed, imported or tested) to set the description and topics on the git host. Supports O4. | No | | +| 9 | Review code against the Python checklist | Review the source and tests against `qc-programming-python` and record an `RC-*` before the pull request. Supports Go criterion 6. | No | | + +--- + +[BC-001]: ../business-case.md +[SA-001]: ../stakeholder-analysis.md diff --git a/docs/project-plan.md b/docs/project-plan.md new file mode 100644 index 0000000..58f3f24 --- /dev/null +++ b/docs/project-plan.md @@ -0,0 +1,71 @@ +# Project Plan + +## Metadata +| Key | Value | +| --- | --- | +| ID | PP-001 | +| CrossReference | [BC-001], [SA-001], [MIL-001] | +| Language | en | +| Domain | it | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| 2026-10-07 | Accepted | Jens Tirsvad Nielsen | S01 | Initial version | pending | + +--- + +## Purpose + +Schedules the single delivery phase of the Pretty Table assignment so that the repository can be published within one week, as the Business Case's small-scope constraint implies. + +## Planning Assumptions + +- Week 1 starts 2026-10-07; the plan ends by 2026-10-14. +- One phase of one week; the Product Owner (S01) is the only decision maker, per [SA-001]. + +## Gateway Schedule + +| Gateway | Document | Window | Decision date | Owner | Stories | Main deliverable | Milestone | +| --- | --- | --- | --- | --- | --- | --- | --- | +| G1 Project delivery | [MIL-001] | 2026-10-07 to 2026-10-14 | 2026-10-14 | S01 | none | Tested, documented Python project and published repository metadata | | + +```plantuml +@startgantt +Project starts 2026-10-07 +[G1 Project delivery] starts 2026-10-07 and ends 2026-10-14 +[G1 Go/No-Go] happens 2026-10-14 +@endgantt +``` + +## Scope Coverage + +| Business Case scope item | Gateway | +| --- | --- | +| Source under `src/`, tests under `tests/`, documents under `docs/` | G1 | +| `pyproject.toml`, `.gitignore`, `Doxyfile`, README | G1 | +| Repository description and topics | G1 | + +## Dependencies + +``` +G1 Project delivery +``` + +A No-Go on G1 moves the decision date until the failed criteria are fixed. + +## Plan Risks + +| Risk | Impact | Mitigation | +| --- | --- | --- | +| Git host API is unavailable for description and topics | Task cannot be completed | Set them by hand on the repository page | + +## Open Issues + +- The assignment's exact function names are not given in the task text; the code uses `create_table` and `main`, to be adjusted if S01 names others. + +--- + +[BC-001]: ./business-case.md +[SA-001]: ./stakeholder-analysis.md +[MIL-001]: ./milestones/mil-001-pretty-table-project.md diff --git a/docs/sqa/reviews/rc-001-business-case.md b/docs/sqa/reviews/rc-001-business-case.md new file mode 100644 index 0000000..081a4a1 --- /dev/null +++ b/docs/sqa/reviews/rc-001-business-case.md @@ -0,0 +1,60 @@ +# SQA Review Record + +## Metadata +| Key | Value | +| --- | --- | +| ID | RC-001 | +| CrossReference | [BC-001] | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| 2026-10-07 | Proposed | Jens Tirsvad Nielsen | S01 | Initial version | pending | + +--- + +## Artifact Under Review + +- Instance reviewed: [BC-001] +- Checklist used: none available; the `BC` reference in the `artifact` skill (`references/BC.md`) +- Scope: full review. The QC checklist named in the catalog is not present: `framework/qc/` is empty in this clone. The criteria below are the required sections and rules of the type's `references/` file. +- Language and domain: en / it +- Language reviewer: none (S01 reads English and knows the domain) + +## Checklist Results + +| # | Criterion | Status | Evidence/Notes | +| --- | --- | --- | --- | +| 1 | Executive Summary | Pass | Present and filled in the instance | +| 2 | Methodological and Standards Foundation | Pass | Present and filled in the instance | +| 3 | Problem Statement | Pass | Present and filled in the instance | +| 4 | Business Opportunity | Pass | Present and filled in the instance | +| 5 | Objectives | Pass | Present and filled in the instance | +| 6 | Scope (In/Out) | Pass | Present and filled in the instance | +| 7 | Expected Benefits (Tangible/Intangible) | Pass | Present and filled in the instance | +| 8 | Strategic Alignment | Pass | Present and filled in the instance | +| 9 | Success Criteria (measurable) | Pass | Present and filled in the instance | +| 10 | Risks (each with mitigation) | Pass | Present and filled in the instance | +| 11 | Assumptions | Pass | Present and filled in the instance | +| 12 | Constraints | Pass | Present and filled in the instance | +| 13 | Cost-Benefit Assessment | Pass | Present and filled in the instance | +| 14 | Stakeholders cite SA IDs, no re-description | Pass | Present and filled in the instance | +| 15 | Recommendation (single proceed statement) | Pass | Present and filled in the instance | + +## Language and Domain Results + +QC-LANG-001 is not available in this clone. Spot check: the document is in English, in the IT domain, with the `Language` and `Domain` rows set, and uses the PO's terms. + +## Overall Verdict + +Go — every required section is present and consistent with the Business Case and Stakeholder Analysis. The author and the reviewer are both S01, the only stakeholder with the authority; the PO explicitly instructed acceptance in chat on 2026-10-07. + +## Action Items + +| Action | Owner | Due | +| --- | --- | --- | +| Re-review against the QC checklist once `framework/qc/` is populated | S01 | when the framework provides it | + +--- + +[BC-001]: ../../business-case.md diff --git a/docs/sqa/reviews/rc-002-stakeholder-analysis.md b/docs/sqa/reviews/rc-002-stakeholder-analysis.md new file mode 100644 index 0000000..1bce657 --- /dev/null +++ b/docs/sqa/reviews/rc-002-stakeholder-analysis.md @@ -0,0 +1,53 @@ +# SQA Review Record + +## Metadata +| Key | Value | +| --- | --- | +| ID | RC-002 | +| CrossReference | [SA-001] | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| 2026-10-07 | Proposed | Jens Tirsvad Nielsen | S01 | Initial version | pending | + +--- + +## Artifact Under Review + +- Instance reviewed: [SA-001] +- Checklist used: none available; the `SA` reference in the `artifact` skill (`references/SA.md`) +- Scope: full review. The QC checklist named in the catalog is not present: `framework/qc/` is empty in this clone. The criteria below are the required sections and rules of the type's `references/` file. +- Language and domain: en / it +- Language reviewer: none (S01 reads English and knows the domain) + +## Checklist Results + +| # | Criterion | Status | Evidence/Notes | +| --- | --- | --- | --- | +| 1 | Purpose | Pass | Present and filled in the instance | +| 2 | Stakeholder Summary Table fully filled | Pass | Present and filled in the instance | +| 3 | Classification Rationale consistent with the table | Pass | Present and filled in the instance | +| 4 | Concerns mapped to FURPS+ | Pass | Present and filled in the instance | +| 5 | Communication Requirements | Pass | Present and filled in the instance | +| 6 | Every conflict has a mitigation | Pass | Present and filled in the instance | +| 7 | Traceability cites BC-001 objectives | Pass | Present and filled in the instance | +| 8 | Sign-Off | Pass | Present and filled in the instance | + +## Language and Domain Results + +QC-LANG-001 is not available in this clone. Spot check: the document is in English, in the IT domain, with the `Language` and `Domain` rows set, and uses the PO's terms. + +## Overall Verdict + +Go — every required section is present and consistent with the Business Case and Stakeholder Analysis. The author and the reviewer are both S01, the only stakeholder with the authority; the PO explicitly instructed acceptance in chat on 2026-10-07. + +## Action Items + +| Action | Owner | Due | +| --- | --- | --- | +| Re-review against the QC checklist once `framework/qc/` is populated | S01 | when the framework provides it | + +--- + +[SA-001]: ../../stakeholder-analysis.md diff --git a/docs/sqa/reviews/rc-003-milestone-g1.md b/docs/sqa/reviews/rc-003-milestone-g1.md new file mode 100644 index 0000000..af7bc88 --- /dev/null +++ b/docs/sqa/reviews/rc-003-milestone-g1.md @@ -0,0 +1,53 @@ +# SQA Review Record + +## Metadata +| Key | Value | +| --- | --- | +| ID | RC-003 | +| CrossReference | [MIL-001] | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| 2026-10-07 | Proposed | Jens Tirsvad Nielsen | S01 | Initial version | pending | + +--- + +## Artifact Under Review + +- Instance reviewed: [MIL-001] +- Checklist used: none available; the `MIL` reference in the `artifact` skill (`references/MIL.md`) +- Scope: full review. The QC checklist named in the catalog is not present: `framework/qc/` is empty in this clone. The criteria below are the required sections and rules of the type's `references/` file. +- Language and domain: en / it +- Language reviewer: none (S01 reads English and knows the domain) + +## Checklist Results + +| # | Criterion | Status | Evidence/Notes | +| --- | --- | --- | --- | +| 1 | Purpose | Pass | Present and filled in the instance | +| 2 | Deliverable is concrete | Pass | Present and filled in the instance | +| 3 | Go/No-Go criteria objectively checkable | Pass | Present and filled in the instance | +| 4 | Dependencies | Pass | Present and filled in the instance | +| 5 | Traceability to BC objectives | Pass | Present and filled in the instance | +| 6 | Ownership uses SA stakeholder IDs | Pass | Present and filled in the instance | +| 7 | Target Date consistent with BC | Pass | Present and filled in the instance | +| 8 | Tasks table: Task/Summary/Needs-UC/Reference, plain tasks marked No | Pass | Present and filled in the instance | + +## Language and Domain Results + +QC-LANG-001 is not available in this clone. Spot check: the document is in English, in the IT domain, with the `Language` and `Domain` rows set, and uses the PO's terms. + +## Overall Verdict + +Go — every required section is present and consistent with the Business Case and Stakeholder Analysis. The author and the reviewer are both S01, the only stakeholder with the authority; the PO explicitly instructed acceptance in chat on 2026-10-07. + +## Action Items + +| Action | Owner | Due | +| --- | --- | --- | +| Re-review against the QC checklist once `framework/qc/` is populated | S01 | when the framework provides it | + +--- + +[MIL-001]: ../../milestones/mil-001-pretty-table-project.md diff --git a/docs/stakeholder-analysis.md b/docs/stakeholder-analysis.md new file mode 100644 index 0000000..a458e9c --- /dev/null +++ b/docs/stakeholder-analysis.md @@ -0,0 +1,74 @@ +# Stakeholder Analysis + +## Metadata +| Key | Value | +| --- | --- | +| ID | SA-001 | +| CrossReference | [BC-001] | +| Language | en | +| Domain | it | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| 2026-10-07 | Accepted | Jens Tirsvad Nielsen | S01 | Initial version | pending | + +--- + +## Purpose + +Identify who is affected by the project and what each needs, using a power/interest grid, so the plan and the README serve them. + +## Stakeholder Summary Table + +| ID | Name | Role/Title | Organization | Power Level | Interest Level | Quadrant | Primary Concern (Business Language) | +| --- | --- | --- | --- | --- | --- | --- | --- | +| S01 | Jens Tirsvad Nielsen | Course participant: Product Owner, developer and reviewer | Tirsvad | HIGH | HIGH | Manage Closely | A finished, reviewed assignment that follows the framework | +| S02 | Udemy coursists | Fellow course participants | Udemy community | LOW | HIGH | Keep Informed | Readable, runnable code with the assignment's function names, and README run instructions | +| S03 | GitHub viewers | Repository browsers | Public | LOW | LOW | Monitor | A clear repository description, topics and README, and no runtime dependencies beyond the lesson's | + +## Power/Interest Classification Rationale + +- **Manage Closely:** S01 decides scope, writes and reviews everything. +- **Keep Informed:** S02 cannot change the project but depends on its code and README. +- **Monitor:** S03 browses for ideas and has no say; the description, topics and README are enough. + +## Primary Concerns and FURPS+ Mapping + +| ID | Concern | FURPS+ attribute | +| --- | --- | --- | +| S01 | Work follows the plan-first process and is verified by tests | Functionality, Supportability | +| S02 | Code is readable and runs with the documented steps | Usability, Functionality | +| S03 | Repository is self-explanatory and light | Usability, Implementation (no extra runtime dependencies) | + +## Communication Requirements + +| ID | Channel | Frequency | Deliverable | Phase / Milestone | +| --- | --- | --- | --- | --- | +| S01 | Chat review of the working tree | Per phase | Reviewed documents and code | All | +| S02 | README | Once, on publication | Run and test instructions | Delivery | +| S03 | Repository page | Once, on publication | Description, topics, README | Delivery | + +## Conflicting Interests and Mitigations + +| Conflict | Stakeholders | Mitigation | +| --- | --- | --- | +| S02 wants the assignment's exact function names; S03 wants a tidy, idiomatic project | S02, S03 | Keep the assignment's names for public functions and apply the conventions everywhere else | + +## Traceability Analysis + +### Business Goal Alignment + +| Stakeholder | Concern | Business Case objective | +| --- | --- | --- | +| S01 | Reviewed, framework-compliant work | [BC-001] O3, O4 | +| S02 | Runnable code and instructions | [BC-001] O1, O2 | +| S03 | Clear repository presentation | [BC-001] O4 | + +## Sign-Off + +Accepted by S01 (RC-002). + +--- + +[BC-001]: ./business-case.md diff --git a/framework b/framework new file mode 160000 index 0000000..ce1f9dd --- /dev/null +++ b/framework @@ -0,0 +1 @@ +Subproject commit ce1f9ddd3c7a8d32ff30a50755fdc777f5a0c183 diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 0000000..be88f7d --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,39 @@ +[build-system] +requires = ["setuptools>=68"] +build-backend = "setuptools.build_meta" + +[project] +name = "pretty-table-pokemon" +version = "0.1.0" +description = "Pokemon type table with PrettyTable from Udemy's 100 Days of Code: The Complete Python Pro Bootcamp." +readme = "README.md" +requires-python = ">=3.13" +license = { file = "LICENSE" } +authors = [{ name = "Jens Tirsvad Nielsen" }] +# PrettyTable is the package the lesson teaches; it is the only runtime dependency. +dependencies = ["prettytable>=3.10"] + +[project.optional-dependencies] +dev = ["pytest>=8", "ruff>=0.6", "mypy>=1.11"] + +[project.scripts] +pretty-table = "pretty_table.main:main" + +[tool.setuptools.packages.find] +where = ["src"] + +[tool.pytest.ini_options] +testpaths = ["tests"] +pythonpath = ["src"] + +[tool.ruff] +line-length = 88 +target-version = "py313" + +[tool.ruff.lint] +select = ["E", "F", "I", "N", "UP", "B"] + +[tool.mypy] +strict = true +python_version = "3.13" +files = ["src", "tests"] diff --git a/src/pretty_table/__init__.py b/src/pretty_table/__init__.py new file mode 100644 index 0000000..97ced3d --- /dev/null +++ b/src/pretty_table/__init__.py @@ -0,0 +1,4 @@ +"""! +@file __init__.py +@brief Pokemon type table built with PrettyTable. +""" diff --git a/src/pretty_table/__main__.py b/src/pretty_table/__main__.py new file mode 100644 index 0000000..7ec2a28 --- /dev/null +++ b/src/pretty_table/__main__.py @@ -0,0 +1,8 @@ +"""! +@file __main__.py +@brief Entry point for `python -m pretty_table`. +""" + +from pretty_table.main import main + +main() diff --git a/src/pretty_table/constants.py b/src/pretty_table/constants.py new file mode 100644 index 0000000..0218c23 --- /dev/null +++ b/src/pretty_table/constants.py @@ -0,0 +1,20 @@ +"""! +@file constants.py +@brief Constants of the Pokemon table: column titles and the rows shown. +""" + +## Title of the column holding the Pokemon name. +COLUMN_NAME: str = "Pokemon Name" + +## Title of the column holding the Pokemon type. +COLUMN_TYPE: str = "Type" + +## Column titles in display order. +COLUMN_TITLES: tuple[str, str] = (COLUMN_NAME, COLUMN_TYPE) + +## Pokemon names in display order, paired with their type. +POKEMON: tuple[tuple[str, str], ...] = ( + ("Pikachu", "Electric"), + ("Squirtle", "Water"), + ("Charmander", "Fire"), +) diff --git a/src/pretty_table/main.py b/src/pretty_table/main.py new file mode 100644 index 0000000..51927c6 --- /dev/null +++ b/src/pretty_table/main.py @@ -0,0 +1,30 @@ +"""! +@file main.py +@brief Builds and prints the Pokemon type table with PrettyTable. +""" + +from prettytable import PrettyTable + +from pretty_table.constants import COLUMN_NAME, COLUMN_TYPE, POKEMON + + +def create_table() -> PrettyTable: + """! + @brief Build the table of Pokemon names and their types. + @return A PrettyTable with one row per Pokemon in POKEMON. + """ + table = PrettyTable() + table.add_column(COLUMN_NAME, [name for name, _ in POKEMON]) + table.add_column(COLUMN_TYPE, [type_ for _, type_ in POKEMON]) + return table + + +def main() -> None: + """! + @brief Print the Pokemon type table to standard output. + """ + print(create_table()) + + +if __name__ == "__main__": + main() diff --git a/tests/__init__.py b/tests/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/tests/test_constants.py b/tests/test_constants.py new file mode 100644 index 0000000..3c98163 --- /dev/null +++ b/tests/test_constants.py @@ -0,0 +1,17 @@ +"""Tests for the constants.""" + +from pretty_table import constants + + +def test_column_titles_match_the_column_constants() -> None: + assert constants.COLUMN_TITLES == (constants.COLUMN_NAME, constants.COLUMN_TYPE) + + +def test_pokemon_includes_the_lesson_examples() -> None: + assert ("Pikachu", "Electric") in constants.POKEMON + assert ("Squirtle", "Water") in constants.POKEMON + + +def test_pokemon_names_are_unique() -> None: + names = [name for name, _ in constants.POKEMON] + assert len(names) == len(set(names)) diff --git a/tests/test_main.py b/tests/test_main.py new file mode 100644 index 0000000..f3b4d04 --- /dev/null +++ b/tests/test_main.py @@ -0,0 +1,40 @@ +"""Tests for the Pokemon table.""" + +import pytest +from prettytable import PrettyTable + +from pretty_table.constants import COLUMN_TITLES, POKEMON +from pretty_table.main import create_table, main + +EXPECTED_TABLE = """\ ++--------------+----------+ +| Pokemon Name | Type | ++--------------+----------+ +| Pikachu | Electric | +| Squirtle | Water | +| Charmander | Fire | ++--------------+----------+ +""" + + +def test_create_table_returns_prettytable() -> None: + assert isinstance(create_table(), PrettyTable) + + +def test_create_table_has_the_column_titles() -> None: + assert tuple(create_table().field_names) == COLUMN_TITLES + + +def test_create_table_has_one_row_per_pokemon() -> None: + table = create_table() + assert len(table.rows) == len(POKEMON) + assert [tuple(row) for row in table.rows] == list(POKEMON) + + +def test_create_table_renders_the_expected_text() -> None: + assert create_table().get_string() == EXPECTED_TABLE.rstrip("\n") + + +def test_main_prints_the_table(capsys: pytest.CaptureFixture[str]) -> None: + main() + assert capsys.readouterr().out == EXPECTED_TABLE