docs(solutions): standardize verified field on ISO dates and refresh privacy-gate code

[marcusrbrown]

Closes #3351.

Addresses the two non-blocking concerns from #3350's review.

1. verified field convention sweep (13 files)

docs/solutions/ had two shapes in use:

• verified: true (boolean) \u2014 14 older entries
• verified: YYYY-MM-DD (ISO date) \u2014 2 newer entries from docs(solutions): capture diagnostic-discipline + Issues-API race patterns #3350

Dates carry strictly more information. Sweep converts the 13 remaining boolean entries to ISO dates matching each file's date suffix, leaving the directory consistent on one shape.

Directory	Files converted
best-practices/	2
documentation-gaps/	1
integration-issues/	3
runtime-errors/	3
security-issues/	2 (incl. survey-workflow-side-privacy-gate-2026-05-16.md)
workflow-issues/	2

2. Stale-code refresh in survey-workflow-side-privacy-gate-2026-05-16.md

The doc's code blocks reflected the pre-#3344/#3346/#3347 state. Refreshed to match current production:

Block	Before	After
Resolve-step token	GH_TOKEN: ${{ secrets.FRO_BOT_PAT }}	App token via actions/create-github-app-token (PR #3347)
Resolve-step stderr	gh api graphql ... 2>/dev/null (swallow)	tempfile capture + marker-line dump on failure (PR #3344)
Resolve-step jq	jq -r ... // "null" (falsy-coalesce trap)	jq -er with composed selectors (current production)
Marker line	printf '--- gh stderr ---' >&2	printf '%s\\n' '--- gh stderr ---' >&2 (PR #3346 bash-builtin fix)
Recheck-step token	GH_TOKEN: ${{ secrets.FRO_BOT_PAT }}	GH_TOKEN: ${{ steps.gate-token.outputs.token }} (reuses gate token)
Output sink	{owner, repo} only	{owner, repo, node_id} (downstream concurrency key uses node_id)

Also honestly notes the recheck-step asymmetry: it still uses 2>/dev/null. That's #3345 \u2014 the production gap is unchanged by this PR, but the doc now flags it instead of pretending it's resolved.

Two new prevention rules:

1. Public-read GraphQL gates use App installation tokens, not user PATs. Pins the cross-org PAT-policy lesson from PR fix(survey-repo): use App token for cross-org privacy gate #3347.
2. Capture gh api stderr to a tempfile, not 2>/dev/null. Pins the diagnostic-discipline lesson from PRs diag(survey): surface gh api graphql stderr on privacy-gate lookup failure #3344/fix(survey-repo): use %s format for stderr markers (unblocks PR #3344 diagnostic) #3346.

Cross-links the diagnostic-discipline compound doc and the four referenced PRs. last_updated: 2026-05-23.

Verification

• pnpm lint clean
• pnpm check-types clean
• grep verified: docs/solutions/: zero boolean entries remain, all dates well-formed
• grep FRO_BOT_PAT docs/solutions/security-issues/survey-workflow-side-privacy-gate-*.md: zero matches (replaced by App-token references)

Docs-only. No workflow, action, dependency, or runtime code touched.

[fro-bot]

Verdict: PASS

Docs-only sweep. The boolean→ISO-date convention conversion is mechanical and correct (13 files, zero verified: true remain in docs/solutions/, all values are well-formed YYYY-MM-DD). The survey-workflow-side-privacy-gate-2026-05-16.md refresh tracks production faithfully: App-token mint replaces the cross-org PAT, the actions/create-github-app-token pin (bcd2ba49218906704ab6c1aa796996da409d3eb1) resolves to v3.2.0 commit, the jq -er composed-selector idiom replaces the // "null" falsy-coalesce trap, the printf '%s\n' '--- gh stderr ---' marker pattern is correctly preserved, and the recheck step honestly notes its remaining 2>/dev/null asymmetry as #3345 rather than papering over it.

The new prevention rule about App tokens for public-read GraphQL gates is a clean pin of the cross-org PAT-policy lesson — useful institutional memory.

Blocking issues

None.

Non-blocking concerns

• docs/solutions/security-issues/survey-workflow-side-privacy-gate-2026-05-16.md, recheck snippet — The recheck block sets GH_TOKEN: ${{ steps.gate-token.outputs.token }} but elides its body as # ... same shape-validate + GraphQL check as resolve, neutral abort on any failure .... A future reader copying this block wo't see at the code level that the recheck currently lacks the tempfile-capture pattern the resolve step demonstrates immediately above it. Consider showing the recheck body verbatim (including the 2>/dev/null) so the documented asymmetry is visually obvious, not just buried in the prose follow-up. Non-blocking; the prose already names #3345.
• PR description, rule 10 — The numbered list in the PR body shows 1. followed by 10. (the file itself is correctly sequential 1–10). Cosmetic only; no doc change needed.

Missing tests

N/A. Docs-only; no behavior change. No code paths added or modified. pnpm lint / pnpm check-types per author verification is the appropriate gate.

Risk assessment: LOW

Pure documentation. No workflow YAML, action source, dependency manifest, or runtime code touched. The frontmatter convention is consumed by docs/solutions/ tooling for indexing, and the boolean→date shape is strictly more informative — any consumer that broke on dates would have already broken on the 2/16 files that already used the date shape pre-sweep. The privacy-gate code-block refresh is read-only knowledge; it documents production rather than changing it.

---

Run Summary

Field	Value
Event	pull_request
Repository	fro-bot/.github
Run ID	26338968798
Cache	hit
Session	ses_1aa211b97ffebBrt11HtCoRXNz

[fro-bot]

Verdict: PASS

Recheck snippet is now verbatim. The inline # NOTE: recheck currently swallows stderr with 2>/dev/null — see follow-up below lands the asymmetry at the code level where a reader copying the block will see it, instead of burying it three paragraphs down. The prose underneath is also sharper: it names the 2026-05-20 diagnostic loop explicitly, pins PRs #3344/#3346 as the hardening source for resolve, and routes future readers to issue #3345 for the recheck patch.

Net effect: the doc now teaches the asymmetry rather than apologizing for it. Re-approving the prior verdict.

Blocking issues

None.

Non-blocking concerns

• Recheck snippet shape-validation — The new recheck verbatim block omits the NODE_ID shape-validation regex that the resolve step shows above it. The step header still says "same shape-validate + GraphQL check as resolve", which is technically accurate (production does shape-validate in both places), but a reader could copy this snippet and miss the regex. Trivial — section 2 above already demonstrates the pattern in full — not worth a re-spin.

Missing tests

N/A. Docs-only; no behavior change.

Risk assessment: LOW

Same as prior review. Pure documentation. The recheck-verbatim addition is read-only knowledge clarifying an already-tracked production gap (#3345), not changing production behavior.

---

Run Summary

Field	Value
Event	pull_request
Repository	fro-bot/.github
Run ID	26339068607
Cache	hit
Session	ses_1aa211b97ffebBrt11HtCoRXNz