Merge pull request 'Add QC-LANG-001 (language and domain); rewrite QC-DICT-001 criterion 7' (#4) from language-domain-checklist into main

Reviewed-on: #4

README.md

@@ -11,6 +11,8 @@ ISO/IEC 25010:2023 quality characteristic.
   Model Canvas, BPMN, Governance, Milestones and gateways
 - Requirements and design: Use Case Diagram, Use Case, User Story, Domain Model,
   SSD, Operation Contract, Sequence Diagram, DCD, ERD, ADR
+- Cross-cutting: Language and Domain (applies to every artifact type written in
+  the Product Owner's language), Domain Dictionary
 - Source code: Python, C, C++, C#
 
 ## Use

qc-dictionary.md

@@ -0,0 +1,53 @@
+# Quality Criteria: Domain Dictionary
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | QC-DICT-001 |
+| CrossReference | [QC-DM-001], [QC-OC-001], [QC-DCD-001], [QC-LANG-001] |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| 2026-10-02 | Accepted | Jens Tirsvad Nielsen | S07 | Initial version | — |
+| 2026-10-03 | Proposed | Jens Tirsvad Nielsen | S07 | Criterion 7 rewritten for the single-file rule (no translated twins); QC-LANG-001 added to CrossReference | — |
+
+---
+
+## Purpose
+
+The Domain Dictionary keeps the Product Owner's terms and the professional IT terms apart on purpose. Its quality determines whether the Domain Model stays in the business language while the Operation Contracts, Sequence Diagrams, Design Class Diagrams and ERDs stay in precise IT terms, without the two drifting.
+
+## 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 | Every row has a PO term, its language, an IT term and a definition | Mandatory | Functional Suitability | An incomplete row cannot be applied consistently |
+| 2 | Each PO term maps to exactly one IT term and the reverse (no synonyms) | Mandatory | Maintainability | Synonyms are how the two vocabularies drift |
+| 3 | Every Domain Model concept has a row, and the Domain Model uses its PO term | Mandatory | Functional Suitability, Usability | Checks the Domain Model against the dictionary |
+| 4 | The Operation Contracts, Sequence Diagrams, Design Class Diagrams and ERD use the IT term, not the PO term | Mandatory | Maintainability | A PO term in design artifacts is a defect |
+| 5 | Definitions are written in the PO language and are one sentence | Optional | Usability | |
+| 6 | "Used as PO term in" and "Used as IT term in" name artifact types that exist in the project | Optional | Maintainability | |
+| 7 | The dictionary's `Language` and `Domain` rows, and the language of every row, match the PO language and domain in the project registry | Mandatory | Usability, Maintainability | Replaces the translated-artifacts check: there is no translated twin, the PO-language file is the artifact. Whether other artifacts use the dictionary's terms is checked by the language and domain checklist ([QC-LANG-001]) |
+
+## Common Defects
+
+- A concept in the Domain Model with no dictionary row
+- The IT term used in the Domain Model, or the PO term in a design class
+- Two PO terms for one IT term
+- A definition copied from the IT term in the wrong language
+- A dictionary whose `Domain` row differs from the PO domain, or that mixes terms of two domains
+
+## Traceability Rule
+
+- Backward: Every row traces to a concept in the Domain Model checklist ([QC-DM-001]) or a term in the Business Case
+- Forward: Feeds the Operation Contract ([QC-OC-001]) and Design Class Diagram ([QC-DCD-001]) checklists, which must use the IT terms, and the language and domain checklist ([QC-LANG-001]), which checks that PO-language artifacts use the PO terms
+
+---
+
+[QC-DM-001]: ./qc-domain-model.md
+[QC-OC-001]: ./qc-operation-contract.md
+[QC-DCD-001]: ./qc-dcd.md
+[QC-LANG-001]: ./qc-language-domain.md

qc-language-domain.md

@@ -0,0 +1,53 @@
+# Quality Criteria: Language and Domain
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | QC-LANG-001 |
+| CrossReference | [QC-DICT-001] |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| 2026-10-03 | Proposed | Jens Tirsvad Nielsen | S07 | Initial version | — |
+
+---
+
+## Purpose
+
+Every artifact of a type written in the Product Owner's (PO's) language exists once, in that language and in the vocabulary of its professional domain (for example medical or construction engineering, even when the language is English). This checklist decides whether such an artifact can be read and reviewed by the people it is for. It is cross-cutting: apply it in addition to the checklist of the artifact's own type, to every artifact type the project registry marks as written in the PO language.
+
+## 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 | The Metadata table has a `Language` row and a `Domain` row, and neither is a placeholder | Mandatory | Usability, Maintainability | A reviewer must see at once how to read the document |
+| 2 | `Language` is a BCP 47 code and `Domain` is a value from the registry's domain list | Mandatory | Maintainability | Free-text values cannot be listed or compared |
+| 3 | The content (prose and table cells) is written in the stated language | Mandatory | Usability | Quoted source text and established technical terms may stay in another language; a document half in one language and half in another fails |
+| 4 | The register matches the one the registry gives for the artifact type | Mandatory | Usability | The register fixes the reader the text assumes and how much it explains |
+| 5 | Domain terms are the PO terms of the domain's dictionary, with no synonyms | Mandatory | Usability, Maintainability | A second word for a dictionary term is a defect |
+| 6 | Metadata keys, section headings, IDs and statuses are in English | Mandatory | Maintainability, Compatibility | The scripts read them; only the content is in the PO language |
+| 7 | No translated twin (`<name>.<language>.md`) exists beside the document | Mandatory | Maintainability | One file per artifact; two files drift apart |
+| 8 | A change of language or domain since the previous accepted version has a Version History row and was reviewed again | Mandatory | Maintainability | Changing the language of an artifact is a material change |
+| 9 | A reviewer competent in the domain, and in the language, has confirmed that the domain terms are used correctly | Mandatory | Functional Suitability | May be a second reviewer named on the review record when the first does not read the language or know the domain |
+| 10 | Abbreviations are spelled out on first use, in the stated language | Optional | Usability | |
+
+## Common Defects
+
+- A `Domain` or `Language` row left as a placeholder, or a free-text domain
+- Sections in two languages, or headings translated so that a script cannot find them
+- A PO term in the domain's dictionary replaced by a near-synonym in one section
+- The English document replaced by a translation without a Version History row or a new review
+- A translated copy kept beside the document "for convenience"
+- Domain terms used loosely because the reviewer does not know the domain
+
+## Traceability Rule
+
+- Backward: Every PO term traces to a row of the Domain Dictionary ([QC-DICT-001]) of the same domain
+- Forward: Applies together with the checklist of the artifact's own type; it feeds no other checklist
+
+---
+
+[QC-DICT-001]: ./qc-dictionary.md

qc-programming-shell.md

@@ -0,0 +1,59 @@
+# Quality Criteria: Shell Script (bash)
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | QC-SH-001 |
+| CrossReference | [QC-DCD-001], [QC-ADR-001] |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| 2026-10-02 | Accepted | Jens Tirsvad Nielsen | S07 | Initial version | — |
+
+---
+
+## Purpose
+
+Shell scripts automate steps that change files, repositories and remote systems, so a defect often does damage quietly. This checklist confirms that a bash script follows the shell conventions (strict mode, quoting, error handling, safe defaults), so that it is predictable, maintainable and safe to run.
+
+## 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 | Starts with `#!/usr/bin/env bash` and `set -euo pipefail` (or a comment explains the exception) | Mandatory | Reliability | |
+| 2 | Every expansion is quoted; lists are arrays; tests use `[[ ]]` and `$(...)` | Mandatory | Reliability, Security | Unquoted expansions break on spaces and globs |
+| 3 | Names follow the conventions: `kebab-case.sh` files, `snake_case` functions and variables, `UPPER_SNAKE` constants and environment variables | Mandatory | Maintainability, Usability | |
+| 4 | Passes `shellcheck` and `bash -n` with no unexplained `disable` comments | Mandatory | Maintainability, Reliability | State the tool versions used |
+| 5 | Errors go to standard error with an `error:` message and a non-zero exit code; bad or missing arguments print a usage line | Mandatory | Reliability, Usability | |
+| 6 | Temporary files use `mktemp` with a `trap ... EXIT` cleanup; no fixed `/tmp` names | Mandatory | Security, Reliability | |
+| 7 | No secret is written in the script, echoed, or put on a command line; secrets come from the environment or a gitignored file | Mandatory | Security | |
+| 8 | A script that changes state outside its own directory defaults to a dry run or needs an explicit flag, and says so in its header | Mandatory | Reliability, Security | |
+| 9 | A header comment states purpose, usage, options, environment variables and exit codes | Mandatory | Usability, Maintainability | |
+| 10 | The script implements a task or design it cites; deviations are recorded | Mandatory | Functional Suitability, Maintainability | |
+| 11 | Behaviour is tested for success, failure and any disabled or bypass path | Mandatory | Reliability | Tests may be a recorded manual run |
+| 12 | Formatted with `shfmt` (or the project's formatter) | Optional | Maintainability | |
+| 13 | Safe to re-run: a second run does not duplicate or corrupt what the first did | Optional | Reliability | |
+| 14 | Bash version and external tools it needs are stated; GNU-only options are named | Optional | Portability | |
+
+## Common Defects
+
+- Unquoted `$var` that breaks on a space or an empty value
+- Missing `set -euo pipefail`, or `|| true` hiding a real failure
+- Parsing `ls` output instead of using globs or `find -print0`
+- A script that deletes or overwrites by default with no dry run
+- A token echoed to the terminal or kept in the script
+- No usage message, so a wrong call fails with a cryptic error
+- A script that implements nothing in any task or design
+
+## Traceability Rule
+
+- Backward: Design Class Diagram checklist ([QC-DCD-001]) where the script implements a design; Architecture Decision Record checklist ([QC-ADR-001]) for the decisions that constrain it
+- Forward: none, source code is the end of the QC checklist chain
+
+---
+
+[QC-DCD-001]: ./qc-dcd.md
+[QC-ADR-001]: ./qc-adr.md