Review proposed organization ADRs 0008–0010 for acceptance

[ss-o]

Objective

Reconcile organization ADRs 0008–0010 with live repository behavior, then obtain an explicit maintainer decision for each. Do not accept them unchanged merely because their supporting files have been on main since PR #433.

Audit result — 2026-07-18

ADR	What conforms	Material drift	Recommended disposition
0008 — Branching	Live next branches exist exactly for src, wiki, zi, zsh-lint, and zsh-eza, matching the canonical table.	Every audited GitHub default branch is main; the private catalog conflates default and development branches, lists next for four repos that do not have it, and misclassifies zi's release model. src and zd also publish on tag events beyond the stated boundary.	Reconcile catalog terminology/data and decide the tag-triggered deploy exceptions before acceptance.
0009 — Testing/CI	Concrete build, lint, test, and reusable-workflow evidence exists across the classes.	It references superseded ADR 0004; testing instructions overstate commit enforcement; promised SAST/release gates and development-branch validation are not uniformly live; .github has no self-running Trunk/Markdown gate; corrected Zi controls remain on next, not main.	Treat as target policy with explicit rollout gaps, or defer acceptance until the selected gates are implemented.
0010 — Security IR	The ADR and runbook agree on GHSA tracking, SLA/severity targets, disclosure, and post-incident review; ss-o is the sole listed maintainer and therefore the current default owner.	SECURITY.md does not route reporters to GHSA; escalation to “another org maintainer” has no executable backup; the runbook suggests moving a published tag; private-reporting/security settings are not visible through current tools.	Reconcile intake and escalation, remove tag retargeting, and confirm settings/SLA before acceptance.

ADR 0008 evidence and patch boundary

• The five-repository next set in the ADR is live-accurate; the other six audited repositories have no next.
• All 11 audited repositories use GitHub main as the default branch. The private workspace/repos.yml field named default_branch therefore has the wrong name or wrong values.
• The impossible catalog entries are zd, packaged zsh, z-a-meta-plugins, and zsh-fancy-completions, each recorded as next despite having no such branch.
• The catalog records zi as tag-driven, while accepted ADR 0007 classifies it as git-consumed/validation-only.
• Root guidance still universally says to branch from next; ADR 0008 already identifies that as an acceptance-time correction.
• src and zd have semantic-tag publication triggers that need an explicit exception or removal decision.

The private catalog/root-guidance correction must be a separate meta-workspace change from the public ADR PR.

ADR 0009 evidence and patch boundary

• Replace superseded ADR 0004 with accepted ADR 0012 for dependency ownership; do not imply ADR 0012 also governs secret scanning.
• Make .github/instructions/testing.instructions.md match the ADR's target-state wording. Concrete commit/PR-title enforcement was found on zi@next, not uniformly across the audited repositories.
• zsh-lint runs Go test/vet but has no CodeQL/gosec on main; its tag release does not run the suite.
• zunit has native/scheduled suites, but its release workflow does not invoke them.
• Packaged zsh has manifest/Trunk linting but no defined functional release gate.
• src@next validation workflows still filter events to main.
• The organization repository exposes reusable Trunk but does not call it for its own Markdown/workflow changes.
• zi@main retains workflow-convention violations while the corrected workflows and zd integration remain on next.
• Required-check/ruleset state is unverified and must not be inferred from workflow files.

ADR 0010 evidence and patch boundary

• Update .github/SECURITY.md to route reporters to a repository Security Advisory first, with the organization contact as fallback.
• Replace “another org maintainer” with a named, executable backup/escalation route before promising it.
• Remove “move a tag”; use withdrawal/deprecation, artifact revocation where available, and a new patched tag.
• Confirm private vulnerability reporting and repository security settings through authenticated administration before claiming live conformance.

Maintainer decisions requested

1. Accept ADR 0008 after factual reconciliation, or amend its branch/publication policy.
2. Decide whether GitHub defaults remain main while next is strictly the development/integration branch.
3. Decide whether src/zd tag publication is an accepted exception.
4. Decide whether ADR 0009 may be accepted now as target policy with owned rollout gaps, or only after implementation.
5. Define “full functional suite” for packaged zsh and the release-gate requirement for zunit.
6. Confirm the 3/5-business-day and 7/30/90-day security targets and designate a real backup incident route.
7. Accept, reject, or supersede each ADR with a named decider and decision date.

Checklist

• Compare ADR 0008 with live branch models, publication triggers, and the private catalog.
• Compare ADR 0009 with current workflows, reusable callers, release gates, SAST, and enforcement claims.
• Compare ADR 0010 with reporter intake, runbook behavior, maintainer ownership, and visible settings.
• Separate factual reconciliation from maintainer policy decisions.
• Prepare a public factual-reconciliation PR while keeping all three ADRs PROPOSED.
• Prepare the separate private catalog/schema/root-guidance correction.
• Create owning-repository implementation follow-ups only after the target-policy decision makes their acceptance criteria authoritative.
• Verify links/Markdown/Trunk for the public ADR draft.
• Obtain the maintainer decision and record named deciders/dates.
• Synchronize the public PR/review state with Linear ZSH-16.
• Synchronize the final maintainer disposition with Linear ZSH-16.

