From ea917debf4976003cfb8c3e570ca3abccb2da8ba Mon Sep 17 00:00:00 2001 From: Julian Noble Date: Sun, 2 Aug 2026 14:15:18 +1000 Subject: [PATCH] G-156 proposed: alpha-window identifier alignment + derived-project census 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.com --- GOALS.md | 4 + goals/G-155-mint-stage-vocabulary.md | 3 + ...G-156-alpha-window-identifier-alignment.md | 134 ++++++++++++++++++ 3 files changed, 141 insertions(+) create mode 100644 goals/G-156-alpha-window-identifier-alignment.md diff --git a/GOALS.md b/GOALS.md index 65660dfc..b168b63a 100644 --- a/GOALS.md +++ b/GOALS.md @@ -410,3 +410,7 @@ Detail: goals/G-151-punkargs-annotated-success-render.md Scope: src/make.tcl (SUMMARIES/HELPTEXTS/SUBGROUPS, workflow_text + new TERMINOLOGY block, BUILD-WARNING -> BAKE-WARNING, bakelist vocabulary, workdir paths); src/modules/punk/mix/base-999999.0a1.0.tm + src/modules/punk/mix/cli-999999.0a1.0.tm (workdir paths, antidir/antipattern/reserved lists, legacy vfs-cksums trio disposition); src/vfs/_config/punk_main.tcl + src/vfs/_config/project_main.tcl (dev-mode src/_build path logic); .gitignore + .fossil-settings/ignore-glob (_build glob split per dual-VCS derivation); src/project_layouts (make.tcl copies, gitignore.in + ignore-glob payloads, via established sync channels); src/tests/shell/testsuites/punkexe/ + src/tests/modules/punkboot/ + src/tests/modules/punkcheck/ (pinned tokens: BUILD-WARNING, nobuild, _build paths); AGENTS.md + src/AGENTS.md + src/modules/AGENTS.md + src/vfs/AGENTS.md + src/runtime/AGENTS.md + bin/AGENTS.md + README.md + src/README.md + ARCHITECTURE.md (prose sweep); GOALS.md G-029 entry title (coordinated proposal-first edit) Detail: goals/G-155-mint-stage-vocabulary.md +### G-156 [proposed] Alpha-window identifier alignment: persisted build-named identities renamed while consumers are none, with derived-project census +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) +Detail: goals/G-156-alpha-window-identifier-alignment.md + diff --git a/goals/G-155-mint-stage-vocabulary.md b/goals/G-155-mint-stage-vocabulary.md index ae4f7c1e..ca7c4cbe 100644 --- a/goals/G-155-mint-stage-vocabulary.md +++ b/goals/G-155-mint-stage-vocabulary.md @@ -176,3 +176,6 @@ their landings) Related: G-023 + G-005 + G-006 + G-019 + G-026 + G-089 + G-136 (umbrella/module-stage/bake-domain 'build' prose named in the survey - live-tier non-contract wording rides this sweep; contract-line instances follow proposal-first at their own goals) +Related: G-156 (follow-on, proposed 2026-08-02) - promotes this goal's identifier keep-list to a +candidate work-list under the alpha-window rationale (no evidenced third-party consumers yet) with a +machine-wide derived-project census; this goal's prose/tag/workdir sweep stands alone either way diff --git a/goals/G-156-alpha-window-identifier-alignment.md b/goals/G-156-alpha-window-identifier-alignment.md new file mode 100644 index 00000000..1d9ad301 --- /dev/null +++ b/goals/G-156-alpha-window-identifier-alignment.md @@ -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. +- -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).