docs/adr/adr-0004-shared-wiki-publishing-opt-in.md

@@ -0,0 +1,117 @@
+# ADR-0004: Opt-in rule and secret handling of the shared wiki publisher
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | ADR-0004 |
+| CrossReference | [MIL-006], [ADR-0003], [ADR-0002] |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| 2026-10-10 | Deprecated | Jens Tirsvad Nielsen | S01 | Initial version | [b22a2cd] |
+| 2026-10-10 | Accepted | Jens Tirsvad Nielsen | S01 | Reviewed (RC-018): the `prune` variant added to the evaluated options | [b22a2cd] |
+
+Allowed Status values: `Proposed`, `Accepted`, `Rejected`, `Deprecated`, `Superseded by ADR-NNNN`.
+
+---
+
+## Context
+
+MIL-006 turns the Publish wiki workflow into a scoped workflow, which Gitea
+runs in every repository of every organisation on the instance (verified,
+issue #9). The publisher writes to a repository's wiki and removes pages that
+are not in `wiki/`. Without a gate, any of the 26 repositories of
+`Tirsvad-Udemy-100-days-of-code`, or any other repository, that happens to
+have a `wiki/` folder would have its wiki overwritten or emptied by a
+workflow it never asked for. The secret is also per organisation, so the
+shared workflow must say what happens where it is missing, and
+[ADR-0003] let this repository fall back to `TOKEN_FOR_GITEA`.
+
+Options for how a repository opts in:
+
+1. **A marker file `wiki/.publish`** on the default branch. Visible in the
+   repository, reviewed in a pull request, and nothing to configure in an
+   organisation. It comes in two forms:
+   - **(a) the marker alone** makes the wiki equal `wiki/`, so pages that are
+     not in the folder are deleted, as in ADR-0003;
+   - **(b) the marker plus the word `prune`** in it: without the word the
+     workflow only creates and updates pages, and deleting is a second,
+     explicit choice.
+2. **A repository variable** (for example `PUBLISH_WIKI=true`). Not part of
+   the repository content, so it is not reviewed or versioned, and it has to
+   be set in the web interface once per repository.
+3. **An allow list** in this repository. One place to read, but every
+   repository in every organisation has to ask this repository for a change.
+4. **Publish whenever `wiki/` exists.** No setup, which is the risk the gate
+   is meant to remove.
+
+Option 1(b) is chosen for the reason in the first paragraph: a repository
+that adds `wiki/` to a wiki it wrote by hand should not lose that wiki by
+opting in.
+
+Options for the secret:
+
+1. **`TOKEN_FOR_GITEA_WIKI` of the organisation only.** The sync token stays
+   read-only everywhere.
+2. **Fall back to `TOKEN_FOR_GITEA`** as in ADR-0003. A missing wiki secret is
+   hidden until a write is refused (HTTP 403).
+
+## Decision
+
+A repository opts in by committing `wiki/.publish` on its default branch; the
+file may contain the single word `prune`, which is the only thing that lets the
+workflow delete wiki pages that are not in `wiki/`, and without the marker the
+workflow ends successfully without any request. The shared workflow uses the
+organisation's `TOKEN_FOR_GITEA_WIKI` only, and fails with a configuration
+error when a repository has opted in and the secret is missing.
+
+The rules that follow from it:
+
+- Without `prune` the workflow only creates and updates pages.
+- An empty `wiki/` (no Markdown page) never deletes anything, with or without
+  `prune`.
+- A repository that has not opted in is skipped with one log line, so its
+  runs stay green.
+- This repository commits `wiki/.publish` containing `prune`, because its wiki
+  must equal `wiki/` (ADR-0001, ADR-0003).
+- The fallback to `TOKEN_FOR_GITEA` of ADR-0003 is removed from the shared
+  workflow; the sync token is read-only everywhere.
+
+## Consequences
+
+**Positive:**
+
+- A repository that did not opt in is never written to, and the marker is a
+  reviewed change in the repository that wants it.
+- Deleting pages is a second, explicit choice, so adopting the workflow in a
+  repository with hand-written wiki pages loses nothing.
+- A missing wiki secret is reported where it happens, in the repository that
+  opted in, and the sync token never gets write access.
+
+**Negative:**
+
+- Each organisation that wants this needs its own `TOKEN_FOR_GITEA_WIKI`; it
+  cannot borrow the sync token.
+- A repository that opts in without `prune` keeps pages that were removed from
+  `wiki/`, so its wiki can drift from the folder until someone adds `prune`.
+- Anyone with write access to a repository can opt it in and, with `prune`,
+  make the workflow delete its wiki pages; that is the intended scope of write
+  access, but it is not a separate approval.
+- The change supersedes the fallback part of [ADR-0003], so the credentials
+  guide and the wiki pages that mention it need an update (MIL-006 task 5).
+
+## Affected Artifacts
+
+- [MIL-006] — tasks 2, 3 and 4 (issues #57 to #59) implement and pilot this
+  decision.
+- [ADR-0003] — its fallback to `TOKEN_FOR_GITEA` no longer applies to the
+  shared workflow.
+- [ADR-0002] — the stand-in rule applies to the review of this ADR.
+
+---
+
+[MIL-006]: ../milestones/mil-006-shared-wiki-publishing.md
+[ADR-0003]: ./adr-0003-wiki-publish-token.md
+[ADR-0002]: ./adr-0002-s01-approves-as-stand-in.md
+[b22a2cd]: https://git.tirsystem.com/TirSystem/github-action/commit/b22a2cd59235078656c4440b945b787f88fbd345

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 | 007 |
-| RC | SQA Review Record | docs/sqa/reviews/rc-*.md | 018 |
+| RC | SQA Review Record | docs/sqa/reviews/rc-*.md | 019 |
 | TM | Traceability Matrix | docs/sqa/traceability-matrix.md | 002 |
-| ADR | Architecture Decision Record | docs/adr/adr-NNNN-*.md | 0004 |
+| ADR | Architecture Decision Record | docs/adr/adr-NNNN-*.md | 0005 |
 
 ## Languages
 

docs/project-plan.md

@@ -35,7 +35,7 @@ workflows. The Business Case sets no deadline, so the dates are proposals.
 | Shared quality checks | [MIL-003] | 2026-11-02 to 2026-11-14 | 2026-11-14 | S05 | None yet | Reusable quality-check workflow | [Milestone MIL-003] |
 | Versioned release and publishing | [MIL-004] | 2026-11-16 to 2026-11-28 | 2026-11-28 | S05 | None yet | Release process and reusable release workflow | [Milestone MIL-004] |
 | Wiki and translations | [MIL-005] | 2026-11-30 to 2026-12-12 | 2026-12-12 | S05 | None yet | Wiki pages in English, Danish and Bahasa Malaysia, kept current by every pull request | [Milestone MIL-005] |
-| Shared wiki publishing | [MIL-006] | 2026-12-14 to 2026-12-26 | 2026-12-26 | S05 | None yet | Scoped publish-wiki workflow with opt-in, piloted in one other repository | Not created yet |
+| Shared wiki publishing | [MIL-006] | 2026-12-14 to 2026-12-26 | 2026-12-26 | S05 | None yet | Scoped publish-wiki workflow with opt-in, piloted in one other repository | [Milestone MIL-006] |
 
 ```plantuml
 @startgantt
@@ -255,5 +255,6 @@ no tests, no release process.
 [Milestone MIL-003]: https://git.tirsystem.com/TirSystem/github-action/milestone/20
 [Milestone MIL-004]: https://git.tirsystem.com/TirSystem/github-action/milestone/21
 [Milestone MIL-005]: https://git.tirsystem.com/TirSystem/github-action/milestone/93
+[Milestone MIL-006]: https://git.tirsystem.com/TirSystem/github-action/milestone/94
 [b282e10]: https://git.tirsystem.com/TirSystem/github-action/commit/b282e107416a890d6df27e6bdf23ab8a65e17123
 [6b8e36d]: https://git.tirsystem.com/TirSystem/github-action/commit/6b8e36d67ac9af165b180bc0045289e41cfd1fc3

docs/sqa/reviews/rc-018-adr-0004.md

@@ -0,0 +1,52 @@
+# Review Record: ADR-0004 Opt-in rule and secret handling of the shared wiki publisher
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | RC-018 |
+| CrossReference | [ADR-0004], [QC-ADR-001] |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| 2026-10-10 | Accepted | Jens Tirsvad Nielsen | S01 | Initial version | [b22a2cd] |
+
+---
+
+## Artifact Under Review
+
+- Instance reviewed: [ADR-0004]
+- 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-0004 in `adr-0004-shared-wiki-publishing-opt-in.md`; follows ADR-0003. |
+| 2 | Context states the problem, the forces (cost, risk, constraints) and the options evaluated | Pass | States the scoped delivery, the deletion risk, the per-organisation secret and the fallback. |
+| 3 | At least two options were considered, or the absence of alternatives is justified | Pass | Four options for opting in (one with two forms) and two for the secret. |
+| 4 | Decision is stated in one or two unhedged sentences and matches one of the evaluated options | Pass | Finding fixed during this review: the `prune` form was not among the evaluated options. It is now option 1(b), with the reason. The decision is two sentences. |
+| 5 | Consequences list both Positive and Negative outcomes | Pass | Three positive, four negative. |
+| 6 | Quality-attribute impacts (performance, security, portability, etc.) are named where the decision affects them | Pass | Security is named: no write without opt-in, no write access for the sync token, write access of anyone with repository write rights. |
+| 7 | Affected Artifacts are listed as links, and each is also in CrossReference | Pass | MIL-006, ADR-0003 and ADR-0002 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 | The earlier row is kept and only its status changed. |
+| 9 | A superseded or deprecated ADR names its successor, and the successor links back | N-A | ADR-0003 is superseded only in part and stays in force for this repository's local workflow until MIL-006 task 2 lands; see the action item. |
+| 10 | Written in business or technical language of the domain, with no unexplained abbreviations | Pass | IT Professional English; `prune` and the marker are explained where they are introduced. |
+| 11 | Status is one of `Proposed`, `Accepted`, `Rejected`, `Deprecated` or `Superseded by ADR-NNNN`, and every Version History row uses only these | Pass | Deprecated and 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 |
+| --- | --- | --- |
+| When MIL-006 task 2 (#57) merges, mark ADR-0003 as superseded by ADR-0004 for the shared workflow (new version row and review record) | S01 | 2026-12-26 |
+| Choose the pilot repository (MIL-006 task 4, already an action item in RC-016) | S01 | 2026-12-14 |
+
+---
+
+[ADR-0004]: ../../adr/adr-0004-shared-wiki-publishing-opt-in.md
+[QC-ADR-001]: ../../../framework/qc/qc-adr.md
+[b22a2cd]: https://git.tirsystem.com/TirSystem/github-action/commit/b22a2cd59235078656c4440b945b787f88fbd345

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], [MIL-006], [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], [RC-015], [RC-016], [RC-017], [ADR-0001], [ADR-0002], [ADR-0003] |
+| CrossReference | [BC-001], [SA-001], [PP-001], [MIL-001], [MIL-002], [MIL-003], [MIL-004], [MIL-005], [MIL-006], [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], [RC-015], [RC-016], [RC-017], [RC-018], [ADR-0001], [ADR-0002], [ADR-0003], [ADR-0004] |
 
 ## Version History
 | Date | Status | Author | Reviewer | Change | Commit |
 | --- | --- | --- | --- | --- | --- |
-| 2026-10-10 | Deprecated | Jens Tirsvad Nielsen | S01 | Added MIL-006 and RC-016 | [676a262] |
+| 2026-10-10 | Deprecated | Jens Tirsvad Nielsen | S01 | Added RC-017 for PP-001 | [676a262] |
-| 2026-10-10 | Accepted | Jens Tirsvad Nielsen | S01 | Added RC-017 for PP-001 | [676a262] |
+| 2026-10-10 | Accepted | Jens Tirsvad Nielsen | S01 | Added ADR-0004 and RC-018 | [b22a2cd] |
 
 ---
 
@@ -45,7 +45,8 @@ updated whenever an artifact instance is created or reviewed.
 | [RC-010] | RC | [MIL-005] | - | - |
 | [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] |
+| [ADR-0003] | ADR | [MIL-005], [ADR-0001], [RC-011] | [ADR-0004] | [RC-014] |
+| [ADR-0004] | ADR | [MIL-006], [ADR-0003], [ADR-0002] | - | [RC-018] |
 | [RC-011] | RC | [MIL-005] | - | - |
 | [RC-012] | RC | [ADR-0001] | - | - |
 | [RC-013] | RC | [ADR-0002] | - | - |
@@ -53,6 +54,7 @@ updated whenever an artifact instance is created or reviewed.
 | [RC-015] | RC | [PP-001] | - | - |
 | [RC-016] | RC | [MIL-006] | - | - |
 | [RC-017] | RC | [PP-001] | - | - |
+| [RC-018] | RC | [ADR-0004] | - | - |
 
 ## Coverage Notes
 
@@ -87,9 +89,12 @@ updated whenever an artifact instance is created or reviewed.
 [ADR-0001]: ../adr/adr-0001-wiki-structure-and-languages.md
 [ADR-0002]: ../adr/adr-0002-s01-approves-as-stand-in.md
 [ADR-0003]: ../adr/adr-0003-wiki-publish-token.md
+[ADR-0004]: ../adr/adr-0004-shared-wiki-publishing-opt-in.md
 [RC-013]: ./reviews/rc-013-adr-0002.md
 [RC-014]: ./reviews/rc-014-adr-0003.md
 [RC-015]: ./reviews/rc-015-project-plan-pat.md
 [RC-016]: ./reviews/rc-016-mil-006.md
 [RC-017]: ./reviews/rc-017-project-plan-mil-006.md
+[RC-018]: ./reviews/rc-018-adr-0004.md
 [676a262]: https://git.tirsystem.com/TirSystem/github-action/commit/676a26240563338307c0454c3bf15b960bdb58ca
+[b22a2cd]: https://git.tirsystem.com/TirSystem/github-action/commit/b22a2cd59235078656c4440b945b787f88fbd345