[HIGH doc-trust] docs: README and integration.md contradict on `secrets: inherit` — both overstate it (RECOMMENDED, not required) #197

New issue

Closed

opened 2026-06-27 15:26:20 +02:00 by shipwright · 0 comments

shipwright commented

2026-06-27 15:26:20 +02:00

Owner

Filed from the #157 consumer-walkthrough audit (report, finding H2), corrected by Surveyor's empirical review on #200 (review 3145 + d50c).

Problem — a real contradiction, but BOTH sides overstate

The two primary adoption surfaces disagree on whether secrets: inherit is required:

README.md L115: secrets: inherit # required for path-(alpha) token override — frames it as conditional on path-α.
docs/integration.md L227–236: consumers "MUST inherit … even on path-γ (no token)" — unconditional MUST.

A fresh adopter reading the two surfaces gets contradictory instructions. The contradiction itself is the defect — it erodes doc-trust and leaves an adopter unsure which to believe.

Correction (empirical — supersedes the original "breakage" framing)

The original audit framing called this "the exact #135 breakage, re-manifested." That over-stated it. Surveyor empirically verified (d50c, on the cellblock adoption today) that the without-inherit shape RUNS and WORKS: Forgejo resolves the missing secrets.RELEASE_TOOLKIT_TOKEN reference to empty → the reusable's bash :- fallback to GITHUB_TOKEN kicks in → cellblock's first cut literally ran without secrets: inherit and shipped v1.1.0 clean.

So both doc claims are wrong in the same direction:

README's "required" — overstated.
integration.md's "MUST … even on path-γ" — also overstated.

secrets: inherit is RECOMMENDED (it's needed for path-α's RELEASE_TOOLKIT_TOKEN, and it's the only shape the toolkit has actively exercised), but omitting it on path-γ degrades benignly — the substrate handles the missing reference without breakage.

Severity reframe

HIGH on doc-trust — the contradiction is real, user-visible, and erodes confidence; keep it visible / fix it.
NOT adoption-breakage — runtime is benign. This is reconcile-the-contradiction, not fix-a-breakage.

Fix

Reconcile both surfaces to the accurate framing — do not pick one of the two overstatements:

README + integration.md both say secrets: inherit is RECOMMENDED (required for path-α's token; optional on path-γ where the bash :-→GITHUB_TOKEN fallback covers the omission — empirically benign per cellblock v1.1.0).
Note the substrate's benign-omission behavior so a future adopter who omits it isn't alarmed.
Elevate from inline comment toward a numbered step (companion finding M5, #199).

Possible structural follow-up (for triage)

The same gap-class touched this surface twice (#135, then this contradiction). Even though runtime is benign, a docs-consistency check (lint/CI) asserting the quick-start and integration examples agree on the load-bearing lines (secrets: inherit, paths-ignore, ref pins) would keep the doc-trust surface honest. Scope TBD by operator + Engineer.

Refs

#135 (the original empirical instance — note: also benign per the same fallback)
#200 review 3145 + Surveyor's d50c empirical verification
#157 (this audit)

Filed from the #157 consumer-walkthrough audit ([report](https://git.frankenbit.de/frankenbit/release-toolkit/issues/157#issuecomment-75472), finding **H2**), **corrected by Surveyor's empirical review** on #200 (review 3145 + d50c). ## Problem — a real contradiction, but BOTH sides overstate The two primary adoption surfaces disagree on whether `secrets: inherit` is required: - `README.md` L115: `secrets: inherit # required for path-(alpha) token override` — frames it as **conditional** on path-α. - `docs/integration.md` L227–236: consumers *"MUST inherit … even on path-γ (no token)"* — **unconditional MUST**. A fresh adopter reading the two surfaces gets contradictory instructions. **The contradiction itself is the defect** — it erodes doc-trust and leaves an adopter unsure which to believe. ## Correction (empirical — supersedes the original "breakage" framing) The original audit framing called this *"the exact #135 breakage, re-manifested."* **That over-stated it.** Surveyor empirically verified (d50c, on the cellblock adoption today) that the **without-`inherit` shape RUNS and WORKS**: Forgejo resolves the missing `secrets.RELEASE_TOOLKIT_TOKEN` reference to empty → the reusable's bash `:-` fallback to `GITHUB_TOKEN` kicks in → **cellblock's first cut literally ran without `secrets: inherit` and shipped v1.1.0 clean**. So **both** doc claims are wrong in the same direction: - README's "required" — overstated. - integration.md's "MUST … even on path-γ" — also overstated. `secrets: inherit` is **RECOMMENDED** (it's needed for path-α's `RELEASE_TOOLKIT_TOKEN`, and it's the only shape the toolkit has actively exercised), but **omitting it on path-γ degrades benignly** — the substrate handles the missing reference without breakage. ## Severity reframe - **HIGH on doc-trust** — the contradiction is real, user-visible, and erodes confidence; keep it visible / fix it. - **NOT adoption-breakage** — runtime is benign. This is *reconcile-the-contradiction*, **not** *fix-a-breakage*. ## Fix Reconcile **both** surfaces to the accurate framing — **do not pick one of the two overstatements**: 1. README + integration.md both say `secrets: inherit` is **RECOMMENDED** (required for path-α's token; optional on path-γ where the bash `:-`→`GITHUB_TOKEN` fallback covers the omission — empirically benign per cellblock v1.1.0). 2. Note the substrate's benign-omission behavior so a future adopter who omits it isn't alarmed. 3. Elevate from inline comment toward a numbered step (companion finding M5, #199). ## Possible structural follow-up (for triage) The same gap-class touched this surface twice (#135, then this contradiction). Even though runtime is benign, a docs-consistency check (lint/CI) asserting the quick-start and integration examples agree on the load-bearing lines (`secrets: inherit`, `paths-ignore`, ref pins) would keep the *doc-trust* surface honest. Scope TBD by operator + Engineer. ## Refs - #135 (the original empirical instance — note: also benign per the same fallback) - #200 review 3145 + Surveyor's d50c empirical verification - #157 (this audit)

shipwright referenced this issue from a commit

2026-06-27 15:27:57 +02:00

docs(walkthrough): fresh-eyes consumer-adoption audit (#157)

shipwright referenced this issue

2026-06-27 15:28:26 +02:00

docs(walkthrough): fresh-eyes consumer-adoption audit (#157) #200

shipwright changed title from ~~[HIGH] docs: README and integration.md contradict on whether secrets: inherit is conditional (re-manifests #135)~~ to [HIGH doc-trust] docs: README and integration.md contradict on secrets: inherit — both overstate it (RECOMMENDED, not required)

2026-06-27 15:35:29 +02:00

shipwright referenced this issue from a commit

2026-06-27 15:36:37 +02:00

docs(walkthrough): fold Surveyor's empirical H2 correction into the record (#157)