Browse Source
User-directed follow-on to G-155 (2026-08-02): with punkshell alpha, single-machine build infra and no evidenced third-party users, the identifier keep-list becomes a candidate work-list while renames are cheap. - goals/G-156-alpha-window-identifier-alignment.md: contract (proposed) - punkcheck installer-identity migration (mint-named surface + ledger strategy: rewrite vs rebuildable-cache re-record), BUILDCOPY -> BAKECOPY, buildversion.txt disposition; census tool (fossil config-db lane per G-016 caveats + bounded scan of user-confirmed roots, punkorigin.toml primary marker + pre-G-087 fallbacks) with committed reconcile/freeze/ retire report; reconciliation honours G-027 docs-ownership split and feeds its requirements; window-expiry condition recorded - GOALS.md: G-156 index entry appended (activation is a user decision) - goals/G-155-mint-stage-vocabulary.md: Related pointer to G-156 (Notes, non-contract) Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.commaster
3 changed files with 141 additions and 0 deletions
@ -0,0 +1,134 @@
|
||||
# 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. |
||||
- <pkg>-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"). |
||||
- If G-155 lands with keeps on get_build_workdir or bakelist's nobuild token, those fold in here. |
||||
- 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 or in the same window - this |
||||
goal presupposes the mint/bake vocabulary. |
||||
|
||||
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. |
||||
|
||||
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, proposed - its identifier keep-list is this goal's candidate work-list; |
||||
this goal presupposes its mint/bake vocabulary; ordering: G-155 first or same window) |
||||
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) |
||||
|
||||
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). |
||||
Loading…
Reference in new issue