ci: reference organization reusable workflows at main

[ss-o]

Closes #801.

Summary

• Accepted ADR-0042: callers reference the organization's reusable workflows (z-shell/.github/.github/workflows/*) at @main, so a change merged here reaches every caller without a pull request in each repository. Every other remote reference stays pinned to a full SHA with its release comment, including third-party actions and workflows and the organization's actions under z-shell/.github/actions/.
• Workflow contract (source knowledge/domains/ci/workflow-contract.md and generated .github/instructions/ci/workflow-contract.instructions.md): the pinning rules, called-workflow guidance and pre-merge checklist follow the ADR. Existing SHA pins of the shared workflows stay valid until each caller moves, and the default-branch rule from [bug]: commit-lint callers pinned to 64a427d end in a startup failure #774 still applies to them.
• Shared pinact template (templates/pinact/.pinact.yaml): adds an ignore_actions entry for an exact main ref on the shared workflows and keeps the full-SHA entry, so callers that copied the template still pass. pinact 4.1.1 matches both patterns against the whole name and ref.
• Organization Renovate preset (renovate-config.json): a package rule turns off digest pinning for z-shell/.github references whose ref is main. config:best-practices pins GitHub Actions references, and the Dependency Dashboard (Dependency Dashboard #790) already lists a pin update for the starter templates' main references; without the rule every caller extending the preset would get pin pull requests that undo the ADR. Release-tagged organization actions and existing SHA pins keep their updates. Its keys were checked against Renovate's published JSON schema; Renovate itself was not run.
• New-repository procedure (source knowledge/domains/governance/new-repository.md, generated runbooks/new-repository.md): it installs CI from the @main templates and then said to pin reusable-workflow references to SHAs; it now keeps the shared workflows at @main and pins everything else.
• knowledge/domains/agents/implementation-patterns.md (generated PATTERNS.md) follows the same rule and the renamed contract anchor.
• The ADR is declared in .github/instruction-surfaces.json and knowledge/repository-files.json; decisions/README.md and knowledge/domains/ci/repository-resources.md are regenerated (the latter's diff is one new row plus column realignment).
• automation/ci/test_validate_zsh_standard_policy.py: the frozen consumer golden hashes the visible text of PATTERNS.md, so it is refreshed. Only that file's visible text changed; the scripting instruction's rule blocks, parsed rules and documentation registry are identical, and the previous digest reproduces on the base revision.

Not changed: the starter templates (already @main), any caller repository, repo-settings-audit.rb --workflow-pins (it only matches SHA pins), and ADR-0009 (it defers workflow conventions to the contract).

Impact review

Answers to the instruction update questions:

1. Classification: shared organization policy (workflow contract and implementation patterns) plus a shared configuration template; no enforcement change.
2. Consumers: every repository that reads the generated workflow contract or PATTERNS.md, and every caller that copies the pinact template. The change-impact report lists the policy files as shared-policy review and the template as needing a caller inventory: no caller changes here; callers keep their SHA pins until their own reviewed change.
3. Canonical owner: unchanged. knowledge/domains/ci/workflow-contract.md remains the editable source; the ADR records the decision.
4. Duplicates or contradictions: implementation-patterns.md and the new-repository procedure repeated the old rule, and the Renovate preset would have pinned @main references; all three are updated in this change. ADR-0009 and the CI workflow author and reviewer roles defer to the contract and stay accurate for actions.
5. Manifest routes: one new advisory decision surface (decision-0042); no route changes.
6. Mandatory rule delivery: the contract is delivered through the existing generated instructions and routing, without relying on an optional hook or skill.
7. Generated output and limits: knowledge-delivery.py --check passes for 57 consumers, and the policy validators below pass.

Verification

• python3 automation/knowledge/knowledge-delivery.py --check: 57 consumers checked.
• python3 automation/knowledge/knowledge-coverage.py: 366 files covered.
• python3 automation/governance/decision-records.py --check: passed.
• python3 automation/agents/validate-agent-policy.py: passed.
• python3 automation/agents/org-routing.py validate and verify-approved (with the z-shell/agent-skills source root): passed.
• python3 -m unittest automation/agents/test_validate_agent_policy.py (99 tests) and automation/agents/test_org_routing.py (77 tests): OK.
• Every step of the Validate Agent Instructions job, run locally on the head, including automation/ci/test_validate_zsh_standard_policy.py (111 tests) and validate-zsh-standard-policy.py: passed.
• trunk check --no-fix on the changed files: no issues.
• Not run: the private control-workspace validators, which run when the meta-workspace advances its gitlink.

Agent handoff

No handoff needed.

[ss-o]

Fallback review under ADR-0026: Copilot request not registered on c002459

Findings

No actionable findings on the reviewed head.

Two findings from this review were fixed before it was posted:

• IMPORTANT, CI pinning (fixed in 434a639): renovate-config.json extends config:best-practices, which pins GitHub Actions references to digests. The Dependency Dashboard (#790) already listed a pin update for the starter templates' z-shell/.github main references, so every caller extending the preset would have received pull requests undoing ADR-0042. A package rule now turns off digest pinning for z-shell/.github references whose current ref is main.
• IMPORTANT, contradicting guidance (fixed in c002459): knowledge/domains/governance/new-repository.md:141 installed CI from the @main templates and then said to pin reusable-workflow references to SHAs. It now follows ADR-0042.

Scope: complete diff of d8edc83...c002459 (four commits), against issue #801. Copilot was requested once on 7a73dbb at 12:35:28Z; after two minutes the timeline held only the CODEOWNERS tsc request and no Copilot review_requested event, so the request did not register (cause unconfirmed). Later commits changed the test golden, the Renovate preset and the new-repository guidance; no second request was made.

Note

This is a maintainer-elected self-review, not an independent review or approval to merge.

Validation

• Passed on c002459: all 12 hosted checks, including Validate Agent Instructions, Org Routing, Validate Commits, Validate Issue Link and links-check.
• Passed locally on c002459: every step of the Validate Agent Instructions job (policy, delivery, coverage, routing, decision-record and Zsh standard suites and validators); org-routing.py verify-approved with the z-shell/agent-skills source root; trunk check --no-fix on the changed files.
• Skipped or unavailable: Renovate was not run against the new rule; its keys (matchManagers, matchPackageNames, matchCurrentValue, pinDigests) were checked against Renovate's published JSON schema, so the rule's effect is confirmed on the next scheduled Renovate run, not here. pinact was not run; the template follows the pinact 4.1.1 documentation that name and ref must match exactly. Private control-workspace validators are outside this repository.

Checklist verdicts and supporting evidence

• Policy consistency: pass. The contract source and its generated instructions, implementation-patterns.md and PATTERNS.md, the new-repository procedure, ADR-0042 and the Renovate preset state one rule: organization reusable workflows at @main, every other remote reference SHA-pinned, existing SHA pins valid. A repository search finds no remaining statement that organization reusable workflows must be SHA-pinned.
• Scope boundary: pass. Organization actions under z-shell/.github/actions/ stay pinned (the rclone template keeps actions/rclone@6443afd # v1.0.0), and the Renovate rule matches only a current ref of main, so tagged actions and existing SHA pins keep their updates.
• pinact template: pass. Two ignore_actions entries for z-shell/\.github/\.github/workflows/.*: ref main and the existing full-SHA pattern, so callers that copied the template keep passing. The usage link targets the renamed heading #pinact-exception-for-organization-reusable-workflows, which exists in the generated instructions.
• Audit tooling: pass. repo-settings-audit.rb --workflow-pins only matches 40-hex SHA refs, so @main callers are not reported; its default-branch check still applies to remaining SHA pins, as the contract says.
• Generated outputs: pass. Delivery, coverage and the decisions index were regenerated by their tools; the repository-resources.md diff is one new row plus column realignment. The Zsh standard consumer golden changed only because PATTERNS.md's visible text changed: the scripting instruction's rule blocks, parsed rules and documentation registry are identical, and the previous digest reproduces on the base revision.
• ADR: pass. ADR-0042 is ACCEPTED with an acceptance record, declared in .github/instruction-surfaces.json and knowledge/repository-files.json, and listed in the generated index. It states the accepted risk (a defect on main reaches every caller at once) and the controls (review on this repository, an optional default-branch SHA pin for a caller that must freeze).
• Text policy: pass. No em dash, tool credit or private reference in the added text.

Follow-up

Moving existing callers from SHA pins to @main is per-repository work outside this pull request.