Repository navigation
chore: align repository governance and release policy #70
Description
Context
A repository audit on 2026-08-14 found that zpmod is active and its default-branch CI is green, but its branch model, release class, repository settings, work queue, and automation are not aligned with current Z-Shell policy.
Maintainer decision: classify zpmod as a class 2 versioned compiled tool/package and use trunk-based development on main. Record the corresponding organization-policy update separately in z-shell/.github.
Required work
- Add
zpmodto the canonical release and branch-model documentation as class 2, trunk onmain. - Replace classic
mainprotection and the disabled ruleset with one active class-2 ruleset that requires pull requests and class-appropriate checks, blocks deletion and force-pushes, and enables Copilot review. - Change default Actions workflow permissions from write to read.
- Stop production Pages deployments from the unprotected
developbranch; publish only from the accepted publication branch. - Restore a root
README.mdand a GitHub-detectable rootLICENSE, preserving applicable upstream notices. - Reconcile the PR Introduces significant updates to streamline project management and module codebase #61 review-boundary divergence: PR Introduces significant updates to streamline project management and module codebase #61 was merged as-is, and its residual risks were decomposed into focused sub-issues fix(security): resolve filesystem creation and TOCTOU alerts #93 through chore(deps): prove Renovate processing and routine-update ownership #98.
- Fix issue [bug]: (eval):ZIModule_:1: can't write zwc file: /proc/self/fd/15.zwc #31 by skipping ZWC compilation for non-regular sources and add a process-substitution regression test.
- Resolve issue [docs]: How to install the traditional way? #28 through a focused, package-manager-friendly system-install path and documentation update.
- Close obsolete PR build(deps): bump actions/checkout from 5.0.0 to 6.0.2 #68.
- Prove Renovate processing and routine-update ownership under chore(deps): prove Renovate processing and routine-update ownership #98 after chore(deps): migrate repositories to hybrid Renovate ownership .github#452 clears.
- Reconcile
v2.0.0: it is superseded by immutable published releases from reviewedmain, currently v2.0.6. - Pin every workflow action to a full commit SHA, remove emoji from workflow/job names, apply least-privilege permissions, and add effective concurrency.
- Disable orphaned workflow records that no longer exist on
mainordevelop. - Migrate open items from legacy labels and remove unused legacy labels after confirming no remaining references.
Original audit evidence (2026-08-14)
- PR Introduces significant updates to streamline project management and module codebase #61: 159 commits, 285 changed files, +13,820/-137,742; automated review cannot process the diff and CodeQL reported mutable action references.
main: pull requests required, but force-pushes allowed and no required status checks.develop: unprotected and permitted to deploy to thegithub-pagesenvironment.- Repository Actions defaults: write token permissions and no enforced SHA pinning.
- Open queue: issues [docs]: How to install the traditional way? #28 and [bug]: (eval):ZIModule_:1: can't write zwc file: /proc/self/fd/15.zwc #31; pull requests Introduces significant updates to streamline project management and module codebase #61 and build(deps): bump actions/checkout from 5.0.0 to 6.0.2 #68.
- Security baseline: dependency graph, Dependabot security updates, secret scanning, and push protection are enabled; no open Dependabot or secret-scanning alerts were found.
Current blocker
#98 is the only open native sub-issue. Live verification on 2026-08-27 found no repository Renovate configuration, no current Dependency Dashboard or configuration-warning issue, no Renovate branch or recent Renovate-authored commit, and only historical onboarding PR #1 from 2022. Dependabot security updates remain enabled, with zero current Dependabot alerts.
Organization rollout owner z-shell/.github#452 remains open. Keep this parent Blocked until #98 records current hosted-processing evidence, proves non-overlapping routine-update ownership, and closes as completed or is explicitly descoped.
Acceptance criteria
- The default branch and release path match the recorded class-2 trunk-on-
maindecision. - Required checks gate merges and the public Pages/release surfaces consume reviewed
maincommits only. - All open issues and pull requests have an explicit current disposition.
- Repository files, labels, workflows, and dependency automation match canonical organization policy.
Activity
ss-o commentedon Aug 22, 2026
Status check on the checklist (audited 2026-08-22):
Done
main(org ADR-0008).mainnow has an active ruleset: requires PRs, required status checks, blocks deletion and force-push, Copilot code review enabled.read.README.mdandLICENSErestored (docs: restore root README and LICENSE #71, docs: restore root README and LICENSE #88).v2.0.0superseded by a working, fully publishedv2.0.1release line.main/develop(codeql.yml,code-quality.yml,performance-monitoring.yml,test-quality.yml) are disabled.Still outstanding
develop, anddevelopis still unprotected. Publication needs to move to the accepted branch/tag path before this item is done.@v4,@v3, ...), not full commit SHAs.cleanup-workflows.ymlstill has an emoji in its name.bug :lady_beetle:,bug 🐛,stale 👻, ...) remain alongside thetype:/area:taxonomy and haven't been migrated or removed.New finding, not in the original checklist
ci.ymlanddocs.ymlare bothdisabled_manuallyat the repo level, but themainruleset's required status checks still referenceci.ymljob names (Lint scripts on Linux,Build standalone module on Linux/macOS, etc.). Those checks can never be produced while the workflow stays disabled. Recent merges (docs: restore root README and LICENSE #88, fix: skip ZWC compilation for non-regular sources #89) only went through because write/maintain/admin roles have an unconditional ruleset bypass. Recommend either re-enablingci.ymlor removing its job names fromrequired_status_checksso the requirement matches what actually runs.Keeping this open — real work remains.
fix(ci): pin ci and docs workflow actions to full commit SHAs
chore(release): exclude bot authors from auto-generated notes
ss-o commentedon Aug 22, 2026
Update (2026-08-22), following #88, #89, #91 and the pending #90.
Newly completed
develop.ci.ymlanddocs.ymlnow trigger onmainonly (chore(ci): stop triggering CI and Pages from develop #91), and the post-merge run onmaincompleted withBuild docs (container): successandDeploy to Pages: success, so the public surface is served from a reviewedmaincommit.developis retired and deleted. Before deletion it was verified to hold zero unique files againstmain(compare/main...developreportedunique_files: 0); its 169 "ahead" commits were duplicated pre-CMake history already superseded onmain. Recovery ref, if ever needed:68e0a88beab8398c86c0bef3dde475ca9cd80345.developtomain.ci.ymlanddocs.ymlwere the remaining offenders (chore(ci): stop triggering CI and Pages from develop #91);release.ymlandcleanup-workflows.ymlwere already pinned.ci.ymlanddocs.ymlare re-enabled. They had beendisabled_manuallybecause every run failed atSet up jobunder the repository's allowed-actions policy, which is the same unpinned-action problem fixed above.Corrections to the earlier status comment
mainruleset named eight contexts that no workflow produced (Lint scripts on Linux,Build standalone module on Linux, and similar). A commit status query against a PR head returnedstate: pendingwith an emptystatusesarray, so those contexts sat unreported forever and every merge depended on the write/maintain/admin bypass. The list is now set to the job names actually emitted:Native Tests (ubuntu-latest),Native Tests (macos-latest),Docker Tests (minimal),Docker Tests (full-dev),Smoke Tests,Build docs (container),Analyze (actions),Analyze (c-cpp).Deploy to Pagesis deliberately excluded because it is conditional and skips on pull requests. All other rules (deletion, linear history, Copilot review, non-fast-forward, pull request) are unchanged.docs.ymlhad a second latent defect: thedeployjob carried no event guard, so it attempted a Pages deployment on every pull request and was rejected outright by thegithub-pagesenvironment branch policy, which permitsmainonly. It is now gated topushonmain.Still outstanding
cleanup-workflows.ymlstill carries an emoji in its workflow name.type:/area:taxonomy.3 remaining items
ss-o commentedon Aug 27, 2026
Legacy-label migration archive — before write
Live all-state usage and archived definitions:
chore 🔧c5def5type:maintenance, remove legacyrefactor ♻️5319e7type:maintenance, remove legacybug 🐛d73a4atype:bug, remove legacyci :robot:5319e7area:ci, remove legacybug :lady_beetle:B60205type:maintenancewithtype:bug, remove legacystale 👻fffffftype:questionNo open issue or pull request uses any of these labels, and no repository configuration references them. Each definition will be deleted only after its all-state usage is re-read as zero. This comment is the restoration archive required by the label-maintenance runbook.
ss-o commentedon Aug 27, 2026
Legacy-label reconciliation completed and verified: all six archived variants were migrated off their closed records, each definition was deleted only after all-state usage reached zero, and the canonical
labels-sync.rb --repo z-shell/zpmod --jsondry run now reportsrepos_with_drift: 0with no missing, updated, legacy, or unknown labels.ss-o commentedon Aug 27, 2026
Parent reconciliation - 2026-08-27
Live verification confirms that the original governance remediation is complete except for Renovate ownership proof:
zpmodas class 2, trunk onmainmainruleset requires pull requests, eight real status checks, linear history, deletion and non-fast-forward protection, review-thread resolution, and Copilot review; classic protection is absentmain, anddevelopis absentmain#98 is the sole remaining sub-issue. It remains Blocked by open organization rollout z-shell/.github#452, and current repository evidence still does not prove hosted Renovate processing. Dependabot security updates remain enabled with zero alerts.
Parent disposition: keep #70 open, add
status:blocked, and move its Z-shell Delivery status to Blocked. The sole next action is to resume #98 only after hosted-processing or equivalent approved validation evidence becomes available.ss-o commentedon Oct 3, 2026
The remaining governance deliverable is Renovate processing under #98. The issue already specifies: "Keep this parent Blocked until #98 records current hosted-processing evidence, proves non-overlapping routine-update ownership, and closes as completed or is explicitly descoped."
#98 remains open, and its implementation PR #138 still needs its review of record and subsequent hosted-processing evidence. Project status is Blocked with the matching status:blocked label and a native blocked-by link to #98. The next action is to complete #98's remaining acceptance criteria; the other governance work is already recorded as complete.
ss-o commentedon Oct 15, 2026
The remaining Renovate deliverable under #98 is complete: Dashboard #140 and routine update PRs demonstrate hosted processing, strict validation passes on the unchanged merged configuration, routine-update ownership does not overlap, and Dependabot retains security remediation. The organization blocker z-shell/.github#452 is closed.
All required sub-issues #93 through #98 are complete. Current main 5d5c798 retains the recorded class 2, trunk-on-main model; required checks, pull-request and thread-resolution gates, read-only workflow defaults, and immutable v2.0.6 publication remain in place. Main CI passes native Linux/macOS, Docker and smoke tests. Docs builds and deploys Pages from main. The organization routing and approved review-skill content check passes.
The remaining open queue is routine dependency maintenance, with these dispositions: #141 waits for its minimum-release-age status and review; #147 needs a separate Ubuntu 26.04 compatibility investigation for its failing Docker and smoke checks; #157 needs its failing Trunk check and minimum-release-age status resolved before review. These updates remain open under the Dependency Dashboard; they are not outstanding deliverables from the original governance remediation. Broader Renovate coverage remains open under z-shell/.github#613.