Repository navigation
chore: audit and trim repository metadata #374
Description
Goal
Keep repository metadata only where it provides demonstrated value to Zi. Remove editor-specific or dead configuration, reduce copied template content to Zi's actual languages and workflows, and correct retained controls that are stale or ineffective.
This audit covers next at f3e68af on 2026-08-15, compares the default main branch, checks live workflow/ruleset state, and reviews every tracked repository-control file. It complements #360, which owns repository settings and required-check alignment.
Findings and disposition
| File | Disposition | Evidence and suggested solution |
|---|---|---|
.editorconfig |
Keep, rewrite minimally | The 2-space, LF, final-newline, and trailing-whitespace rules fit Zi. The file is 359 lines, with roughly 300 lines of .NET policy plus sections for languages absent from the repository. Replace it with a small global section plus only Markdown and Zsh/shell exceptions. |
.gitattributes |
Keep, rewrite minimally | LF normalization and binary marking protect a shell-first repository. The current 82-line generic template contains many unused document and platform patterns. Keep text=auto, LF for shell/Zsh, and the repository's actual binary types. Decide explicitly whether release archives should exclude metadata rather than retaining the current partial export-ignore list. |
.gitignore |
Keep, rewrite minimally | Zi creates .zwc, cache/history, test, editor, and Trunk artifacts. The current 129 lines duplicate *.zwc, *.o, *.a, *.so, and *.dll, include broad rules such as *.txt, test/, other, TODO*, and site*/, and carry a generic C build template despite no tracked C source. Keep only artifacts Zi or its supported development flow actually creates. |
.vscode/settings.json |
Remove | It is tracked while .gitignore excludes .vscode/*; it depends on unrecorded extensions; conventionalCommits.scopes contains commit types rather than scopes; and *za-* associations are unrelated to Zi. No .vscode/extensions.json establishes a reproducible workspace. Keep .vscode/ ignored for local preferences. |
.trunk/.gitignore |
Keep | Required to prevent Trunk caches, logs, tools, and generated output from entering Git. |
.trunk/trunk.yaml |
Keep, streamline and upgrade | The live Trunk workflow succeeds and provides action, Markdown, YAML, formatting, image, and secret checks. However, a full local run found 4 existing MD045 issues, every Gitleaks invocation failed because the pinned binary was unavailable, and trunk upgrade --dry-run reports CLI 1.24.0 -> 1.25.0, plugin v1.7.0 -> v1.11.0, and 5 stale linters. Review each enabled linter against Zi's files, choose one justified local secret scanner rather than overlapping tools, remove unnecessary runtimes/actions, then require a clean trunk check --all. |
.trunk/config/.markdownlint.yaml |
Keep, tighten | Markdown is tracked and linted, but the config disables most formatting rules. Retain only evidence-backed exceptions and fix the 4 current missing-alt-text findings. |
.trunk/config/.yamllint.yaml |
Remove | yamllint is explicitly disabled in trunk.yaml, so this file has no effect. Re-add it only if the linter is enabled. |
.trunk/config/svgo.config.js |
Keep only with SVGO | Zi tracks docs/images/logo.svg, so the config is relevant while SVGO remains enabled. Remove both together if image optimization is dropped from the focused linter set. |
AGENTS.md |
Keep | This is the repository's concise, runtime-neutral guidance and records Zi's next branch model and Zsh-first requirements. |
.github/copilot-instructions.md |
Keep | This is the required thin Copilot adapter to AGENTS.md; it avoids duplicating policy. |
.github/CODEOWNERS |
Keep | Both live main and next rulesets require code-owner review, so this file has enforced value. The core/runtime and governance ownership split is relevant. |
.github/PULL_REQUEST_TEMPLATE.md |
Keep, fix | The branch and validation checklist is useful. Replace the claim that the Copilot adapter contains the "full guidelines" with a link to AGENTS.md, and keep checks aligned with actual required status checks from #360. |
.github/dependabot.yml |
Remove only at approved Stage 2 | It correctly targets next, but routine GitHub Actions updates are moving to Renovate in #352 and z-shell/.github#452. Keep it during the gated Stage 1, then remove routine Dependabot configuration atomically after live Renovate and security ownership are verified. |
.github/ISSUE_TEMPLATE/config.yml |
Keep, verify links | Issue routing is useful. Wiki, Discussions, Matrix, and Crowdin resolved during the audit; the Slack endpoint returned HTTP 403 and needs a manual invite check. Remove any channel that is no longer maintained. |
.github/ISSUE_TEMPLATE/01_bug_report.yml |
Keep, repair | Configured labels bug 🐞 and triage 📑 do not exist; both required policy links return 404; the self-service text says "documentation request"; and Zsh examples are rendered as Bash. Use canonical labels and valid organization policy links, then remove copied fields that do not help reproduce a Zi bug. |
.github/ISSUE_TEMPLATE/02_feature_request.yml |
Keep, repair | Label feature-request 💡 does not exist, both required policy links return 404, and self-service text incorrectly says "documentation request". Use canonical labels and concise Zi-specific questions. |
.github/ISSUE_TEMPLATE/03_codebase_improvement.yml |
Keep, repair | enhancement ✨ exists, but both required policy links return 404 and self-service text incorrectly says "documentation request". This is the correct template category for repository-maintenance proposals after repair. |
.github/ISSUE_TEMPLATE/04_documentation.yml |
Keep, repair | Label documentation 📝 does not exist and both required policy links return 404. Keep the useful area selector, switch to canonical labels/links, and remove unnecessary contact collection. |
.github/workflows/codeql.yml |
Keep, fix permissions/pins | Actions scanning is useful for the repository's substantial workflow surface and recent runs pass. Job-level permissions replace the top-level map, so add contents: read to the analyze job alongside security-events: write; refresh pinned action SHAs/comments. |
.github/workflows/commit-lint.yml |
Keep | It enforces Conventional Commits, PR titles, branch naming, and the no-coauthor-trailer policy required by organization guidance. Keep the full-SHA pin current and verify the strict branch rule still permits the intended contribution model. |
.github/workflows/main-branch-guard.yml |
Keep | It is the only required status check in the live main ruleset and safely uses pull_request_target without checking out or executing contributor code. |
.github/workflows/trunk-check.yml |
Keep, fix | Trunk provides demonstrated CI value. Replace top-level permissions: read-all with least privilege, use a workflow-qualified concurrency group instead of github.run_id on pushes, add the action version comment, and use imperative step names. The current push mode checks only modified files, so periodic or pre-merge full-repository validation must be explicit if desired. |
.github/workflows/zd-integration.yml |
Keep | This is the functional Zi integration test for runtime changes and recent runs pass. Keep the reusable workflow SHA pinned and refreshed deliberately. |
.github/workflows/zsh-n.yml |
Keep, fix | zsh -n and zcompile are the essential validation for a git-consumed Zsh project. Remove the dead workflow_run dependency on ⭕ Trunk, which no longer matches Trunk Code Quality and is redundant with direct push/PR triggers. Review repeated package installation cost separately. |
Default-branch drift
main still contains .github/labeler.yml plus labeler.yml, lock.yml, pr-labels.yml, rebase.yml, stale.yml, and legacy zunit.yml workflows. They are already deleted on next, but GitHub still lists the default-branch workflows, including disabled or obsolete entries. Do not restore them. Preserve those deletions when next is promoted to main.
Proposed implementation order
- Remove
.vscode/settings.jsonand dead.trunk/config/.yamllint.yaml. - Replace
.editorconfig,.gitattributes, and.gitignorewith Zi-specific minimal versions. - Upgrade and prune Trunk, fix the existing full-run findings, and prove
trunk check --allis clean. - Repair issue forms, canonical labels, links, copy, and the PR-template guidance link.
- Apply the targeted workflow fixes while retaining syntax, integration, policy, and security coverage.
- Coordinate required checks with Audit and align zi next-branch repository settings #360 and Dependabot removal with chore(deps): align dependency automation config #352 and chore(deps): migrate repositories to hybrid Renovate ownership .github#452.
- Confirm the default branch no longer exposes the legacy workflows after the normal
nexttomainpromotion.
Acceptance criteria
- Every retained metadata rule matches a tracked Zi file, generated Zi artifact, active GitHub feature, or documented contributor workflow.
-
.vscode/settings.jsonand disabled-linter configuration are removed. - The three root dotfiles are concise and contain no broad rules that can hide likely source or documentation files.
- All issue forms use existing canonical labels and valid links, with Zi-specific wording.
-
trunk check --all, workflow syntax checks,zsh -n, andzcompilepass after cleanup. - External actions remain pinned to full commit SHAs with version comments, permissions are least-privilege, and concurrency groups cannot collide across workflows.
- Stage 2 dependency-manager cleanup follows the existing migration gate rather than removing Dependabot prematurely.
- Legacy default-branch workflow files remain deleted when
nextreachesmain.
Metadata
Metadata
Labels
Type
Projects
- Status
Activity
ss-o commentedon Aug 18, 2026
Resolved by #375, merged into
nexton 2026-08-15.This issue remained open because GitHub only closes issues automatically when a pull request merges into the default branch (
main). TheCloses #374keyword in anext-targeted pull request therefore has no effect. Closing manually perrunbooks/triage.mdStep 6.The work is on
next. Promotion tomainis tracked separately in #377.