Add Blackjack game: rules, card rendering, game loop and tests

Implement the playable console game for gateway MIL-002. - rules.py: deal_card, calculate_score (blackjack = 0, aces drop 11 -> 1) and compare with an Outcome enum; no console I/O - display.py: hand rendering as plain-text rank plus suit emoji (keycap emoji rendered as boxes in common terminals), score formatting and outcome messages - art.py: course logo shown at the start of every game - game.py: play_game (hit/stand, dealer draws below 17), play (restart loop, console clear, logo) and ask_yes_no with re-prompt; read, write and draw are injected so games can be scripted - __main__.py: python -m blackjack entry point, exits cleanly on Ctrl+C/Ctrl+D - constants.py: card ranks and suits, prompts and messages - tests: 32 new unit and scripted end-to-end tests (35 in total) - README: run instructions for python -m blackjack Closes #7 Closes #8 Closes #9 Closes #10 Closes #11 Closes #12 Closes #13 Closes #14 Task: MIL-002#1 Task: MIL-002#2 Task: MIL-002#3 Task: MIL-002#4 Task: MIL-002#5 Task: MIL-002#6 Task: MIL-002#7 Task: MIL-002#8
Merge pull request 'Add project setup: layout, pyproject, constants, Doxyfile, README' (#16 ) from mil-001-project-setup into main
2026-10-04 22:04:40 +08:00 · 2026-10-04 15:50:19 +02:00 · 2026-10-04 21:48:52 +08:00 · 2026-10-04 15:39:58 +02:00 · 2026-10-04 21:38:09 +08:00
137 changed files with 7350 additions and 1 deletions
@@ -0,0 +1,3 @@
+artifact
+coding-conventions
+project-planning
@@ -0,0 +1,113 @@
+---
+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 <SHORT> [--file <path>] [--title "<text>"] [--cite <ID>=<path>]...
+   ```
+
+   `--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/<SHORT>.md` (cite-for
+   hints and required sections), then fill in the file. Keep the sections in
+   order and replace every `<placeholder>`.
+
+## 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 <SHORT>`. 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 | Jane Doe | S02 | Added Risks section<br>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 `<br>`.
+- **Commit** — the commit that made the change, as a reference-style link
+  defined at the bottom of the file
+  (`[a1b2c3d]: https://<host>/<owner>/<repo>/commit/<full-hash>`; 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 <file>...`, 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 <url> <file>` (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:** `<SHORT>-<version>`, 3 digits (`BC-001`); `ADR` uses 4 digits;
+  `RC` is sequential across all types; QC is `QC-<SHORT>-<version>`.
+- **Language:** artifacts carry no `DomainLanguages` row. 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).
+- **Translations:** when the PO language is not English, each type the
+  registry marks "Also kept as a PO-language file" is also saved as
+  `<artifact>.<language>.md` beside its English source (`business-case.da.md`).
+  A translation keeps the source's ID and sections, uses the PO terms from the
+  dictionary (`DICT`), and has a Version History row naming the source version
+  it follows. The English file is authoritative; update the translation in the
+  same change. If the PO language is English, no translations are made.
+- **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`).
@@ -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 <ID>=<path>`); 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.
@@ -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.
@@ -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.
@@ -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.
@@ -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.
@@ -0,0 +1,25 @@
+# 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 (from the registry's `Languages`
+   section) 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.
+
+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.
@@ -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.
@@ -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.
@@ -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<NN>`), 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.
@@ -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.
@@ -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-<v>.<NN>`) 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.
@@ -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.
@@ -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.
@@ -0,0 +1,44 @@
+# Quality Criteria checklist (QC)
+
+A QC checklist is the reusable review checklist for one artifact **type**.
+It lives in the framework (`framework/qc/qc-<type>.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-<short-name>-<version>` (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-<type>.md
+  --cite QC-<adjacent>=framework/qc/qc-<adjacent>.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)
+```
+
+## 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.
@@ -0,0 +1,34 @@
+# 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-<NNN>-<instance-slug>.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-<slug>.md
+  --cite <INSTANCE-ID>=<instance path> --cite QC-<SHORT>-001=framework/qc/<checklist>.md`
+
+## Required sections (after Metadata / Version History)
+
+- **Artifact Under Review** — links to the instance and to the QC checklist
+  used.
+- **Checklist Results** — `# | Criterion | Status (Pass/Fail/N-A) |
+  Evidence/Notes`, one row per criterion copied from the QC checklist, in
+  the same order.
+- **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).
+- 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`.
@@ -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<NN>`.
@@ -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.
@@ -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).
@@ -0,0 +1,15 @@
+# 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 | Upstream (Backward Link) | Downstream (Forward
+  Link) | Last Reviewed (RC-ID)`. 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.
@@ -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.
@@ -0,0 +1,21 @@
+# 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), Feedback, Follow-ups (action, owner as a stakeholder ID, due).
+Fill the record after the session; never before.
@@ -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 `<<include>>` /
+  `<<extend>>` use cases), Special Requirements / Business Rules (per step),
+  Open Issues.
+
+Title and actor names must match `UCD` and `US` exactly.
@@ -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 (`<<Actor>>`,
+   `<<System>>`), a labelled system boundary, `<<include>>` / `<<extend>>`
+   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 `<<include>>` / `<<extend>>` with a one-line
+   justification.
@@ -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-<doc-version>.<NN>` (e.g.
+   `US-001.01`, so it cannot be confused with the document ID `US-001`):
+   - Statement: **As a** `<actor>`, **I want** `<goal>`, **so that**
+     `<benefit>` — 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).
@@ -0,0 +1,42 @@
+# @TITLE@
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | @ID@ |
+| CrossReference | @CROSSREF@ |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| @DATE@ | Accepted | @AUTHOR@ | <reviewer S-ID> | Initial version | pending |
+
+Allowed Status values: `Proposed`, `Accepted`, `Rejected`, `Deprecated`, `Superseded by ADR-NNNN`.
+
+---
+
+## Context
+
+<The forces/problem driving this decision, and the options considered.>
+
+## Decision
+
+<The decision that was made, stated plainly.>
+
+## Consequences
+
+**Positive:**
+
+- <positive consequence>
+
+**Negative:**
+
+- <negative consequence>
+
+## Affected Artifacts
+
+- [<ARTIFACT-ID>] — <how this decision affects it>, or a single "-" if none
+
+---
+
+@LINKS@
@@ -0,0 +1,70 @@
+# @TITLE@
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | @ID@ |
+| CrossReference | @CROSSREF@ |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| @DATE@ | Accepted | @AUTHOR@ | <reviewer S-ID> | 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
+
+<Proceed | Do not proceed> — <one-sentence rationale>
+
+---
+
+@LINKS@
@@ -0,0 +1,113 @@
+# @TITLE@
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | @ID@ |
+| CrossReference | @CROSSREF@ |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| @DATE@ | Accepted | @AUTHOR@ | <reviewer S-ID> | Initial version | pending |
+
+---
+
+## Purpose / Scope
+
+Operationalizes: <Business Case objectives> ([BC-<n>])
+
+## Canvas
+
+<!-- Business Model Canvas Template -->
+<table border="1" width="100%" height="600px" style="border-collapse: collapse; vertical-align: top;">
+  <!-- Upper Section -->
+  <tr>
+    <th colspan="2" width="20%">Key Partners</th>
+    <th colspan="2" width="20%">Key Activities</th>
+    <th colspan="2" width="20%">Value Propositions</th>
+    <th colspan="2" width="20%">Customer Relationships</th>
+    <th colspan="2" width="20%">Customer Segments</th>
+  </tr>
+  <tr>
+    <td rowspan="3" colspan="2">
+      <!--- Key Partners List -->
+      <ul>
+        <li></li>
+      </ul>
+    </td>
+    <td colspan="2">
+      <!--- Key Activities List -->
+      <ul>
+        <li></li>
+      </ul>
+    </td>
+    <td rowspan="3" colspan="2">
+      <!--- Value Propositions List -->
+      <ul>
+        <li></li>
+      </ul>
+    </td>
+    <td colspan="2">
+      <!--- Customer Relationships List -->
+      <ul>
+        <li></li>
+      </ul>
+    </td>
+    <td rowspan="3" colspan="2">
+      <!--- Customer Segments List -->
+      <ul>
+        <li></li>
+      </ul>
+    </td>
+  </tr>
+  <tr>
+    <th colspan="2">Key Resources</th>
+    <th colspan="2">Channels</th>
+  </tr>
+  <tr>
+    <td colspan="2">
+      <!--- Key Resources List -->
+      <ul>
+        <li></li>
+      </ul>
+    </td>
+    <td colspan="2">
+      <!--- Channels List -->
+      <ul>
+        <li></li>
+      </ul>
+    </td>
+  </tr>
+  <!-- Lower Section -->
+  <tr>
+    <th colspan="5">Cost Structure</th>
+    <th colspan="5">Revenue Streams</th>
+  </tr>
+  <tr>
+    <td colspan="5">
+      <!--- Cost Structure List -->
+      <ul>
+        <li></li>
+      </ul>
+    </td>
+    <td colspan="5">
+      <!--- Revenue Streams List -->
+      <ul>
+        <li></li>
+      </ul>
+    </td>
+  </tr>
+</table>
+
+
+## Assumptions
+
+| # | Assumption | How it can be tested |
+| --- | --- | --- |
+
+## Consistency Check
+
+---
+
+@LINKS@
@@ -0,0 +1,41 @@
+# @TITLE@
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | @ID@ |
+| CrossReference | @CROSSREF@ |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| @DATE@ | Accepted | @AUTHOR@ | <reviewer S-ID> | Initial version | pending |
+
+---
+
+## Purpose and Business Goal
+
+Realizes: <Business Case objective> ([BC-<n>])
+
+## Participants
+
+| Pool / Lane | Participant | Stakeholder ID (SA) |
+| --- | --- | --- |
+
+## Process Diagram
+
+<image, or link to the BPMN 2.0 diagram file + its source>
+
+## Element Table
+
+| Element | Type (event / activity / gateway) | Lane | Description |
+| --- | --- | --- | --- |
+
+## Path Coverage
+
+| Path | Start event | End event |
+| --- | --- | --- |
+
+---
+
+@LINKS@
@@ -0,0 +1,50 @@
+# @TITLE@
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | @ID@ |
+| CrossReference | @CROSSREF@ |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| @DATE@ | Accepted | @AUTHOR@ | <reviewer S-ID> | 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@
@@ -0,0 +1,35 @@
+# @TITLE@
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | @ID@ |
+| CrossReference | @CROSSREF@ |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| @DATE@ | Accepted | @AUTHOR@ | <reviewer S-ID> | Initial version | pending |
+
+---
+
+## Purpose and Scope
+
+Maps each Product Owner (PO) term to its professional IT term. PO language:
+<language, from the registry's `Languages` section>.
+
+## Dictionary
+
+| PO term | Language | IT term | Definition | Used as PO term in | Used as IT term in |
+| --- | --- | --- | --- | --- | --- |
+| <term> | <da> | <Term> | <one sentence, in the PO language> | 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@
@@ -0,0 +1,54 @@
+# @TITLE@
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | @ID@ |
+| CrossReference | @CROSSREF@ |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| @DATE@ | Accepted | @AUTHOR@ | <reviewer S-ID> | Initial version | pending |
+
+---
+
+## Purpose and Scope
+
+Covers: <use cases>
+
+## 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@
@@ -0,0 +1,53 @@
+# @TITLE@
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | @ID@ |
+| CrossReference | @CROSSREF@ |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| @DATE@ | Accepted | @AUTHOR@ | <reviewer S-ID> | Initial version | pending |
+
+---
+
+## Purpose and Scope
+
+## Diagram
+
+```plantuml
+@startuml
+hide circle
+entity CUSTOMER {
+  * id : int <<PK>>
+  --
+  name : string
+}
+entity ORDER {
+  * id : int <<PK>>
+  --
+  * customer_id : int <<FK>>
+}
+CUSTOMER ||--o{ ORDER : places
+@enduml
+```
+
+## Entity Table
+
+### <ENTITY>
+
+| Attribute | Type | PK/FK | Nullable | Source (DCD class.attribute) |
+| --- | --- | --- | --- | --- |
+
+## Relationship Table
+
+| Entity | Cardinality | Entity | FK | Rule |
+| --- | --- | --- | --- | --- |
+
+## Normalization Notes
+
+---
+
+@LINKS@
@@ -0,0 +1,68 @@
+# @TITLE@
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | @ID@ |
+| CrossReference | @CROSSREF@ |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| @DATE@ | Accepted | @AUTHOR@ | <reviewer S-ID> | 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<NN>`),
+never role names.
+
+| Artifact Category | Responsible (runs the review) | Accountable (Go/No-Go owner) | Consulted | Informed |
+| --- | --- | --- | --- | --- |
+| Strategic (Stakeholder Analysis, Business Case, BMC) | S<NN> | S<NN> | S<NN> | S<NN> |
+| Process/Business (BPMN, KPI, Milestones/Gateways) | S<NN> | S<NN> | S<NN> | S<NN> |
+| Requirements (Use Case Diagram, User Story, Use Case) | S<NN> | S<NN> | S<NN> | S<NN> |
+| Modeling/Design (Domain Model, SSD, Operation Contract, Sequence Diagram, DCD, ERD) | S<NN> | S<NN> | S<NN> | S<NN> |
+
+Cross-cutting escalations and disputed verdicts are Accountable to the ARB
+Chair (`S<NN>`), 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@
@@ -0,0 +1,35 @@
+# @TITLE@
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | @ID@ |
+| CrossReference | @CROSSREF@ |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| @DATE@ | Accepted | @AUTHOR@ | <reviewer S-ID> | Initial version | pending |
+
+---
+
+## Purpose
+
+<which Business Case success criteria this operationalizes>
+
+## 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@
@@ -0,0 +1,58 @@
+# @TITLE@
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | @ID@ |
+| CrossReference | @CROSSREF@ |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| @DATE@ | Accepted | @AUTHOR@ | <reviewer S-ID> | Initial version | pending |
+
+---
+
+## Purpose
+
+<decision this gate supports>
+
+## Deliverable
+
+<concrete output evaluated at this gate>
+
+## 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 — <consistency with Business Case constraints>
+
+## Tasks
+
+| # | Task | Summary | Needs its own Use Case/User Story? | Reference |
+| --- | --- | --- | --- | --- |
+| 1 | <task> | <what it involves and why - becomes the Issue body> | No | |
+
+---
+
+@LINKS@
@@ -0,0 +1,41 @@
+# @TITLE@
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | @ID@ |
+| CrossReference | @CROSSREF@ |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| @DATE@ | Accepted | @AUTHOR@ | <reviewer S-ID> | Initial version | pending |
+
+---
+
+## Contract: <operationName>
+
+| Item | Value |
+| --- | --- |
+| Operation | `operationName(param: Type): ReturnType` |
+| Traces to | <SSD message> in [SSD-<n>] |
+| Domain Model concepts | <Concept, Association> ([DM-<n>]) |
+
+**Preconditions**
+
+- <required state in Domain Model terms>
+
+**Postconditions**
+
+- A <Concept> instance was created.
+- <Concept> was associated with <Concept>.
+- <Concept>.<attribute> was set to <value>.
+
+**Exceptions**
+
+| Condition (failing precondition) | Outcome |
+| --- | --- |
+
+---
+
+@LINKS@
@@ -0,0 +1,61 @@
+# @TITLE@
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | @ID@ |
+| CrossReference | @CROSSREF@ |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| @DATE@ | Accepted | @AUTHOR@ | <reviewer S-ID> | Initial version | pending |
+
+---
+
+## Purpose
+
+<what this plan schedules, and over what constraint>
+
+## Planning Assumptions
+
+- Week 1 starts <date>; the plan ends by <date>, per the Business Case constraint.
+- Phase length: <e.g. two weeks>.
+
+## Gateway Schedule
+
+| Gateway | Document | Window | Decision date | Owner | Stories | Main deliverable | Milestone |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| <name> | [MIL-<n>] | <dates> | <date> | <S-ID> | <US-…> | <deliverable> | <link once synced> |
+
+```plantuml
+@startgantt
+Project starts <start YYYY-MM-DD>
+[Phase 1] starts <start YYYY-MM-DD> and ends <end YYYY-MM-DD>
+[Phase 1 Go/No-Go] happens <date YYYY-MM-DD>
+@endgantt
+```
+
+## Scope Coverage
+
+| Business Case scope item | Gateway |
+| --- | --- |
+
+## Dependencies
+
+```
+<phase 1> → <phase 2> → ...
+```
+
+## Plan Risks
+
+| Risk | Impact | Mitigation |
+| --- | --- | --- |
+
+## Open Issues
+
+- <unresolved item>
+
+---
+
+@LINKS@
@@ -0,0 +1,42 @@
+# @TITLE@
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | @ID@ |
+| CrossReference | @CROSSREF@ |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| @DATE@ | Accepted | @AUTHOR@ | <reviewer S-ID> | Initial version | pending |
+
+Allowed Status values: `Proposed`, `Accepted`, `Rejected`, `Deprecated`. The latest reviewed row is `Accepted`; the row before it is `Deprecated`.
+
+---
+
+## Purpose
+
+<Why this artifact type matters and what decision it supports.>
+
+## 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 | <criterion> | Mandatory | <characteristic(s)> | |
+
+## Common Defects
+
+- <anti-pattern 1>
+- <anti-pattern 2>
+
+## Traceability Rule
+
+- Backward: <what this artifact must link to as input> ([QC-<BACKWARD-SHORT-NAME>-<NNN>])
+- Forward: <what this artifact must feed into as output> ([QC-<FORWARD-SHORT-NAME>-<NNN>])
+
+---
+
+@LINKS@
@@ -0,0 +1,39 @@
+# @TITLE@
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | @ID@ |
+| CrossReference | @CROSSREF@ |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| @DATE@ | Accepted | @AUTHOR@ | <reviewer S-ID> | Initial version | pending |
+
+---
+
+## Artifact Under Review
+
+- Instance reviewed: [<INSTANCE-ID>]
+- Checklist used: [<QC-ID>] (`QC-<short-name>-<version>`, e.g. `QC-BC-001`)
+
+## Checklist Results
+
+| # | Criterion | Status | Evidence/Notes |
+| --- | --- | --- | --- |
+| 1 | <criterion copied from the QC checklist> | Pass/Fail/N-A | |
+
+## Overall Verdict
+
+<Go / Go-with-conditions / No-Go> — <rationale>
+
+## Action Items
+
+| Action | Owner | Due |
+| --- | --- | --- |
+| <action> | <stakeholder ID, e.g. S07> | <date> |
+
+---
+
+@LINKS@
@@ -0,0 +1,54 @@
+# @TITLE@
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | @ID@ |
+| CrossReference | @CROSSREF@ |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| @DATE@ | Accepted | @AUTHOR@ | <reviewer S-ID> | Initial version | pending |
+
+---
+
+## Purpose
+
+<why this analysis exists; methodology followed>
+
+## 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@
@@ -0,0 +1,47 @@
+# @TITLE@
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | @ID@ |
+| CrossReference | @CROSSREF@ |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| @DATE@ | Accepted | @AUTHOR@ | <reviewer S-ID> | Initial version | pending |
+
+---
+
+## Sequence: <operationName>
+
+**Realizes:** `operationName` in [OC-<n>]
+
+### 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@
@@ -0,0 +1,40 @@
+# @TITLE@
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | @ID@ |
+| CrossReference | @CROSSREF@ |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| @DATE@ | Accepted | @AUTHOR@ | <reviewer S-ID> | Initial version | pending |
+
+---
+
+## Source Use Case
+
+<Use case name> ([UC-<n>]) — scenario: <main success scenario | named alternate>
+
+## 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@
@@ -0,0 +1,30 @@
+# @TITLE@
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | @ID@ |
+| CrossReference | @CROSSREF@ |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| @DATE@ | Accepted | @AUTHOR@ | <reviewer S-ID> | 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 | Upstream (Backward Link) | Downstream (Forward Link) | Last Reviewed (RC-ID) |
+| --- | --- | --- | --- | --- |
+| [<ID>] | <type> | [<upstream-ID>] | [<downstream-ID>] | [<RC-ID>] |
+
+---
+
+@LINKS@
@@ -0,0 +1,60 @@
+# @TITLE@
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | @ID@ |
+| CrossReference | @CROSSREF@ |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| @DATE@ | Accepted | @AUTHOR@ | <reviewer S-ID> | Initial version | pending |
+
+---
+
+## Purpose
+
+<What the training achieves and the risk it mitigates.>
+
+## Audience and Prerequisites
+
+<Who attends, what they must have read or installed.>
+
+## Learning Objectives
+
+By the end, a participant can:
+
+- <objective>
+
+## Agenda
+
+| Module | Topic | Minutes |
+| --- | --- | --- |
+| 1 | <topic> | <n> |
+
+## Module Notes
+
+### Module 1: <topic>
+
+<Key points and what the facilitator shows.>
+
+## Exercises
+
+### Exercise 1: <name>
+
+<Task, input and expected result.>
+
+## Assessment
+
+<How the facilitator checks each participant, and the pass criteria.>
+
+## 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@
@@ -0,0 +1,43 @@
+# @TITLE@
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | @ID@ |
+| CrossReference | @CROSSREF@ |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| @DATE@ | Accepted | @AUTHOR@ | <reviewer S-ID> | Initial version | pending |
+
+---
+
+## Session
+
+| Item | Value |
+| --- | --- |
+| Training material | [<TRN-ID>] |
+| Date | <date of the session> |
+| Facilitator | <stakeholder ID> |
+| Format and place | <in person / online, where> |
+
+## Attendees and Assessment
+
+| Stakeholder ID (SA) | Attended | Assessment (Pass / Not yet) | Notes |
+| --- | --- | --- | --- |
+| <S-ID> | <Yes / No> | <Pass / Not yet> | |
+
+## Feedback
+
+<What attendees said worked and did not.>
+
+## Follow-ups
+
+| Action | Owner | Due |
+| --- | --- | --- |
+| <action, for example a repeat session or a checklist change> | <stakeholder ID> | <date> |
+
+---
+
+@LINKS@
@@ -0,0 +1,55 @@
+# @TITLE@
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | @ID@ |
+| CrossReference | @CROSSREF@ |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| @DATE@ | Accepted | @AUTHOR@ | <reviewer S-ID> | Initial version | pending |
+
+---
+
+**Format:** Brief | Casual | Fully Dressed  (delete the unused sections below)
+
+## Brief
+
+<one paragraph: main success scenario only>
+
+## Casual
+
+<informal multi-paragraph narrative; may mention some alternate flows>
+
+## Fully Dressed
+
+- **Scope:** <system>
+- **Level:** summary | user-goal | subfunction
+- **Primary Actor:** <actor, as named in [UCD-<n>]>
+- **Stakeholders and Interests:**
+  - <S-ID> — <interest>
+- **Preconditions:**
+- **Postconditions (success guarantee):**
+
+### Main Success Scenario
+
+1. <actor action>
+2. <system response>
+
+### Extensions (Alternative / Exception Flows)
+
+- 2a. <condition>:
+  1. <handling> (`<<include>>` / `<<extend>>` <other use case>)
+
+### Special Requirements / Business Rules
+
+| Step | Rule |
+| --- | --- |
+
+### Open Issues
+
+---
+
+@LINKS@
@@ -0,0 +1,50 @@
+# @TITLE@
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | @ID@ |
+| CrossReference | @CROSSREF@ |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| @DATE@ | Accepted | @AUTHOR@ | <reviewer S-ID> | Initial version | pending |
+
+---
+
+## Purpose and Scope
+
+<system boundary in words>
+
+## 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 (`<<include>>` / `<<extend>>`) | To | Justification |
+| --- | --- | --- | --- |
+
+---
+
+@LINKS@
@@ -0,0 +1,36 @@
+# @TITLE@
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | @ID@ |
+| CrossReference | @CROSSREF@ |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| @DATE@ | Accepted | @AUTHOR@ | <reviewer S-ID> | Initial version | pending |
+
+---
+
+## Purpose and Scope
+
+## Story List
+
+### @ID@.01 — <short title>
+
+**As a** <actor from [UCD-<n>]>, **I want** <goal>, **so that** <benefit>.
+
+**Acceptance Criteria**
+
+- Given <context>, when <action>, then <observable outcome>.
+
+| Traces to | Size | INVEST exceptions |
+| --- | --- | --- |
+| [UC-<n>] or [MIL-<n>] | fits one iteration | none |
+
+## INVEST Check
+
+---
+
+@LINKS@
@@ -0,0 +1,94 @@
+---
+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`).
+Reviewing code needs no task.
+
+## 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/<language>.md` with these sections: Standard base, Naming,
+   Formatting, Language rules, Errors, Tests, Tooling.
+2. Add `framework/qc/qc-<language>.md` (`QC-<SHORT>-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`.
@@ -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 (`<stdint.h>`) 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`.
@@ -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`.
@@ -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 (`<Nullable>enable</Nullable>`) 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`.
@@ -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_<module>.py` / `test_<behavior>_<condition>` | `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`.
@@ -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.
@@ -0,0 +1,278 @@
+---
+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. If it differs from the project's working language, the high-level
+artifacts are also kept in it (see the registry's translation list).
+
+## 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).
+
+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: <reason>").
+
+## 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-<NNN>-<slug>.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://<host>/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://<host>/<owner>/<repo>/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 <branch-name>
+# ... commits ...
+git push -u origin <branch-name>
+```
+
+- 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/<owner>/<repo>/issues/<N>` with
+  `GITEA_TOKEN`) rather than assuming the whole list closed; close any that
+  didn't with a direct `PATCH .../issues/<N>` `{"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: <reason>") 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 <changed docs>`, 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.
@@ -0,0 +1,3 @@
+artifact
+coding-conventions
+project-planning
@@ -0,0 +1,113 @@
+---
+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 <SHORT> [--file <path>] [--title "<text>"] [--cite <ID>=<path>]...
+   ```
+
+   `--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/<SHORT>.md` (cite-for
+   hints and required sections), then fill in the file. Keep the sections in
+   order and replace every `<placeholder>`.
+
+## 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 <SHORT>`. 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 | Jane Doe | S02 | Added Risks section<br>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 `<br>`.
+- **Commit** — the commit that made the change, as a reference-style link
+  defined at the bottom of the file
+  (`[a1b2c3d]: https://<host>/<owner>/<repo>/commit/<full-hash>`; 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 <file>...`, 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 <url> <file>` (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:** `<SHORT>-<version>`, 3 digits (`BC-001`); `ADR` uses 4 digits;
+  `RC` is sequential across all types; QC is `QC-<SHORT>-<version>`.
+- **Language:** artifacts carry no `DomainLanguages` row. 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).
+- **Translations:** when the PO language is not English, each type the
+  registry marks "Also kept as a PO-language file" is also saved as
+  `<artifact>.<language>.md` beside its English source (`business-case.da.md`).
+  A translation keeps the source's ID and sections, uses the PO terms from the
+  dictionary (`DICT`), and has a Version History row naming the source version
+  it follows. The English file is authoritative; update the translation in the
+  same change. If the PO language is English, no translations are made.
+- **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`).
@@ -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 <ID>=<path>`); 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.
@@ -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.
@@ -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.
@@ -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.
@@ -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.
@@ -0,0 +1,25 @@
+# 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 (from the registry's `Languages`
+   section) 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.
+
+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.
@@ -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.
@@ -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.
@@ -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<NN>`), 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.
@@ -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.
@@ -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-<v>.<NN>`) 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.
@@ -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.
@@ -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.
@@ -0,0 +1,44 @@
+# Quality Criteria checklist (QC)
+
+A QC checklist is the reusable review checklist for one artifact **type**.
+It lives in the framework (`framework/qc/qc-<type>.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-<short-name>-<version>` (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-<type>.md
+  --cite QC-<adjacent>=framework/qc/qc-<adjacent>.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)
+```
+
+## 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.
@@ -0,0 +1,34 @@
+# 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-<NNN>-<instance-slug>.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-<slug>.md
+  --cite <INSTANCE-ID>=<instance path> --cite QC-<SHORT>-001=framework/qc/<checklist>.md`
+
+## Required sections (after Metadata / Version History)
+
+- **Artifact Under Review** — links to the instance and to the QC checklist
+  used.
+- **Checklist Results** — `# | Criterion | Status (Pass/Fail/N-A) |
+  Evidence/Notes`, one row per criterion copied from the QC checklist, in
+  the same order.
+- **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).
+- 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`.
@@ -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<NN>`.
@@ -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.
@@ -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).
@@ -0,0 +1,15 @@
+# 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 | Upstream (Backward Link) | Downstream (Forward
+  Link) | Last Reviewed (RC-ID)`. 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.
@@ -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.
@@ -0,0 +1,21 @@
+# 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), Feedback, Follow-ups (action, owner as a stakeholder ID, due).
+Fill the record after the session; never before.
@@ -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 `<<include>>` /
+  `<<extend>>` use cases), Special Requirements / Business Rules (per step),
+  Open Issues.
+
+Title and actor names must match `UCD` and `US` exactly.
@@ -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 (`<<Actor>>`,
+   `<<System>>`), a labelled system boundary, `<<include>>` / `<<extend>>`
+   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 `<<include>>` / `<<extend>>` with a one-line
+   justification.
@@ -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-<doc-version>.<NN>` (e.g.
+   `US-001.01`, so it cannot be confused with the document ID `US-001`):
+   - Statement: **As a** `<actor>`, **I want** `<goal>`, **so that**
+     `<benefit>` — 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).
@@ -0,0 +1,42 @@
+# @TITLE@
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | @ID@ |
+| CrossReference | @CROSSREF@ |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| @DATE@ | Accepted | @AUTHOR@ | <reviewer S-ID> | Initial version | pending |
+
+Allowed Status values: `Proposed`, `Accepted`, `Rejected`, `Deprecated`, `Superseded by ADR-NNNN`.
+
+---
+
+## Context
+
+<The forces/problem driving this decision, and the options considered.>
+
+## Decision
+
+<The decision that was made, stated plainly.>
+
+## Consequences
+
+**Positive:**
+
+- <positive consequence>
+
+**Negative:**
+
+- <negative consequence>
+
+## Affected Artifacts
+
+- [<ARTIFACT-ID>] — <how this decision affects it>, or a single "-" if none
+
+---
+
+@LINKS@
@@ -0,0 +1,70 @@
+# @TITLE@
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | @ID@ |
+| CrossReference | @CROSSREF@ |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| @DATE@ | Accepted | @AUTHOR@ | <reviewer S-ID> | 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
+
+<Proceed | Do not proceed> — <one-sentence rationale>
+
+---
+
+@LINKS@
@@ -0,0 +1,113 @@
+# @TITLE@
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | @ID@ |
+| CrossReference | @CROSSREF@ |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| @DATE@ | Accepted | @AUTHOR@ | <reviewer S-ID> | Initial version | pending |
+
+---
+
+## Purpose / Scope
+
+Operationalizes: <Business Case objectives> ([BC-<n>])
+
+## Canvas
+
+<!-- Business Model Canvas Template -->
+<table border="1" width="100%" height="600px" style="border-collapse: collapse; vertical-align: top;">
+  <!-- Upper Section -->
+  <tr>
+    <th colspan="2" width="20%">Key Partners</th>
+    <th colspan="2" width="20%">Key Activities</th>
+    <th colspan="2" width="20%">Value Propositions</th>
+    <th colspan="2" width="20%">Customer Relationships</th>
+    <th colspan="2" width="20%">Customer Segments</th>
+  </tr>
+  <tr>
+    <td rowspan="3" colspan="2">
+      <!--- Key Partners List -->
+      <ul>
+        <li></li>
+      </ul>
+    </td>
+    <td colspan="2">
+      <!--- Key Activities List -->
+      <ul>
+        <li></li>
+      </ul>
+    </td>
+    <td rowspan="3" colspan="2">
+      <!--- Value Propositions List -->
+      <ul>
+        <li></li>
+      </ul>
+    </td>
+    <td colspan="2">
+      <!--- Customer Relationships List -->
+      <ul>
+        <li></li>
+      </ul>
+    </td>
+    <td rowspan="3" colspan="2">
+      <!--- Customer Segments List -->
+      <ul>
+        <li></li>
+      </ul>
+    </td>
+  </tr>
+  <tr>
+    <th colspan="2">Key Resources</th>
+    <th colspan="2">Channels</th>
+  </tr>
+  <tr>
+    <td colspan="2">
+      <!--- Key Resources List -->
+      <ul>
+        <li></li>
+      </ul>
+    </td>
+    <td colspan="2">
+      <!--- Channels List -->
+      <ul>
+        <li></li>
+      </ul>
+    </td>
+  </tr>
+  <!-- Lower Section -->
+  <tr>
+    <th colspan="5">Cost Structure</th>
+    <th colspan="5">Revenue Streams</th>
+  </tr>
+  <tr>
+    <td colspan="5">
+      <!--- Cost Structure List -->
+      <ul>
+        <li></li>
+      </ul>
+    </td>
+    <td colspan="5">
+      <!--- Revenue Streams List -->
+      <ul>
+        <li></li>
+      </ul>
+    </td>
+  </tr>
+</table>
+
+
+## Assumptions
+
+| # | Assumption | How it can be tested |
+| --- | --- | --- |
+
+## Consistency Check
+
+---
+
+@LINKS@
@@ -0,0 +1,41 @@
+# @TITLE@
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | @ID@ |
+| CrossReference | @CROSSREF@ |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| @DATE@ | Accepted | @AUTHOR@ | <reviewer S-ID> | Initial version | pending |
+
+---
+
+## Purpose and Business Goal
+
+Realizes: <Business Case objective> ([BC-<n>])
+
+## Participants
+
+| Pool / Lane | Participant | Stakeholder ID (SA) |
+| --- | --- | --- |
+
+## Process Diagram
+
+<image, or link to the BPMN 2.0 diagram file + its source>
+
+## Element Table
+
+| Element | Type (event / activity / gateway) | Lane | Description |
+| --- | --- | --- | --- |
+
+## Path Coverage
+
+| Path | Start event | End event |
+| --- | --- | --- |
+
+---
+
+@LINKS@
@@ -0,0 +1,50 @@
+# @TITLE@
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | @ID@ |
+| CrossReference | @CROSSREF@ |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| @DATE@ | Accepted | @AUTHOR@ | <reviewer S-ID> | 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@
@@ -0,0 +1,35 @@
+# @TITLE@
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | @ID@ |
+| CrossReference | @CROSSREF@ |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| @DATE@ | Accepted | @AUTHOR@ | <reviewer S-ID> | Initial version | pending |
+
+---
+
+## Purpose and Scope
+
+Maps each Product Owner (PO) term to its professional IT term. PO language:
+<language, from the registry's `Languages` section>.
+
+## Dictionary
+
+| PO term | Language | IT term | Definition | Used as PO term in | Used as IT term in |
+| --- | --- | --- | --- | --- | --- |
+| <term> | <da> | <Term> | <one sentence, in the PO language> | 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@
@@ -0,0 +1,54 @@
+# @TITLE@
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | @ID@ |
+| CrossReference | @CROSSREF@ |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| @DATE@ | Accepted | @AUTHOR@ | <reviewer S-ID> | Initial version | pending |
+
+---
+
+## Purpose and Scope
+
+Covers: <use cases>
+
+## 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@
@@ -0,0 +1,53 @@
+# @TITLE@
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | @ID@ |
+| CrossReference | @CROSSREF@ |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| @DATE@ | Accepted | @AUTHOR@ | <reviewer S-ID> | Initial version | pending |
+
+---
+
+## Purpose and Scope
+
+## Diagram
+
+```plantuml
+@startuml
+hide circle
+entity CUSTOMER {
+  * id : int <<PK>>
+  --
+  name : string
+}
+entity ORDER {
+  * id : int <<PK>>
+  --
+  * customer_id : int <<FK>>
+}
+CUSTOMER ||--o{ ORDER : places
+@enduml
+```
+
+## Entity Table
+
+### <ENTITY>
+
+| Attribute | Type | PK/FK | Nullable | Source (DCD class.attribute) |
+| --- | --- | --- | --- | --- |
+
+## Relationship Table
+
+| Entity | Cardinality | Entity | FK | Rule |
+| --- | --- | --- | --- | --- |
+
+## Normalization Notes
+
+---
+
+@LINKS@
@@ -0,0 +1,68 @@
+# @TITLE@
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | @ID@ |
+| CrossReference | @CROSSREF@ |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| @DATE@ | Accepted | @AUTHOR@ | <reviewer S-ID> | 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<NN>`),
+never role names.
+
+| Artifact Category | Responsible (runs the review) | Accountable (Go/No-Go owner) | Consulted | Informed |
+| --- | --- | --- | --- | --- |
+| Strategic (Stakeholder Analysis, Business Case, BMC) | S<NN> | S<NN> | S<NN> | S<NN> |
+| Process/Business (BPMN, KPI, Milestones/Gateways) | S<NN> | S<NN> | S<NN> | S<NN> |
+| Requirements (Use Case Diagram, User Story, Use Case) | S<NN> | S<NN> | S<NN> | S<NN> |
+| Modeling/Design (Domain Model, SSD, Operation Contract, Sequence Diagram, DCD, ERD) | S<NN> | S<NN> | S<NN> | S<NN> |
+
+Cross-cutting escalations and disputed verdicts are Accountable to the ARB
+Chair (`S<NN>`), 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@
@@ -0,0 +1,35 @@
+# @TITLE@
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | @ID@ |
+| CrossReference | @CROSSREF@ |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| @DATE@ | Accepted | @AUTHOR@ | <reviewer S-ID> | Initial version | pending |
+
+---
+
+## Purpose
+
+<which Business Case success criteria this operationalizes>
+
+## 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@
@@ -0,0 +1,58 @@
+# @TITLE@
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | @ID@ |
+| CrossReference | @CROSSREF@ |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| @DATE@ | Accepted | @AUTHOR@ | <reviewer S-ID> | Initial version | pending |
+
+---
+
+## Purpose
+
+<decision this gate supports>
+
+## Deliverable
+
+<concrete output evaluated at this gate>
+
+## 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 — <consistency with Business Case constraints>
+
+## Tasks
+
+| # | Task | Summary | Needs its own Use Case/User Story? | Reference |
+| --- | --- | --- | --- | --- |
+| 1 | <task> | <what it involves and why - becomes the Issue body> | No | |
+
+---
+
+@LINKS@
@@ -0,0 +1,41 @@
+# @TITLE@
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | @ID@ |
+| CrossReference | @CROSSREF@ |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| @DATE@ | Accepted | @AUTHOR@ | <reviewer S-ID> | Initial version | pending |
+
+---
+
+## Contract: <operationName>
+
+| Item | Value |
+| --- | --- |
+| Operation | `operationName(param: Type): ReturnType` |
+| Traces to | <SSD message> in [SSD-<n>] |
+| Domain Model concepts | <Concept, Association> ([DM-<n>]) |
+
+**Preconditions**
+
+- <required state in Domain Model terms>
+
+**Postconditions**
+
+- A <Concept> instance was created.
+- <Concept> was associated with <Concept>.
+- <Concept>.<attribute> was set to <value>.
+
+**Exceptions**
+
+| Condition (failing precondition) | Outcome |
+| --- | --- |
+
+---
+
+@LINKS@
@@ -0,0 +1,61 @@
+# @TITLE@
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | @ID@ |
+| CrossReference | @CROSSREF@ |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| @DATE@ | Accepted | @AUTHOR@ | <reviewer S-ID> | Initial version | pending |
+
+---
+
+## Purpose
+
+<what this plan schedules, and over what constraint>
+
+## Planning Assumptions
+
+- Week 1 starts <date>; the plan ends by <date>, per the Business Case constraint.
+- Phase length: <e.g. two weeks>.
+
+## Gateway Schedule
+
+| Gateway | Document | Window | Decision date | Owner | Stories | Main deliverable | Milestone |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| <name> | [MIL-<n>] | <dates> | <date> | <S-ID> | <US-…> | <deliverable> | <link once synced> |
+
+```plantuml
+@startgantt
+Project starts <start YYYY-MM-DD>
+[Phase 1] starts <start YYYY-MM-DD> and ends <end YYYY-MM-DD>
+[Phase 1 Go/No-Go] happens <date YYYY-MM-DD>
+@endgantt
+```
+
+## Scope Coverage
+
+| Business Case scope item | Gateway |
+| --- | --- |
+
+## Dependencies
+
+```
+<phase 1> → <phase 2> → ...
+```
+
+## Plan Risks
+
+| Risk | Impact | Mitigation |
+| --- | --- | --- |
+
+## Open Issues
+
+- <unresolved item>
+
+---
+
+@LINKS@
@@ -0,0 +1,42 @@
+# @TITLE@
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | @ID@ |
+| CrossReference | @CROSSREF@ |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| @DATE@ | Accepted | @AUTHOR@ | <reviewer S-ID> | Initial version | pending |
+
+Allowed Status values: `Proposed`, `Accepted`, `Rejected`, `Deprecated`. The latest reviewed row is `Accepted`; the row before it is `Deprecated`.
+
+---
+
+## Purpose
+
+<Why this artifact type matters and what decision it supports.>
+
+## 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 | <criterion> | Mandatory | <characteristic(s)> | |
+
+## Common Defects
+
+- <anti-pattern 1>
+- <anti-pattern 2>
+
+## Traceability Rule
+
+- Backward: <what this artifact must link to as input> ([QC-<BACKWARD-SHORT-NAME>-<NNN>])
+- Forward: <what this artifact must feed into as output> ([QC-<FORWARD-SHORT-NAME>-<NNN>])
+
+---
+
+@LINKS@
@@ -0,0 +1,39 @@
+# @TITLE@
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | @ID@ |
+| CrossReference | @CROSSREF@ |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| @DATE@ | Accepted | @AUTHOR@ | <reviewer S-ID> | Initial version | pending |
+
+---
+
+## Artifact Under Review
+
+- Instance reviewed: [<INSTANCE-ID>]
+- Checklist used: [<QC-ID>] (`QC-<short-name>-<version>`, e.g. `QC-BC-001`)
+
+## Checklist Results
+
+| # | Criterion | Status | Evidence/Notes |
+| --- | --- | --- | --- |
+| 1 | <criterion copied from the QC checklist> | Pass/Fail/N-A | |
+
+## Overall Verdict
+
+<Go / Go-with-conditions / No-Go> — <rationale>
+
+## Action Items
+
+| Action | Owner | Due |
+| --- | --- | --- |
+| <action> | <stakeholder ID, e.g. S07> | <date> |
+
+---
+
+@LINKS@
@@ -0,0 +1,54 @@
+# @TITLE@
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | @ID@ |
+| CrossReference | @CROSSREF@ |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| @DATE@ | Accepted | @AUTHOR@ | <reviewer S-ID> | Initial version | pending |
+
+---
+
+## Purpose
+
+<why this analysis exists; methodology followed>
+
+## 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@
@@ -0,0 +1,47 @@
+# @TITLE@
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | @ID@ |
+| CrossReference | @CROSSREF@ |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| @DATE@ | Accepted | @AUTHOR@ | <reviewer S-ID> | Initial version | pending |
+
+---
+
+## Sequence: <operationName>
+
+**Realizes:** `operationName` in [OC-<n>]
+
+### 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@
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
Tirsvad	3c99040b96	Add Blackjack game: rules, card rendering, game loop and tests Implement the playable console game for gateway MIL-002. - rules.py: deal_card, calculate_score (blackjack = 0, aces drop 11 -> 1) and compare with an Outcome enum; no console I/O - display.py: hand rendering as plain-text rank plus suit emoji (keycap emoji rendered as boxes in common terminals), score formatting and outcome messages - art.py: course logo shown at the start of every game - game.py: play_game (hit/stand, dealer draws below 17), play (restart loop, console clear, logo) and ask_yes_no with re-prompt; read, write and draw are injected so games can be scripted - __main__.py: python -m blackjack entry point, exits cleanly on Ctrl+C/Ctrl+D - constants.py: card ranks and suits, prompts and messages - tests: 32 new unit and scripted end-to-end tests (35 in total) - README: run instructions for python -m blackjack Closes #7 Closes #8 Closes #9 Closes #10 Closes #11 Closes #12 Closes #13 Closes #14 Task: MIL-002#1 Task: MIL-002#2 Task: MIL-002#3 Task: MIL-002#4 Task: MIL-002#5 Task: MIL-002#6 Task: MIL-002#7 Task: MIL-002#8	2026-10-04 22:04:40 +08:00
Tirsvad	3381855019	Merge pull request 'Add project setup: layout, pyproject, constants, Doxyfile, README' (#16 ) from mil-001-project-setup into main TirSystem/github-action: Sync GitHub mirror metadata / sync-metadata (push) Successful in 5s Details Reviewed-on: #16	2026-10-04 15:50:19 +02:00
Tirsvad	36b5788aef	Add project setup: layout, pyproject, constants, Doxyfile, README Set up the Blackjack project foundation for gateway MIL-001. - pyproject.toml: Python >=3.13, src layout, no runtime dependencies, optional dev extras (ruff, mypy, pytest) and their configuration - src/blackjack/: package with constants.py (deck, scoring thresholds, emoji card faces) and Doxygen-style docstrings - tests/test_package.py: smoke tests for the package and its constants - Doxyfile: reads src/, writes HTML to docs/doxygen/ - README.md: venv setup with pip upgrade, run, test, lint and Doxygen instructions - .gitignore: ignore generated docs/doxygen/ The repository description and topics were set on the git host through its API (no file change). Closes #1 Closes #2 Closes #3 Closes #4 Closes #5 Closes #6 Task: MIL-001#1 Task: MIL-001#2 Task: MIL-001#3 Task: MIL-001#4 Task: MIL-001#5 Task: MIL-001#6	2026-10-04 21:48:52 +08:00
Tirsvad	97c71fbec2	Merge pull request 'Add planning baseline: BC, SA, PP and two gateways' (#15 ) from Planning into main TirSystem/github-action: Sync GitHub mirror metadata / sync-metadata (push) Successful in 7s Details Reviewed-on: #15	2026-10-04 15:39:58 +02:00
Tirsvad	1d35410b8d	Add planning baseline: BC, SA, PP and two gateways Create the Business Case, Stakeholder Analysis (S01 course participant, S02 Udemy coursists, S03 GitHub viewers), Project Plan and the milestone documents MIL-001 (project setup, 6 tasks) and MIL-002 (game implementation, 8 tasks) for the console Blackjack game. Register PP and MIL in the artifact registry, set the PO language to en, and link the synced Gitea milestones in the Gateway Schedule. Refs #1 Refs #2 Refs #3 Refs #4 Refs #5 Refs #6 Refs #7 Refs #8 Refs #9 Refs #10 Refs #11 Refs #12 Refs #13 Refs #14	2026-10-04 21:38:09 +08:00