Public factual-reconciliation PR — 2026-07-18

Draft PR #457 publishes commit 12160ffc and changes exactly ADRs 0008–0010. All three remain PROPOSED with Deciders: TBD; no supporting policy, runbook, workflow, security setting, or private catalog was changed.

Focused Markdownlint and Prettier checks passed for all three files, git diff --check passed for the branch range, and Lychee checked 6 links with 0 errors. Independent specification-compliance and documentation-quality reviews both passed with no findings. GitHub Actions CodeQL Advanced run 148 completed successfully for commit 12160ffc. The PR remains draft pending the maintainer decisions above.

Boundaries

Per runbooks/adr.md, only an organization maintainer may change a proposed ADR to accepted. This issue records evidence and decisions; it does not pre-decide acceptance.

Triage

Suggested item type: Task
Suggested priority: Medium
Suggested effort: Medium
Suggested status: In review

Linear mirror: ZSH-16

[ss-o]

Maintainer decision packet — 2026-07-19

State pin:

• Draft PR docs(adr): reconcile proposed governance policies #457 is open, clean/mergeable, and changes only ADRs 0008–0010 at head 12160ffcd30f2b2f9b0f799b628db6021ef169ea.
• The exact-head audit found successful CodeQL/Lychee checks and no requested reviewers, reviews, comments, or review threads.
• All three ADRs remain PROPOSED; supporting policy, workflows, security settings, and the private catalog were not changed.

ADR 0008 — branch and publication policy

• 8A — Accept the per-repository branch table and keep GitHub defaults on main; document the live src/zd semantic-tag triggers as explicit class-1 compatibility publication paths (recommended). This matches live behavior without silently deleting a publication path.
• 8B — Accept the branch table but require main-only continuous deployment. Create owning-repository follow-ups to remove the tag triggers before claiming conformance.
• 8C — Amend/reject the per-repository table. Supply the desired development branch/model for each affected repository.

ADR 0009 — target CI policy

• 9A — Accept now as target policy with owned rollout gaps (recommended). The ADR explicitly distinguishes target state from live controls; acceptance gives follow-up issues authoritative criteria.
• 9B — Keep proposed until every selected control is live. Avoids accepted-policy drift, but leaves rollout criteria non-authoritative.
• 9C — Weaken the ADR to current live minimums. Lowest rollout cost, but preserves the uneven CI state the ADR is intended to resolve.

If selecting 9A, recommended definitions are:

• 9Z1: packaged zsh release gate = metadata/manifest validation plus a clean disposable install and startup/version smoke test on the exact tag commit. Metadata-only validation is not a “functional suite.”
• 9U1: zunit release workflow must run its native suite on the exact tag commit before publication; prior branch checks alone do not prove the released commit.
• 9R1: required checks, development-branch triggers, SAST, and release gates are verified repository-by-repository through owning issues; no workflow file is treated as proof of an enabled ruleset.

ADR 0010 — security response

• 10S1 — Confirm the proposed 3/5-business-day acknowledgement/triage targets and 7/30/90-day remediation targets (recommended).
• 10S2 — Amend them. Supply exact replacement targets.
• 10B1 — Name and permission-check a real backup incident contact. Required before the current proposal can honestly claim operational escalation.
• 10B2 — Amend to an explicit single-maintainer model with no backup escalation promise. Transparent, but increases continuity risk.
• 10D1 — Keep ADR 0010 proposed until 10B1/10B2 is decided and private-reporting, notification, and release-immutability settings are authenticated and verified (recommended).
• 10D2 — Accept it as target policy with those items recorded as rollout gaps. This requires amending the current “before acceptance” language first.

Recommended coherent selection:

8A / 9A + 9Z1 + 9U1 + 9R1 / 10S1 + 10D1

This accepts the two decisions already supported by public evidence while refusing to imply that an unverified security escalation path exists.

Copy-ready record:

ADR 0008: 8A — ACCEPTED
ADR 0009: 9A + 9Z1 + 9U1 + 9R1 — ACCEPTED as target policy
ADR 0010: 10S1 + 10D1 — retain PROPOSED pending backup-route and
administrative-setting verification
Decision date: <YYYY-MM-DD>
Decider: ss-o
Authorization: update PR #457 to record exactly these dispositions, re-run all
document checks, mark ready, and merge only if the accepted head remains green.
Create private-catalog and owning-repository rollout issues after merge.

After explicit approval, it becomes safe to update ADR 0008/0009 metadata and wording for the selected exceptions/definitions, add explicit ADR 0010 objections while retaining PROPOSED, verify PR #457 again, and create the separate private-catalog and owning-repository rollout items. It does not authorize any Cloudflare/GitHub security-setting mutation or naming a backup person by assumption.

Reply with the recommended code set plus approve patch and merge, or provide amended codes/text and, if choosing 10B1, the backup contact to permission-check.