From 92f6c304422e261ec469cc392204739e9fe4dfc6 Mon Sep 17 00:00:00 2001 From: Julian Noble Date: Mon, 6 Jul 2026 23:00:26 +1000 Subject: [PATCH] add goal G-027: pull-based infrastructure updates for derived projects Projects generated by dev project.new receive a layout snapshot that drifts; the current remedy is a push from punkshell (project.new -force 1 -update 1). G-027: one command run inside the derived project pulls make.tcl/build.tcl, bootsupport modules/libs and template payloads from the originating punkshell project - .punkcheck records remain the provenance basis, origin identity becomes durable to workdir moves (not relative paths alone; projects.work discovery as re-locator), VCS awareness on both ends (G-026 clean-checkout policy on the source, uncommitted-local-modification detection on the target), and the remote-pull question gets a recorded decision. Detail file records the motivating incident (tomlish 2026-07-06: a stale make.tcl whose bootsupport updater was disabled by the very drift it needed to fix - broken bundled fileutil::traverse under Tcl 9) and the constraint that the pull entrypoint must not depend on the freshness of what it updates. Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com --- GOALS.md | 6 ++ goals/G-027-derived-project-pull-updates.md | 82 +++++++++++++++++++++ 2 files changed, 88 insertions(+) create mode 100644 goals/G-027-derived-project-pull-updates.md diff --git a/GOALS.md b/GOALS.md index 5514e8b4..3ec0c078 100644 --- a/GOALS.md +++ b/GOALS.md @@ -204,3 +204,9 @@ Scope: src/make.tcl (vendorupdate and bootsupport steps), src/vendormodules/incl Detail: goals/G-026-vendor-provenance-policy.md Goal: pulling vendored or bootsupport artifacts from local source projects enforces committed provenance - the warn-only dirty-checkout check added to vendorupdate in project 0.2.5 becomes a policy that can abort with an explicit override, covers the bootsupport update path as well, and the residual staleness question (built modules that predate or postdate the committed source even in a clean checkout) has a recorded design decision. Acceptance: vendorupdate and the bootsupport update refuse to pull from a source project whose fossil/git checkout is dirty unless an explicit documented override is given (warn-only selectable as a configured mode); the check reports each VCS root once per run and does not fire for unversioned source locations; bootsupport_localupdate is covered by the same shared check (no second divergent implementation); the staleness gap - a clean checkout whose built modules/ artifacts do not correspond to the committed source - is either detected (mechanism chosen and implemented) or explicitly recorded in the detail file as accepted risk with the considered mechanisms; behaviour is exercised by a test or documented manual verification against a scratch dirty checkout. + +### G-027 [proposed] Pull-based infrastructure updates for punkshell-derived projects +Scope: src/modules/punk/mix/commandset/project-999999.0a1.0.tm (project.new push path), src/modules/punkcheck-999999.0a1.0.tm (install provenance records), src/make.tcl (derived-project pull entrypoint) +Detail: goals/G-027-derived-project-pull-updates.md +Goal: a project generated from a punkshell layout can pull infrastructure updates (make.tcl/build.tcl, bootsupport modules and libs, layout template payloads) from its originating punkshell project by running one command inside the derived project - replacing the current push model (`dev project.new -force 1 -update 1` run from punkshell) - with install provenance robust to derived-project workdir moves (not local relative paths alone), VCS-state awareness on both ends, and a recorded decision on pulling from remote sources. +Acceptance: one documented command run inside a derived project updates its punkshell-derived infrastructure from the source punkshell project; the update still works after the derived project's working directory has been moved (proven by moving a scratch derived project and pulling); VCS integration on both ends: the pull applies the G-026 clean-checkout policy to the punkshell source, and reports (or refuses per option) when target files it would overwrite carry uncommitted local modifications in the derived project's git/fossil checkout; .punkcheck records remain the provenance basis (updates are recorded and unchanged targets skipped, as with existing punkcheck-tracked installs); the push flow keeps working until explicitly retired; the remote-pull question (updating from a remote punkshell repository rather than a local checkout) has a recorded design decision - implemented, or deferred with rationale in the detail file. diff --git a/goals/G-027-derived-project-pull-updates.md b/goals/G-027-derived-project-pull-updates.md new file mode 100644 index 00000000..3c611514 --- /dev/null +++ b/goals/G-027-derived-project-pull-updates.md @@ -0,0 +1,82 @@ +# G-027 Pull-based infrastructure updates for punkshell-derived projects + +Status: proposed +Scope: src/modules/punk/mix/commandset/project-999999.0a1.0.tm (project.new push path), src/modules/punkcheck-999999.0a1.0.tm (install provenance records), src/make.tcl (derived-project pull entrypoint) +Acceptance: as in root GOALS.md index (canonical). + +## Context + +Projects initialised via `dev project.new` (punk::mix::commandset::project::new) +receive a snapshot of punkshell's layout system: make.tcl/build.tcl, bootsupport +modules and libs, template payloads. That snapshot then drifts. The current +remedy is a push from punkshell: re-running `dev project.new -force 1 -update 1` +against the derived project. A pull - one command run inside the derived +project - is the more natural shape: the derived project knows when it wants +updating, and its owner is the right party to review what changes. + +Motivating incident (2026-07-06, tomlish project): a make.tcl vintage 2025-04 +carried a bootsupport-update step that itself depended on a stale bundled +fileutil::traverse (Tcl 8.x-only constraint, broken under 9.0.3), so the tool +that should fix the drift was disabled by the drift; bootsupport/lib still had +the obsolete per-platform layout; include_modules.config files were empty +template stubs. Recovery required manual cross-project copying - exactly the +push-shaped work this goal eliminates. A drifted derived project must be +recoverable by a pull whose own machinery does not depend on the freshness of +the drifted parts (the pull entrypoint should be small/self-contained enough to +work from a stale project, or delivered as its first step). + +## Current mechanism and its limits + +- .punkcheck records in the derived project record where targets were installed + from (installer/source paths) - "roughly the right shape": provenance-driven, + change-detected, skippable when unchanged. +- Limits: + - Source references are local relative paths - resolution breaks or silently + mislocates if the derived project (or punkshell checkout) moves. + - No VCS awareness: nothing checks whether the punkshell source is dirty + (G-026 territory) or whether the pull would clobber uncommitted local + modifications in the derived project. + - Push-only initiation, from the punkshell side. + +## Approach + +- A pull entrypoint in the derived project (make.tcl subcommand or a small + standalone bootstrap that does not depend on the possibly-stale local + infrastructure). +- Provenance robust to moves: record the origin punkshell project by something + more durable than a relative path - candidates: fossil project-code / git + remote or commit identity, plus a locally-resolvable path hint refreshed on + each pull; `dev projects.work` discovery (G-016/G-017) can re-locate a moved + punkshell checkout by name/id when the stored path fails. +- VCS integration on both ends: + - Source side: G-026 clean-checkout policy shared, not reimplemented. + - Target side: before overwriting, classify each target file - unmodified + since last punkcheck install (safe), locally modified but committed + (report/confirm), uncommitted local changes (refuse or explicit override). +- Remote pulls: decide whether updates may come directly from a remote + punkshell repository (fossil clone/sync or git fetch of a punkshell repo, + or the G-006 artifact-download channel) rather than a local checkout. + Considerations: provenance/verification of remote content, version pinning + (pull a tagged punkshell release vs trunk), and interaction with the + consent-gating principle of G-006. May be recorded as deferred with + rationale. + +## Alternatives considered + +- Keeping push-only and just fixing its path robustness - rejected as the end + state: the updater lives on the wrong side of the relationship; the derived + project's owner should initiate and review. Push retained during transition. +- Making derived projects git/fossil-track punkshell as an upstream remote and + merge - rejected: derived projects are independent repos with their own + history; infrastructure files are a curated payload, not a branch to merge. + +## Notes + +- Related: G-012 (inert template payloads and the make.tcl template-refresh + step feed what a pull delivers), G-016/G-017 (project discovery for + re-locating a moved origin), G-026 (clean-checkout policy on the source), + G-005/G-006 (remote artifact channels if remote pull proceeds). +- The 2025-04 tomlish checkin "update bootsupport and make.tcl from punkshell" + and the 2026-07-06 manual recovery are the concrete push-model precedents to + test the pull against: a scratch project seeded at an old layout vintage + should be fully recoverable by one pull.