docs(release): draft v4 loader & layout overhaul proposal#258
Merged
Conversation
Add V4-PROPOSAL.md, an RFC for the first major (v4.0.0) bundling three breaking changes that all ride the loader + bootstrap symlink contracts: numbered load-order with drop-in fragment slots, an XDG state/cache/data split, and opt-in CORE_PROFILE module profiles. Proposal-first: the doc carries the design, a drafted CHANGELOG block (to paste when the work lands), and the per-OS-repo migration runbook — no modules are renamed and no live contract is touched yet. Allowlist the doc in scripts/audit-core.sh (repo-meta, not shipped Core) so the manifest<->filesystem audit stays green. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XgSG8AousYiEznFzv2mEBp
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a proposal for a coordinated v4 loader and layout overhaul without changing runtime behavior.
Changes:
- Proposes numbered zsh fragments, XDG runtime storage, and module profiles.
- Adds migration and release-note drafts.
- Allowlists the proposal as repository metadata.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 6 comments.
| File | Description |
|---|---|
V4-PROPOSAL.md |
Documents the proposed v4 architecture and migration. |
scripts/audit-core.sh |
Allowlists the new proposal document. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+79
to
+82
| | `00`–`69` | Core | `00-tools`, `10-options`, `25-git`, `45-plugins`, `60-update` | | ||
| | `70`–`84` | OS-native layer | `80-os-fedora.zsh` | | ||
| | `85`–`94` | Role layer | `85-offensive.zsh` (Kali), `85-defense.zsh` (Defense) | | ||
| | `95`–`99` | Host-local | `99-local.zsh` | |
Comment on lines
+176
to
+178
| | `minimal` | `00`–`30` (tools, ui, options, history, aliases, git, functions) | fast headless / container shell | | ||
| | `standard` | `minimal` + `35`–`50` (fzf, bindings, plugins, op) | interactive workstation without the maintenance surface | | ||
| | `full` (default) | `standard` + `55`–`60` (maint, update) | the current everything-loads behaviour | |
Comment on lines
+164
to
+167
| Every module always loads. The only knob is `DOTFILES_OFFLINE`. A headless | ||
| server or minimal container pays for atuin, `plugins.zsh` (carapace/fzf-tab), | ||
| the `update.zsh` nudge, and (via the editor stack) an increasingly heavy Neovim | ||
| payload — whether it wants them or not. |
Comment on lines
+260
to
+262
| - **`CORE_PROFILE` (`minimal` / `standard` / `full`).** Selects which module bands | ||
| load, so a headless box can skip the interactive- and editor-heavy stages. | ||
| Defaults to `full` (today's behaviour). |
Comment on lines
+200
to
+201
| Skip any gate and the host stays on `v3.x`. Roll back per OS by re-pulling | ||
| `v3.9.0` in just that repo. |
Comment on lines
+205
to
+206
| For each repo in `scripts/os-repos.txt` (plus the Role repos), after `v4.0.0` is | ||
| tagged: |
…s, rollback Resolve the CI markdownlint failure (MD060 table-column-style on the band table: switch it to minimal-delimiter style) and address review feedback: - Bands are recommended default homes, not hard walls — any layer may use a Core numeric gap for mid-chain insertion; define the sort + tiebreak so the §3.1 "insert between aliases and git" claim is actually achievable. - CORE_PROFILE gates only Core-owned fragments (00-69); OS/Role/local (70-99) always load, so a profile can never skip essential OS setup or 99-local.zsh. - Drop the overclaim that CORE_PROFILE skips a Neovim/"editor" payload: nvim is provisioned by blib_link_core at bootstrap and loaded by nvim, not any zsh stage. Scope the rationale to the interactive zsh stages; add an open question on optionally extending profiles to bootstrap wiring. - Correct the per-OS rollback: revert the v4-adoption commit + re-bootstrap; a git subtree pull of an older tag does not reverse an already-merged tree. - os-repos.txt already includes both Role repos — drop the "plus the Role repos" wording. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XgSG8AousYiEznFzv2mEBp
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What & why
Core is at
3.9.0. This addsV4-PROPOSAL.md— a design RFC for the first major (v4.0.0). It is proposal-first (no modules renamed, no live contract touched), matching the repo's "report first, nothing vendored without a green audit" discipline. The doc bundles three breaking changes that all ride the same two contracts (zsh/loader.zsh+lib/bootstrap-lib.sh), so they belong in one coordinated major rather than three consecutive re-bootstraps:NN-prefixes; the loader globs-and-sorts fragments across the Core/OS/local layers, so OS/Role repos can inject between stages instead of only appending. Also aligns the zsh module structure with the PowerShell host layer'sNN-nameconvention (PARITY.md)..zwcwordcode, and plugins leave the symlinked config tree for$XDG_STATE/$XDG_CACHE/$XDG_DATA, finishing a migration the codebase already started unevenly (grounded withfile:linecitations).CORE_PROFILE(minimal/standard/full) — derives the fragment set so a headless box can skip the interactive- and editor-heavy stages.The doc carries the design, a drafted
## [v4.0.0]CHANGELOG block (to paste when the work lands, not now — the live CHANGELOG asserts shipped changes), and the per-OS-repo migration runbook.Is it actually Core?
core/, not symlinked)Contract & checks
core.manifestwas updated in the same change (N/A —V4-PROPOSAL.mdis repo-meta; instead allowlisted inscripts/audit-core.sh'sMETA_ALLOWLIST, exactly likeARCHITECTURE.md)make auditis green locally (markdownlint-cli2 not installed in this environment; validated offline — single H1, language-tagged fences, blank-line-delimited blocks/tables, single trailing newline; shell syntax of the edited audit script checks out. Please confirm via CI.)bootstrap.shwas noted/updated (N/A — proposal doc; no symlink)Notes
zsh/,core.manifest,loader.zsh, orbootstrap-lib.shis modified.fullvsstandard), whether to ship a one-minor_CORE_MODULEScompat shim or hard-cut, and the OS-layer band width.[Unreleased], since the work isn't implemented yet.🤖 Generated with Claude Code
https://claude.ai/code/session_01XgSG8AousYiEznFzv2mEBp
Generated by Claude Code