From 9b728a4c81934464ddf49e14e6cdd169927922c6 Mon Sep 17 00:00:00 2001 From: Julian Noble Date: Sun, 2 Aug 2026 17:50:09 +1000 Subject: [PATCH] G-031: approved contract update - guidance deliverables, runtime-queryable boot-core moduledoc, startup-script collision gate Scope adds src/vfs/README.md (boot-entry guidance), the punk::args moduledoc home and the make.tcl collision gate. Goal/Acceptance now require: project_main.tcl reborn as the commented thin-main sample, README boot-entry sections (repo + project-0.1 layout via sync channels), a punk::args::moduledoc package for the boot-core API shipped via _vfscommon, and per-kit bake refusal when a source .vfs carries both a root main.tcl and a main.tcl fauxlink (today silently traversal-order-dependent - merge_over fauxlink branch overwrites unwarned). Approach/Alternatives/Notes record the 2026-08-02 evidence: project_main.tcl unmapped in mapvfs.toml (layout-template-only), tomlish shared-_config + sample.vfs drop-in exhibits, moduledoc::punkexe delivery precedent. Status remains proposed - activation is a separate flip. Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com --- GOALS.md | 2 +- goals/G-031-componentized-kit-boot.md | 58 +++++++++++++++++++++++++-- 2 files changed, 56 insertions(+), 4 deletions(-) diff --git a/GOALS.md b/GOALS.md index 7747e808..42afb639 100644 --- a/GOALS.md +++ b/GOALS.md @@ -174,7 +174,7 @@ Scope: src/make.tcl (test-module packaging step); src/tests/ (source of truth); Detail: goals/G-029-testmodules-from-srctests.md ### G-031 [proposed] Componentized kit boot: thin project-owned main + shared layout-owned boot core -Scope: src/vfs/_config/ (punk_main.tcl, project_main.tcl restructure); src/vfs/_vfscommon.vfs (boot core delivery); src/project_layouts/ (thin-main skeleton, via established sync channels) +Scope: src/vfs/_config/ (punk_main.tcl, project_main.tcl restructure); src/vfs/_vfscommon.vfs (boot core delivery); src/project_layouts/ (thin-main skeleton + README guidance, via established sync channels); src/vfs/README.md (boot-entry guidance); src/modules/punk/args/moduledoc/ (boot-core API moduledoc); src/make.tcl (startup-script collision gate) Detail: goals/G-031-componentized-kit-boot.md ### G-032 [proposed] Kit launcher dogfoods punk::args: tabled help and parsed subcommands diff --git a/goals/G-031-componentized-kit-boot.md b/goals/G-031-componentized-kit-boot.md index fbadd330..9457e6b8 100644 --- a/goals/G-031-componentized-kit-boot.md +++ b/goals/G-031-componentized-kit-boot.md @@ -1,9 +1,9 @@ # G-031 Componentized kit boot: thin project-owned main + shared layout-owned boot core Status: proposed -Scope: src/vfs/_config/ (punk_main.tcl, project_main.tcl restructure); src/vfs/_vfscommon.vfs (boot core delivery); src/project_layouts/ (thin-main skeleton, via established sync channels) -Goal: the per-project vfs main script becomes a thin project-owned file - declare the application's subcommands and launch defaults at clearly commented customization points, then hand over to a shared layout-owned boot core (vfs mounts, package modes and paths, libunknown, src-mode modpod registration) and default dispatch pulled in from within the kit - so project developers add app-specific subcommands without wading through or forking ~1000 lines of boot boilerplate, and boot improvements reach derived projects as pull-updatable payload instead of dying in vintage forks (tomlish_main.tcl: ~20 custom lines carrying a stale 500-line 2025 copy of the rest). -Acceptance: punkshell's own kits boot through a thin main plus shared boot core with behaviour parity - package modes including src mode, existing tclsh/shellspy/punk/shell/script dispatch semantics, and supported vfs types (zipfs/metakit/cookfs) all unchanged; a project-specific subcommand is added by editing only the thin main at a commented customization point (proven end-to-end in a derived project - tomlish replacing its forked main is the natural first); the boot core ships as layout-owned payload (via _vfscommon/layout channels) and the thin main as a project-owned skeleton, per the G-027 ownership classification; the boot core is versioned/identifiable so a kit can report which boot-core vintage it carries (ties to G-025 stamping). +Scope: src/vfs/_config/ (punk_main.tcl, project_main.tcl restructure); src/vfs/_vfscommon.vfs (boot core delivery); src/project_layouts/ (thin-main skeleton + README guidance, via established sync channels); src/vfs/README.md (boot-entry guidance); src/modules/punk/args/moduledoc/ (boot-core API moduledoc); src/make.tcl (startup-script collision gate) +Goal: the per-project vfs main script becomes a thin project-owned file - declare the application's subcommands and launch defaults at clearly commented customization points, then hand over to a shared layout-owned boot core (vfs mounts, package modes and paths, libunknown, src-mode modpod registration) and default dispatch pulled in from within the kit - so project developers add app-specific subcommands without wading through or forking ~1000 lines of boot boilerplate, and boot improvements reach derived projects as pull-updatable payload instead of dying in vintage forks (tomlish_main.tcl: ~20 custom lines carrying a stale 500-line 2025 copy of the rest). The boot surface an application developer writes against is documented at the point of use (commented thin main, src/vfs README boot-entry guidance) and runtime-queryable from any kit carrying the boot core. +Acceptance: punkshell's own kits boot through a thin main plus shared boot core with behaviour parity - package modes including src mode, existing tclsh/shellspy/punk/shell/script dispatch semantics, and supported vfs types (zipfs/metakit/cookfs) all unchanged; a project-specific subcommand is added by editing only the thin main at a commented customization point (proven end-to-end in a derived project - tomlish replacing its forked main is the natural first); the boot core ships as layout-owned payload (via _vfscommon/layout channels) and the thin main as a project-owned skeleton, per the G-027 ownership classification; the boot core is versioned/identifiable so a kit can report which boot-core vintage it carries (ties to G-025 stamping); developer guidance ships with the split - project_main.tcl is reborn as the heavily commented thin-main sample (its monolith vintage retired) and src/vfs/README.md (repo and project-0.1 layout copies, via the established sync channels) gains a boot-entry section covering the recommended _config/_main.tcl-behind-the-fauxlink path, the supported plain root main.tcl alternative, the inertness of unreferenced _config files, and the one-startup-script rule; the boot-core API is runtime-queryable - a punk::args::moduledoc package (sibling of moduledoc::punkexe) documenting the thin-main contract and the post-boot ::punkboot surface ships via _vfscommon, so a kit answers boot-API queries the same way it answers launch-surface queries today; bake refuses to build a kit whose source .vfs carries both a root main.tcl and a root fauxlink resolving to main.tcl (per-kit refusal naming both files, other kits proceed), replacing today's silent traversal-order-dependent outcome, with the check unit-covered. ## Context @@ -52,6 +52,19 @@ permanently own - a thousand lines of boot code. in. Default-subcommand and no-args behaviour are declared, not hardcoded (a shell-like default remains the punkshell behaviour; a tool-like default such as tomlish's -help injection becomes a declared choice). +- Documentation delivery: the thin main IS the primary sample - project_main.tcl + reborn with heavily commented customization points, retiring its 901-line + monolith vintage. src/vfs/README.md (repo + project-0.1 layout copy) carries + the boot-entry guidance for humans: recommended path (edit + _config/_main.tcl behind the fauxlink - shared by multiple kits, e.g + tomlish's two shell kits), supported plain root main.tcl alternative + (tomlish sample.vfs is a live exhibit), one-startup-script rule, and the + _config-inertness misconception (files there reach kits only as fauxlink + targets). The boot-core API is documented runtime-queryably as a + punk::args::moduledoc package delivered like moduledoc::punkexe + (mint + promote to _vfscommon): thin-main registration contract plus the + post-boot ::punkboot procs - live definitions where procs persist post-boot, + display-first otherwise. - Boot core carries its own version/identity so a kit can report the boot vintage it embeds (G-025 stamping is the natural vehicle). - Layout skeletons follow through the established sync channels (custom/ @@ -69,6 +82,10 @@ permanently own - a thousand lines of boot code. are code; a thin project-owned code file with a clear contract is simpler than inventing a config schema for arbitrary launch behaviour. Revisit if the thin mains themselves start accreting boilerplate. +- Collision as BAKE-WARNING (bake proceeds) - rejected: both-present has no + correct winner; unlike a MISSING startup script (legal bare kit, warn-only), + ambiguity is a kit-definition error. Revisit only if a legitimate + both-present use case appears. ## Notes @@ -110,3 +127,38 @@ permanently own - a thousand lines of boot code. present the same surface as a kit (src/dev modes map naturally; kit-payload notions like os/internal follow the boot core's own zipfs-presence branching). Candidate follow-on when this goal activates. +- 2026-08-02 guidance/API decisions (user direction): the recommended + customization path is editing _config/_main.tcl behind the fauxlink; + a plain root main.tcl (no fauxlink) stays a supported simple shape; a + project main need not use the boot-core API at all - opting out entirely + remains legal (G-018 precedent: plain tclsh kits carry no punk boot layer; + bake must not assume the API is in use). Boot-core API documentation must + be runtime-queryable, not README-only. +- project_main.tcl status verified 2026-08-02: no kit mapping in + src/runtime/mapvfs.toml - never baked in punkshell itself; live only as + layout template payload (project-0.1 project.vfs boots through it via + fauxlink) and known-adrift (G-033: lacks src mode and proj:; only the tclsh + dispatch was byte-synced under G-118 interim). Its rebirth as the thin-main + sample is therefore a behaviour change for GENERATED projects only - parity + exercise belongs there (project.new E2E per the G-087 workflow). +- Startup-script collision evidence (2026-08-02): merge_over's fauxlink + branch materialises with file copy -force and NO overwrite warning + (make.tcl ~7780); only the plain-file branch warns (~7799); + vfs_startup_script_warning returns clean when a real main.tcl exists, so + both-present is undetected and the built kit's boot script depends on + traversal order - typically the fauxlink lands second and wins, so the + developer's drop-in file silently loses. Gate naturally extends + vfs_startup_script_warning (root-level check only; nested app/main.tcl + fauxlinks like punk8win's are a different path and exempt; overlay-only + folders remain unchecked). Independent of the split - may land ahead of the + rest as an early increment. +- Doc-home rationale (2026-08-02): src/vfs/README.md (repo and layout copies) + currently documents only G-115 payload declarations; the boot-entry + contract exists only in agent-facing src/vfs/AGENTS.md - the README section + fills a real human-facing gap. Moduledoc precedent: + punk::args::moduledoc::punkexe (G-118) documents the launch surface, + minted 0.2.0 + promoted to _vfscommon 2026-08-02. Naming: ::punkboot is + already the boot core's persistent runtime namespace (G-129 procs), so + punk::args::moduledoc::punkboot is the natural id home; the moduledoc + documents the API vintage alongside the G-025 stamp rather than duplicating + it.