From bc3bd07b29a0a3dcf45045b9baac64c36144c6d1 Mon Sep 17 00:00:00 2001 From: Jens Tirsvad Nielsen Date: Sat, 10 Oct 2026 10:29:35 +0800 Subject: [PATCH] Record the S01 stand-in rule and the wiki publish token decision ADR-0002: an artifact approved by S01 counts as approved for the other named reviewers, with the stand-in recorded. ADR-0003: the wiki is published with a separate TOKEN_FOR_GITEA_WIKI, dot-named titles work. Add review records RC-013 and RC-014 and update TM-001. --- docs/adr/adr-0002-s01-approves-as-stand-in.md | 69 ++++++++++++++++++ docs/adr/adr-0003-wiki-publish-token.md | 70 +++++++++++++++++++ docs/artifact-registry.md | 4 +- docs/sqa/reviews/rc-013-adr-0002.md | 50 +++++++++++++ docs/sqa/reviews/rc-014-adr-0003.md | 50 +++++++++++++ docs/sqa/traceability-matrix.md | 17 +++-- 6 files changed, 253 insertions(+), 7 deletions(-) create mode 100644 docs/adr/adr-0002-s01-approves-as-stand-in.md create mode 100644 docs/adr/adr-0003-wiki-publish-token.md create mode 100644 docs/sqa/reviews/rc-013-adr-0002.md create mode 100644 docs/sqa/reviews/rc-014-adr-0003.md diff --git a/docs/adr/adr-0002-s01-approves-as-stand-in.md b/docs/adr/adr-0002-s01-approves-as-stand-in.md new file mode 100644 index 0000000..d76de93 --- /dev/null +++ b/docs/adr/adr-0002-s01-approves-as-stand-in.md @@ -0,0 +1,69 @@ +# ADR-0002: S01 approves as stand-in for other reviewers + +## Metadata +| Key | Value | +| --- | --- | +| ID | ADR-0002 | +| CrossReference | [SA-001], [RC-001] | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| 2026-10-10 | Accepted | Jens Tirsvad Nielsen | S01 | Initial version | pending | + +Allowed Status values: `Proposed`, `Accepted`, `Rejected`, `Deprecated`, `Superseded by ADR-NNNN`. + +--- + +## Context + +The project plan names reviewers by stakeholder ID: S01 (Product Owner) is +the approving reviewer, S05 (DevOps owner and security authority) owns the +milestones, and S03 operates runners and secrets. The Stakeholder Analysis +([SA-001]) says credential, token and permission design cannot be accepted +without S05, and the Business Case lists S05's review of every security-relevant +change as the mitigation for a risk. In practice S01 has been approving +documents and has stood in for S05 and S03 (the first time is recorded in +[RC-001]), because there is currently one person doing all three roles. The +framework also requires that a reviewer is not the author of an artifact. + +Options: + +1. **Require each named person to review.** The record is independent, but + work waits for a person who is not available in the project's current + setup, and the S05 actions in RC-001 and RC-011 stayed open. +2. **S01 approves for everyone and the records say so.** Work continues, and + each record names who really approved. +3. **Drop the other reviewers from the documents.** Simple, but it hides who + is accountable and removes the way back to independent review. + +## Decision + +An artifact approved by S01 counts as approved for the stakeholders named +as its reviewers or action owners (S05, S03), and the record says that S01 +stood in. This applies to every artifact of this project, including the review +records themselves, until a named stakeholder asks to review in their own +right; that person's review then replaces the stand-in for later changes. + +## Consequences + +**Positive:** + +- Work is not blocked by a reviewer who is not present, and the records stay honest about who approved. +- The way back to independent review is kept: the stakeholder IDs stay in the documents. + +**Negative:** + +- No independent check: the author, the approving reviewer and the stand-in are the same person, so a security-relevant change (credentials, tokens, permissions, workflow code) has had no second reader. +- It conflicts with the text of [SA-001] (S05 must accept credential, token and permission design) and with the Business Case mitigation "S05 reviews every change"; both still say so and need an amendment, or S05 needs to be told. +- The framework rule that the reviewer must not be the author is not met; this is a project deviation to be taken upstream, not a framework change. + +## Affected Artifacts + +- [SA-001] — the statement that credential, token and permission design cannot be accepted without S05 no longer holds. +- [RC-001] — its action item for an independent S05 review is closed by this decision; the other records that refer to it follow. + +--- + +[SA-001]: ../stakeholder-analysis.md +[RC-001]: ../sqa/reviews/rc-001-business-case.md diff --git a/docs/adr/adr-0003-wiki-publish-token.md b/docs/adr/adr-0003-wiki-publish-token.md new file mode 100644 index 0000000..9a1def8 --- /dev/null +++ b/docs/adr/adr-0003-wiki-publish-token.md @@ -0,0 +1,70 @@ +# ADR-0003: Wiki publish token and dot-named page titles + +## Metadata +| Key | Value | +| --- | --- | +| ID | ADR-0003 | +| CrossReference | [MIL-005], [ADR-0001], [RC-011] | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| 2026-10-10 | Accepted | Jens Tirsvad Nielsen | S01 | Initial version | pending | + +Allowed Status values: `Proposed`, `Accepted`, `Rejected`, `Deprecated`, `Superseded by ADR-NNNN`. + +--- + +## Context + +The Publish wiki workflow (MIL-005 task 8) writes the Gitea wiki and so +needs a token that can write to the repository. The existing `TOKEN_FOR_GITEA` +only reads (`read:repository`) and is used by the metadata sync, so raising its +scope would also give the sync write access. Gitea has no wiki-only scope. +After the first publish two open points from [ADR-0001] and [RC-011] were +answered: pages with a dot in the title are accepted, and the stored secret +must hold the bare token string (a value of the form `NAME=token` is rejected +with HTTP 401). + +Options: + +1. **Reuse `TOKEN_FOR_GITEA` and raise its scope.** One secret, but the + metadata sync gets write access it does not need. +2. **A separate `TOKEN_FOR_GITEA_WIKI` for a dedicated user.** One more + secret to store and rotate, and the sync token stays read-only. +3. **Push to the wiki repository by hand.** No secret, but unreviewed content + and no record of who published. + +## Decision + +The wiki is published with a separate secret, `TOKEN_FOR_GITEA_WIKI`, holding +a bare Gitea token with scope `write:repository` for a dedicated user that has +write access to this repository only; the workflow falls back to +`TOKEN_FOR_GITEA` only when it is absent. Dot-named titles (`Home.da`, +`Home.ms`) are kept as ADR-0001 decided. + +## Consequences + +**Positive:** + +- The metadata sync token stays read-only, so a leak of it cannot change the wiki or the code. +- The first publish (run 65) created all 15 pages and a read-back matched `wiki/` byte for byte. +- A rejected token is diagnosed from the log (length and shape, never the value). + +**Negative:** + +- One more secret to store and rotate, at organisation level for now; scoping it to this repository is a follow-up for the person who administers the secrets. +- The fallback to `TOKEN_FOR_GITEA` can hide a missing wiki secret until a write is refused (HTTP 403). +- The credentials guide and MIL-005 task 2 still say that S05 decides which token to use; the decision is recorded here. + +## Affected Artifacts + +- [MIL-005] — task 2 and task 8 (issues #33 and #42) are settled by this decision. +- [ADR-0001] — its negative consequence about dot-named titles is resolved: they work. +- [RC-011] — its action items for the secret scope (S05) and for storing the secret (S03) are done. + +--- + +[MIL-005]: ../milestones/mil-005-wiki-and-translations.md +[ADR-0001]: ./adr-0001-wiki-structure-and-languages.md +[RC-011]: ../sqa/reviews/rc-011-mil-005-wiki-publishing.md diff --git a/docs/artifact-registry.md b/docs/artifact-registry.md index fb5128c..b633e5f 100644 --- a/docs/artifact-registry.md +++ b/docs/artifact-registry.md @@ -11,9 +11,9 @@ each document lives in *this* project and the next version to use. | SA | Stakeholder Analysis | docs/stakeholder-analysis.md | 002 | | PP | Project Plan | docs/project-plan.md | 002 | | MIL | Milestone / Gateway | docs/milestones/*.md | 006 | -| RC | SQA Review Record | docs/sqa/reviews/rc-*.md | 013 | +| RC | SQA Review Record | docs/sqa/reviews/rc-*.md | 015 | | TM | Traceability Matrix | docs/sqa/traceability-matrix.md | 002 | -| ADR | Architecture Decision Record | docs/adr/adr-NNNN-*.md | 0002 | +| ADR | Architecture Decision Record | docs/adr/adr-NNNN-*.md | 0004 | ## Languages diff --git a/docs/sqa/reviews/rc-013-adr-0002.md b/docs/sqa/reviews/rc-013-adr-0002.md new file mode 100644 index 0000000..e6007fd --- /dev/null +++ b/docs/sqa/reviews/rc-013-adr-0002.md @@ -0,0 +1,50 @@ +# Review Record: ADR-0002 S01 approves as stand-in + +## Metadata +| Key | Value | +| --- | --- | +| ID | RC-013 | +| CrossReference | [ADR-0002], [QC-ADR-001] | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| 2026-10-10 | Accepted | Jens Tirsvad Nielsen | S01 | Initial version | pending | + +--- + +## Artifact Under Review + +- Instance reviewed: [ADR-0002] +- Checklist used: [QC-ADR-001] + +## Checklist Results + +| # | Criterion | Status | Evidence/Notes | +| --- | --- | --- | --- | +| 1 | The ID (`ADR-NNNN`, 4-digit) matches the filename number and is unique and sequential | Pass | ADR-0002 in `adr-0002-s01-approves-as-stand-in.md`. | +| 2 | Context states the problem, the forces (cost, risk, constraints) and the options evaluated | Pass | Names the roles, the conflicting text in SA-001 and the Business Case, and the framework rule. | +| 3 | At least two options were considered, or the absence of alternatives is justified | Pass | Three options. | +| 4 | Decision is stated in one or two unhedged sentences and matches one of the evaluated options | Pass | Two sentences; matches option 2. | +| 5 | Consequences list both Positive and Negative outcomes | Pass | Two positive, three negative. | +| 6 | Quality-attribute impacts (performance, security, portability, etc.) are named where the decision affects them | Pass | Security and accountability impacts are named; the missing second reader is the first negative. | +| 7 | Affected Artifacts are listed as links, and each is also in CrossReference | Pass | SA-001 and RC-001 are linked and cited. | +| 8 | Status changes are recorded as new Version History rows with a Change summary and Commit link; retained rows are never rewritten | Pass | Initial row only. | +| 9 | A superseded or deprecated ADR names its successor, and the successor links back | N-A | Nothing is superseded. | +| 10 | Written in business or technical language of the domain, with no unexplained abbreviations | Pass | IT Professional English; roles are given by ID. | +| 11 | Status is one of `Proposed`, `Accepted`, `Rejected`, `Deprecated` or `Superseded by ADR-NNNN`, and every Version History row uses only these | Pass | Accepted only. | + +## Overall Verdict + +Go - all applicable criteria pass. S01 gave the Go in chat on 2026-10-10, standing in for the other reviewers as ADR-0002 records; there is no independent reader. This record is itself approved under the rule it records, which is the weakness the ADR lists. + +## Action Items + +| Action | Owner | Due | +| --- | --- | --- | +| Tell S05 (Michael Kragh) about this ADR, and amend SA-001 and the Business Case mitigation, or have S05 accept the stand-in rule | S01 | 2026-10-17 | + +--- + +[ADR-0002]: ../../adr/adr-0002-s01-approves-as-stand-in.md +[QC-ADR-001]: ../../../framework/qc/qc-adr.md diff --git a/docs/sqa/reviews/rc-014-adr-0003.md b/docs/sqa/reviews/rc-014-adr-0003.md new file mode 100644 index 0000000..3420be5 --- /dev/null +++ b/docs/sqa/reviews/rc-014-adr-0003.md @@ -0,0 +1,50 @@ +# Review Record: ADR-0003 Wiki publish token + +## Metadata +| Key | Value | +| --- | --- | +| ID | RC-014 | +| CrossReference | [ADR-0003], [QC-ADR-001] | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| 2026-10-10 | Accepted | Jens Tirsvad Nielsen | S01 | Initial version | pending | + +--- + +## Artifact Under Review + +- Instance reviewed: [ADR-0003] +- Checklist used: [QC-ADR-001] + +## Checklist Results + +| # | Criterion | Status | Evidence/Notes | +| --- | --- | --- | --- | +| 1 | The ID (`ADR-NNNN`, 4-digit) matches the filename number and is unique and sequential | Pass | ADR-0003 in `adr-0003-wiki-publish-token.md`; follows ADR-0002. | +| 2 | Context states the problem, the forces (cost, risk, constraints) and the options evaluated | Pass | States the need, the scope problem, the two answered open points and the options. | +| 3 | At least two options were considered, or the absence of alternatives is justified | Pass | Three options. | +| 4 | Decision is stated in one or two unhedged sentences and matches one of the evaluated options | Pass | Finding fixed during this review: the decision had three sentences. It is now two sentences (option 2). | +| 5 | Consequences list both Positive and Negative outcomes | Pass | Three positive, three negative. | +| 6 | Quality-attribute impacts (performance, security, portability, etc.) are named where the decision affects them | Pass | Security is named: sync token stays read-only; fallback may hide a missing secret. | +| 7 | Affected Artifacts are listed as links, and each is also in CrossReference | Pass | MIL-005, ADR-0001 and RC-011 are linked and cited. | +| 8 | Status changes are recorded as new Version History rows with a Change summary and Commit link; retained rows are never rewritten | Pass | Initial row only. | +| 9 | A superseded or deprecated ADR names its successor, and the successor links back | N-A | Nothing is superseded. | +| 10 | Written in business or technical language of the domain, with no unexplained abbreviations | Pass | IT Professional English; `NAME=token`, `HTTP 401` and `403` are explained. | +| 11 | Status is one of `Proposed`, `Accepted`, `Rejected`, `Deprecated` or `Superseded by ADR-NNNN`, and every Version History row uses only these | Pass | Accepted only. | + +## Overall Verdict + +Go - all applicable criteria pass; the one finding (criterion 4) was fixed during the review. S01 gave the Go in chat on 2026-10-10, standing in for the other reviewers as ADR-0002 records; there is no independent reader. + +## Action Items + +| Action | Owner | Due | +| --- | --- | --- | +| Scope `TOKEN_FOR_GITEA_WIKI` to this repository instead of the organisation, and update the credentials guide and MIL-005 task 2 text (new version rows, retranslated wiki pages) | S03 | 2026-10-24 | + +--- + +[ADR-0003]: ../../adr/adr-0003-wiki-publish-token.md +[QC-ADR-001]: ../../../framework/qc/qc-adr.md diff --git a/docs/sqa/traceability-matrix.md b/docs/sqa/traceability-matrix.md index 38efc54..bb08c0d 100644 --- a/docs/sqa/traceability-matrix.md +++ b/docs/sqa/traceability-matrix.md @@ -4,13 +4,13 @@ | Key | Value | | --- | --- | | ID | TM-001 | -| CrossReference | [BC-001], [SA-001], [PP-001], [MIL-001], [MIL-002], [MIL-003], [MIL-004], [MIL-005], [RC-001], [RC-002], [RC-003], [RC-004], [RC-005], [RC-006], [RC-007], [RC-008], [RC-009], [RC-010], [RC-011], [RC-012], [ADR-0001] | +| CrossReference | [BC-001], [SA-001], [PP-001], [MIL-001], [MIL-002], [MIL-003], [MIL-004], [MIL-005], [RC-001], [RC-002], [RC-003], [RC-004], [RC-005], [RC-006], [RC-007], [RC-008], [RC-009], [RC-010], [RC-011], [RC-012], [RC-013], [RC-014], [ADR-0001], [ADR-0002], [ADR-0003] | ## Version History | Date | Status | Author | Reviewer | Change | Commit | | --- | --- | --- | --- | --- | --- | -| 2026-10-10 | Deprecated | Jens Tirsvad Nielsen | S01 | Added RC-011 for the MIL-005 amendment | [20361e8] | -| 2026-10-10 | Accepted | Jens Tirsvad Nielsen | S01 | Added ADR-0001 and RC-012 | [d0618d9] | +| 2026-10-10 | Deprecated | Jens Tirsvad Nielsen | S01 | Added ADR-0001 and RC-012 | [d0618d9] | +| 2026-10-10 | Accepted | Jens Tirsvad Nielsen | S01 | Added ADR-0002, ADR-0003 and RC-013, RC-014 | pending | --- @@ -42,9 +42,13 @@ updated whenever an artifact instance is created or reviewed. | [RC-008] | RC | [BC-001] | - | - | | [RC-009] | RC | [PP-001] | - | - | | [RC-010] | RC | [MIL-005] | - | - | -| [ADR-0001] | ADR | [BC-001], [MIL-005] | - | [RC-012] | +| [ADR-0001] | ADR | [BC-001], [MIL-005] | [ADR-0003] | [RC-012] | +| [ADR-0002] | ADR | [SA-001], [RC-001] | - | [RC-013] | +| [ADR-0003] | ADR | [MIL-005], [ADR-0001], [RC-011] | - | [RC-014] | | [RC-011] | RC | [MIL-005] | - | - | | [RC-012] | RC | [ADR-0001] | - | - | +| [RC-013] | RC | [ADR-0002] | - | - | +| [RC-014] | RC | [ADR-0003] | - | - | ## Coverage Notes @@ -76,5 +80,8 @@ updated whenever an artifact instance is created or reviewed. [RC-011]: ./reviews/rc-011-mil-005-wiki-publishing.md [RC-012]: ./reviews/rc-012-adr-0001.md [ADR-0001]: ../adr/adr-0001-wiki-structure-and-languages.md -[20361e8]: https://git.tirsystem.com/TirSystem/github-action/commit/20361e881ebd0dc52e1d1c358ceb792c41b76c60 +[ADR-0002]: ../adr/adr-0002-s01-approves-as-stand-in.md +[ADR-0003]: ../adr/adr-0003-wiki-publish-token.md +[RC-013]: ./reviews/rc-013-adr-0002.md +[RC-014]: ./reviews/rc-014-adr-0003.md [d0618d9]: https://git.tirsystem.com/TirSystem/github-action/commit/d0618d929f2ec274d30b10bb1be306e1f04c31ee