punkshell/goals/G-012-template-payload-safety.md

G-012 Template system: inert VCS-config payloads and explicit layout refresh

Status: proposed Scope: src/project_layouts/, src/make.tcl, src/modules/punk/mix/ (layout instantiation), fauxlink module (bootsupport 0.1.1 - promoted if chosen as mechanism) Goal: project layouts carry no live nested VCS-config files - template .gitignore payloads are stored inert (renamed, or fauxlink-encoded) and materialized at project generation - and src/make.tcl has an explicit punkcheck-tracked step that refreshes layout payloads from their canonical sources. Acceptance: a scan of src/project_layouts finds no file named .gitignore, and git check-ignore --no-index over every layout file matches only root-.gitignore rules (nested rules provably inert); a project generated from each affected layout receives a working .gitignore whose content matches the canonical payload/target; after editing a canonical source (e.g. root .gitignore), the make.tcl template-refresh step updates the derived layout payloads (punkcheck-tracked), covering vendor/punk layouts as well as custom/_project; the previously hidden template files (layout READMEs, vendored TODO-class files) remain git-tracked without per-file force-add exceptions.

Context

Project layouts under src/project_layouts/ carry .gitignore files as payload - the ignore file a generated project is supposed to receive (essentially a copy of shellspy's own root .gitignore). But git has no concept of payload: any .gitignore anywhere in the working tree is live configuration for its subtree, with leading-/ patterns anchored to the nested file's own directory. The result is a template that self-censors - the layout ignores, in the shellspy repo, exactly what a generated project would ignore in itself.

Discovered 2026-07-06 during git/fossil tracked-set verification (fossil reads only the checkout-root .fossil-settings/ignore-glob, so it managed template files git silently dropped): four vendor/punk/* layouts each carry a live .gitignore, and .../project-0.1/{bin,lib,modules}/README.md plus bin/runtime/README.md were untracked in git. The bin/runtime case shows the nastier variant - git does not descend into an excluded directory, so negation patterns cannot resurrect deeper paths. The immediate stopgap was per-file git add -f (commit fc1c474c), which protects only existing files: any new file placed in a template's ignored spots drops silently again. The dual-VCS contract (.fossil-settings/AGENTS.md) records the git/fossil asymmetry and points here for the fix.

A secondary weakness: template payloads that mirror living files (the root .gitignore, build.tcl/make.tcl, bootsupport modules) have only partial refresh machinery. make.tcl's sync_layouts step (punkcheck-tracked) syncs just build.tcl and make.tcl, and only into the custom/_project layout base - the vendor/punk/* layouts have no refresh mechanism, so payload drift is unmanaged.

Approach

1. Store VCS-config payloads inert. Two candidate mechanisms; the choice is an implementation decision to be recorded here when made:
   • Neutral rename: payload stored as e.g. _gitignore or gitignore.in; layout instantiation renames it to .gitignore in the generated project. Simple, no new dependency; templates keep a literal copy (drift handled by the refresh step).
   • Fauxlink: payload stored as <nominal>#<encoded-target>.fauxlink (see fauxlink module, currently bootsupport 0.1.1) and resolved at generation. Inert for git by construction, and the target can be the canonical root .gitignore itself - eliminating copy drift rather than managing it. Requires generation-time resolution in punk::mix and possibly promoting fauxlink to a first-class module dependency.
2. Materialize at generation. The punk::mix layout-instantiation path produces a real .gitignore in the generated project regardless of mechanism, with content equal to the canonical payload/target.
3. Explicit template refresh in make.tcl. Generalise the existing sync_layouts step into a defined template-refresh covering the vendor/punk/* layout base as well as custom/_project, and derived payloads beyond build.tcl/make.tcl (the gitignore payload, and prospectively other mirrored content). punkcheck-tracked like the existing step, so refreshes are recorded and skippable when sources are unchanged.
4. Retire the stopgap. With inert payloads, the per-file force-adds from fc1c474c become ordinary tracked files (no ignore rule matches them); the accidental-ignore class is structurally impossible rather than patched per file.

Alternatives considered

• Negation entries inside the nested template .gitignore files (e.g. !README.md) - rejected: pollutes the payload that generated projects receive, and cannot fix the excluded-directory case (bin/runtime/) because git does not descend into excluded dirs to evaluate negations.
• Keep per-file git add -f only - rejected as the durable answer: silent drop recurs for every new file placed under a template's ignored paths; nothing structural changes.
• .git/info/exclude or repo-local config tricks - rejected: not versioned/portable to other clones and contributors.
• Do nothing on the git side (fossil sees the files) - rejected: git is the day-to-day VCS; a mirror having the truer view is a symptom, not a solution.

Notes

• Affected today: src/project_layouts/vendor/punk/{basic,minimal,project-0.1,sample-0.1}/.gitignore. The same inert-payload treatment should apply to any future live-config payloads in layouts (e.g. .gitattributes); .fossil-settings/ payloads in layouts are inert by nature (fossil reads them only at a checkout root) and need no change.
• AGENTS.md payloads are the same hazard class (identified 2026-07-07 while designing template DOX for derived projects, see G-027 detail): an AGENTS.md stored as template payload under src/project_layouts/ is live DOX for any agent whose work touches layout paths in the punkshell repo itself - the DOX walking rule makes it binding contract, though its instructions are written for a generated project (e.g. its build/test commands would operate on template internals). When layouts gain AGENTS.md payloads (per the G-027 documentation-ownership design), they need the same inert storage + materialize-at-generation treatment as the .gitignore payloads.
• fauxlink background: target encoded in the filename (+ for /, url-style escapes), no filesystem support required, application-driven resolution - see src/bootsupport/modules/fauxlink-0.1.1.tm doctools header.
• Verification tie-in: the dual-VCS sync checks in .fossil-settings/AGENTS.md double as a regression detector for this class - after this goal, the "git-tracked invisible to fossil" comparison should show no template-payload entries.
• G-062 (archived) recorded a follow-on in this territory: seeding LICENSE.txt into generated project layouts (deliberately excluded from G-062's acceptance because src/project_layouts sync is restricted) - see goals/archive/G-062-project-license-file.md.