punkshell/goals/G-026-vendor-provenance-policy.md

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

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