# 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.