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.
This commit is contained in:
2026-10-10 10:29:35 +08:00
parent 1a9c9a32e7
commit bc3bd07b29
6 changed files with 253 additions and 7 deletions
@@ -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
+70
View File
@@ -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
+2 -2
View File
@@ -11,9 +11,9 @@ each document lives in *this* project and the next version to use.
| SA | Stakeholder Analysis | docs/stakeholder-analysis.md | 002 | | SA | Stakeholder Analysis | docs/stakeholder-analysis.md | 002 |
| PP | Project Plan | docs/project-plan.md | 002 | | PP | Project Plan | docs/project-plan.md | 002 |
| MIL | Milestone / Gateway | docs/milestones/*.md | 006 | | 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 | | 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 ## Languages
+50
View File
@@ -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
+50
View File
@@ -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
+12 -5
View File
@@ -4,13 +4,13 @@
| Key | Value | | Key | Value |
| --- | --- | | --- | --- |
| ID | TM-001 | | 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 ## Version History
| Date | Status | Author | Reviewer | Change | Commit | | 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 | Deprecated | Jens Tirsvad Nielsen | S01 | Added ADR-0001 and RC-012 | [d0618d9] |
| 2026-10-10 | Accepted | 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-008] | RC | [BC-001] | - | - |
| [RC-009] | RC | [PP-001] | - | - | | [RC-009] | RC | [PP-001] | - | - |
| [RC-010] | RC | [MIL-005] | - | - | | [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-011] | RC | [MIL-005] | - | - |
| [RC-012] | RC | [ADR-0001] | - | - | | [RC-012] | RC | [ADR-0001] | - | - |
| [RC-013] | RC | [ADR-0002] | - | - |
| [RC-014] | RC | [ADR-0003] | - | - |
## Coverage Notes ## 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-011]: ./reviews/rc-011-mil-005-wiki-publishing.md
[RC-012]: ./reviews/rc-012-adr-0001.md [RC-012]: ./reviews/rc-012-adr-0001.md
[ADR-0001]: ../adr/adr-0001-wiki-structure-and-languages.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 [d0618d9]: https://git.tirsystem.com/TirSystem/github-action/commit/d0618d929f2ec274d30b10bb1be306e1f04c31ee