punkshell/goals/G-156-alpha-window-identifier-alignment.md

G-156 alpha-window identifier alignment: persisted build-named identities renamed while consumers are none, with derived-project census

Status: proposed Scope: src/modules/punk/mix/cli-999999.0a1.0.tm + src/modules/punk/mix/base-999999.0a1.0.tm (mint-named installer surface, identity migration); src/make.tcl (BUILDCOPY -> BAKECOPY, identity references, buildversion.txt readers); modules/.punkcheck + derived-project .punkcheck ledgers (identity migration or accepted re-record); src/modules/*-buildversion.txt sidecar convention + module-header boilerplate (disposition decided at activation); scriptlib/developer/ (census scanner + committed census report); src/project_layouts + src/modules/punk/mix/#modpod-templates-999999.0a1.0/ (re-seeded identities via established sync channels); machine-wide census over user-confirmed roots (fossil config-db enumeration + bounded filesystem scan, punkorigin.toml + pre-G-087 marker fallbacks, siblings incl c:/repo/jn/tclmodules/tomlish + c:/repo/jn/serversecretsync + c:/repo/jn/punkbin); punkbin repo schema fields (build_id, build_sha1sums.tcl - disposition only) Goal: While punkshell is pre-adoption (alpha, one build/mint/bake machine, repos public but unpublicized with no evidenced third-party users, corporate consumers touching punk module APIs only), the persisted build-named identifiers G-155 keep-listed are aligned to the stage vocabulary - the punkcheck -installer identity moves to a mint-named punk::mix surface with a recorded ledger-migration strategy, BUILDCOPY becomes BAKECOPY, and the buildversion.txt sidecar convention gets an explicit rename-or-keep disposition - and a machine census discovers every project generated by dev project.new or carrying seeded punkshell infra (punkorigin.toml plus pre-G-087 marker fallbacks), records each one's drift (make.tcl vintage, goals-system version, ledger identities, workdir names) and reconciles or explicitly freezes each one, with the findings feeding the G-027 pull-system requirements record. Acceptance: (1) a census tool under scriptlib/developer enumerates candidates from the fossil config-db plus a bounded scan of user-confirmed roots, identifies derived projects by punkorigin.toml or recorded fallback markers, and its committed report lists every hit with a per-project drift record and disposition (reconcile/freeze/retire) - no undispositioned rows; (2) the renamed identities land in punkshell (mint-named installer surface with the old proc name as a compatibility shim or a recorded removal decision, BAKECOPY, the buildversion.txt disposition executed) and a full 'make.tcl bakehouse -confirm 0' passes; (3) ledger continuity is proven - after migration a repeat 'make.tcl packages' run on punkshell and on each reconciled project reports zero spurious re-installs, or the per-project decision to accept a one-time full re-record is recorded and executed; (4) re-seeded layouts and the templates modpod carry the new identities and each reconciled project's own make.tcl runs its packages stage cleanly; (5) the alpha-window rationale and its expiry condition (publicization or the first evidenced third-party consumer closes the window) are recorded here, G-027's Notes gain the census-derived requirements, and punk::mix module versions + the project version + CHANGELOG are bumped.

Context

User rationale (2026-08-02, follow-on to the G-155 draft): "If we're ever going to make things more consistent - soon is the time to do it." punkshell is alpha; only this machine runs the build/mint/bake infrastructure; the corporate infra consumes punk modules (their public APIs - not the punkshell build machinery); punkshell/punkbin and related repos are public but unpublicized, with no evidence of third-party users. The identifier churn that G-155 parked as "highest churn risk" is therefore at its cheapest right now, and the cost only grows.

The difficult part (user-identified) is the machine scan: projects generated with dev project.new, or carrying seeded GOALS/AGENTS systems, use old terminology and already drift because the G-027 pull system is unimplemented. The census is both this goal's risk-pricing step and G-027's requirements-gathering.

Candidate work-list (G-155's identifier keep-list, promoted):

• punk::mix::cli::lib::build_modules_from_source_to_base - also the punkcheck -installer identity string (1644 rows in punkshell's modules/.punkcheck alone; derived projects carry their own ledgers). Rename to a mint-named surface + migration strategy; the old name's fate (compatibility shim vs removal) is an activation decision. Note: derived projects run their own bootsupport copy of punk::mix, so stale projects keep working regardless - the shim matters only for mixed states (new punk::mix driving an old make.tcl).
• BUILDCOPY punkcheck event + runtime_buildcopyname -> BAKECOPY family.
• -buildversion.txt sidecars - the big one: hundreds of files, boilerplate in every module header, readers in make.tcl (bootsupport staleness compare, make.tcl:1752-1769) and punk::mix::commandset::module, layout seeds, docs. Disposition at activation: rename (e.g. mintversion.txt, readers accepting both during transition) vs keep-with-recorded-reading ("the version stamped when minted").
• (Resolved 2026-08-02: G-155 achieved with both renamed - get_bake_workdir landed with a legacy alias whose retirement is this goal's decision, and bakelist says nobake - so nothing folds in from there beyond the alias-retirement question.)
• Internal locals (build_warnings_pending, building_runtime, module_build_version, kit_builddir) - opportunistic, zero contract weight.
• Stays out of scope even under the window: build.zig/build.zig.zon, tcl::build-info, kettle's required build.tcl filename, doc.build (kettle vocabulary) - external contracts.

Approach

Ordering: census FIRST (it prices every rename decision), then punkshell renames, then re-seeded layouts/templates, then per-project reconciliation. Runs after G-155 (achieved 2026-08-02) - the mint/bake vocabulary this goal presupposes is landed.

Census tool (scriptlib/developer, name decided in the work):

• Enumeration lanes: (a) fossil central config-db via punk::repo::fossil_get_configdb - the projects.work lane, with the staleness caveats G-016 recorded (flag rows whose checkout dirs are missing or under temp locations); (b) bounded filesystem scan of user-confirmed roots (activation input; candidates: c:/repo, and any other roots the user names) - a one-time explicit audit scan, the scan-once seed cousin of G-016's configured-search-roots option, NOT query-time scanning (the G-016/G-017 posture against that stands).
• Identification: punkorigin.toml (G-087-seeded, format 1 - generation utc, layout name, templates version, punkshell version, origin path hint) is the primary marker; pre-G-087 vintages need fallbacks (punkproject.toml, punkboot-signature src/make.tcl, seeded GOALS.md "Goals-system:" frontmatter, .punkcheck presence).
• Per-project record: path, VCS (git/fossil/both), punkorigin.toml contents if present, make.tcl vintage (pre-G-112 / G-112 / G-155 vocabulary generation), goals-system version declared, .punkcheck installer identities found, _build/_mint/_bake dir names present, seeded GOALS/AGENTS terminology notes, disposition (reconcile / freeze / retire).

Renames + migration:

• Ledger migration options, chosen per project by ledger value: (a) identity-string rewrite over .punkcheck files; (b) delete-and-re-record - punkcheck ledgers are a rebuildable acceleration cache (G-094/G-095 lineage), so one forced full pass rebuilds equivalent state. Either way the acceptance test is the zero-spurious-reinstall repeat run.
• Reconciliation honours the G-027 ownership split: layout-owned files (make.tcl, bootsupport, template payloads, layout-owned docs) are refreshed; project-owned skeletons (root AGENTS.md, GOALS framework) are REPORTED as drifted, never rewritten - their terminology is the derived project's to change.
• Reconciliation here is one-time scripted catch-up using the existing push mechanism (dev project.new -force 1 -update 1) or manual steps recorded per project - explicitly NOT the G-027 pull system; what it teaches (identity/provenance needs, classification cases, moved-project hits) lands in G-027's Notes as requirements.

Open decisions

To resolve at activation:

• Scan roots list (user confirms; c:/repo assumed, others named then).
• buildversion.txt: rename (to what; transition dual-read window) vs keep-with-recorded-reading.
• punkbin schema fields build_id / build_sha1sums.tcl: lean KEEP (embedded in released artifact records; renaming means a schema bump and re-release) - confirm or override.
• Compatibility-shim window for the old installer proc name (and whether the shim itself records a deprecation notice).
• Census tool's relationship to G-016 (share enumeration code now, or census stays standalone and G-016 adopts it later).
• Whether frozen projects get an in-repo marker (e.g. a punkorigin.toml note) or only the census report row.

Notes

Window expiry: the rationale holds only while unpublicized with no evidenced third-party users - publicization or the first known external consumer closes it. If unclosed work remains at that point, the remainder hardens back to G-155's keep-list posture and this goal is re-scoped or abandoned with that record.

Known sibling starting set for the census (discovery confirms, not assumes): tomlish (c:/repo/jn/tclmodules/tomlish - fossil-only, carries its own src/make.tcl copy; the 2026-07-06 drift incident in G-027's Context is its precedent), serversecretsync (c:/repo/jn/serversecretsync - punkshell-style DOX/GOALS seeds, no src/make.tcl), punkbin (c:/repo/jn/punkbin - artifact repo, schema-field disposition only), modpod + punkzip + metakit_punk + tclparser_punk (fork/tool repos - census records whether any carry seeded infra).

Corporate module consumers: they consume built punk module APIs; nothing here renames a shipped module's public command surface (the renamed procs are dev-tooling inside punk::mix) - but punk::mix module versions are bumped properly like any module change.

G-159 (achieved 2026-08-03 - goals/archive/G-159-followon-disposition-tracking.md) bumped the goals-system to v4 (Follow-on disposition tracking): the census's per-project goals-system-version drift field now spans v1..v4, and its open-items report (scriptlib/developer/goals_followons.tcl) is a candidate input for this goal's requirements gathering.

Overlap survey 2026-08-02: goals_xref paths over scriptlib/developer + src/modules/punkcheck + src/modules/punk/mix surfaced G-069 (scriptlib neighbour, unrelated), G-066 (punk::mix neighbour - the buildversion.txt disposition does not touch its repackaging surface) and G-155; punkcheck has no live intersecting goals. Related lines below record the real relationships.

Related: G-155 (predecessor, achieved 2026-08-02 - see goals/archive/G-155-mint-stage-vocabulary.md; its identifier keep-list is this goal's candidate work-list and the mint/bake vocabulary is landed; the get_build_workdir legacy alias retirement decision transfers here) Related: G-027 (this goal's census is its requirements-gathering and its punkorigin.toml carrier is the census's primary marker; reconciliation here is one-time catch-up via the existing push flow, never the pull system itself - G-027 stays the durable mechanism; its docs-ownership split governs what reconciliation may touch) Related: G-016 + G-017 (fossil config-db enumeration with recorded staleness caveats is the census's registry lane; the bounded root scan is the scan-once seed cousin of G-016's configured-roots option; the census must not normalize query-time filesystem scanning) Related: G-026 (clean-checkout policy on the punkshell source side when reconciling derived projects)

2026-08-02 census input (dev->minted rename, punkshell 0.43.0): the layout src/vfs/_config boot mains are OUTSIDE the thin-layout sync channel (make.tcl/build.tcl/manifests/gitignore.in only) - the project-0.1 layout's punk_main.tcl was found 285 lines behind canonical (pre-G-033 vintage; G-033 achieved - goals/archive/G-033-proj-mode-cwd-project.md) and was token-swept in place rather than upgraded. The census should record each derived project's _config vintage, and the reconciliation/pull design (G-027) should decide whether _config joins the sync channel. The package_mode rename (dev -> minted, clean break) adds to every stale kit's catch-up delta: kits accept only the mode vocabulary they were baked with.

Archived-goal references in this file: G-112 achieved 2026-07-25 (goals/archive/G-112-maketcl-subcommand-rename.md); G-087 achieved 2026-07-19 (goals/archive/G-087-thin-project-layouts.md); G-094 + G-095 achieved 2026-07-21 (goals/archive/G-094-punkcheck-single-lifecycle.md, goals/archive/G-095-punkcheck-concurrent-writer-safety.md).