# G-026 Enforceable clean-checkout provenance policy for vendor and bootsupport pulls

Status: proposed
Scope: src/make.tcl (vendorupdate and bootsupport steps), src/vendormodules/include_modules.config, src/bootsupport/modules*/include_modules.config
Acceptance: as in root GOALS.md index (canonical).

## Context

`make.tcl vendorupdate` pulls the latest release-stamped module files from each
source project's built `modules/` folder (paths declared in
include_modules.config). Nothing verified the source project's checkout state,
so artifacts built from uncommitted source could be vendored with no committed
provenance anywhere. This actually happened: tomlish 1.1.7/1.1.8 were vendored
into punkshell from a tomlish working tree whose fossil history ended at 1.1.6
- the released content existed only as uncommitted edits (recorded and
remedied 2026-07-06, tomlish checkin 37b71e82).

A warn-only check was added in project 0.2.5 (fix-now/goal-later review,
2026-07-06): `vendor_source_dirty_warnings` in make.tcl walks up from each
vendor source path to the nearest fossil and/or git root, runs
`fossil changes` / `git status --porcelain`, and warns once per VCS root when
dirty. The first real run flagged 8 dirty source projects, confirming the
problem is endemic, and equally that **abort-by-default would have made
vendorupdate unusable on this machine today** - which is why enforcement is a
goal (requiring cleanup and a policy/override design) rather than part of the
quick fix.

## Approach

- Promote the warning to a policy: refuse to pull from dirty source projects
  unless an explicit override is given (flag such as
  -allow-dirty-sources, or per-project allowance); warn-only remains
  selectable as a configured mode. Where the mode is configured (command flag
  vs punk::config once G-014 lands) is an implementation decision to record.
- Share one check implementation between vendor_localupdate and
  bootsupport_localupdate (make.tcl already carries a
  "todo - sync alg with bootsupport_localupdate!" note; do not grow a second
  divergent copy).
- Per-root reporting and unversioned-location silence are established
  behaviour from the 0.2.5 check - keep them.

## The residual staleness gap

A clean checkout is necessary but not sufficient: the built `modules/` files
are produced from the working tree at build time, so they can predate the
latest commits (stale) or - the reverse of the tomlish case - have been built
from dirt that was subsequently committed. Candidate mechanisms, decision to
be recorded here:

- Rebuild-on-demand: vendorupdate triggers the source project's module build
  before pulling (correct, but couples projects' build systems).
- Provenance stamp: source projects stamp checkout id (fossil checkin /
  git hash) into built modules at build time; vendorupdate compares stamp to
  the source project's current checkout id (ties into the G-025 stamping
  machinery pattern).
- Accepted risk: document that clean-checkout checking is the enforced bar and
  staleness remains a manual concern.

## Alternatives considered

- Abort-by-default immediately (no goal, just flip the fix) - rejected for
  now: the first run showed 8 dirty source projects; enforcement without a
  cleanup pass and an override design would block routine work.
- Checking only the specific pulled files' dirtiness rather than the whole
  source checkout - rejected: the built module is generated from many source
  files; per-file dirt attribution against a build product is not tractable.

## Notes

- include_modules.config files carry their own "#todo - change to
  include_modules.toml" - a natural companion change under the G-024
  toml-conversion pattern, but deliberately not part of this goal's
  acceptance.
- Related: G-014 (tomlish provenance incident motivated this), G-024 (toml
  config direction), G-025 (build stamping machinery a provenance stamp could
  ride on).