From 6e68e29a1e1974b10f72d4431ca0e72d5ead997c Mon Sep 17 00:00:00 2001 From: Julian Noble Date: Tue, 14 Jul 2026 21:41:13 +1000 Subject: [PATCH] goals: G-086 proposed - light project layout carrying startup/test module-path semantics User-approved from the serversecretsync tm-path-shadowing incident (8.6 require-before-path-setup silently selected a stale tomlish from the machine-default tm paths over the project's vendored copy). Default mechanism per user: vendor punk::libunknown + punk::packagepreference as the light layout's bootstrap minimum. Related: G-012/G-027/G-029/G-035. Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com --- GOALS.md | 4 ++++ goals/G-086-light-project-layout.md | 16 ++++++++++++++++ 2 files changed, 20 insertions(+) create mode 100644 goals/G-086-light-project-layout.md diff --git a/GOALS.md b/GOALS.md index 3f80afde..4a5ef986 100644 --- a/GOALS.md +++ b/GOALS.md @@ -321,3 +321,7 @@ Detail: goals/G-084-punkargs-parsekey-completeness.md ### G-085 [proposed] punk::ns::cmdtrace: source-file vs live-proc line attribution option, and machine-parseable trace output Scope: src/modules/punk/ns-999999.0a1.0.tm (cmdtrace, _cmdtrace_* trace callbacks, argdoc), src/tests/modules/punk/ns/testsuites/ns/cmdtrace.test Detail: goals/G-085-cmdtrace-attribution-and-machine-output.md + +### G-086 [proposed] Light project layout: punkshell-generated minimal projects carrying startup/test module-path semantics +Scope: src/project_layouts/ (new light layout), src/modules/punk/mix/commandset/project-999999.0a1.0.tm (project.new layout selection), layout-seeded test harness + startup preamble (no bootsupport/vfs/build trees in generated output) +Detail: goals/G-086-light-project-layout.md diff --git a/goals/G-086-light-project-layout.md b/goals/G-086-light-project-layout.md new file mode 100644 index 00000000..66a41380 --- /dev/null +++ b/goals/G-086-light-project-layout.md @@ -0,0 +1,16 @@ +# G-086 Light project layout: punkshell-generated minimal projects carrying startup/test module-path semantics + +Status: proposed +Scope: src/project_layouts/ (new light layout), src/modules/punk/mix/commandset/project-999999.0a1.0.tm (project.new layout selection), layout-seeded test harness + startup preamble (no bootsupport/vfs/build trees in generated output) +Goal: project.new can generate a "light" layout - no kits, vfs, bootsupport or build-output trees - that still carries punkshell's environment-control semantics: a seeded script/test startup preamble that deterministically places project module paths (modules, vendormodules, vendorlib) ahead of machine-default tm paths before any package require, a runtests-style test harness, and the DOX/GOALS doc seed, so light projects (e.g. serversecretsync) inherit punkshell startup discipline without the build machinery. +Acceptance: on a machine whose default tm paths carry older copies of a vendored package (the tomlish 1.1.10-vs-1.1.12 incident as the reference case), a generated light project's seeded harness and preamble provably select the project's vendored module on both Tcl 8.6 and 9.x, with a characterization test shipping in the layout that exercises the require-before-path-setup failure mode; the generated tree contains no build-output directories; and serversecretsync can adopt the seeded preamble/harness with its existing doc.test suite passing unchanged. + +## Context + +serversecretsync (c:/repo/jn/serversecretsync) was seeded 2026-07-14 by hand rather than via project.new, deliberately staying light - and promptly hit the class of failure punkshell's launch control exists for: on Tcl 8.6, a `package require` before tm path setup registered modules from the machine-default tm paths (which on dev machines carry punkshell's built modules/ dir) and silently selected tomlish 1.1.10 over that project's vendored 1.1.12; Tcl 9.0 selected correctly with either ordering. Characterized in serversecretsync's src/tests/AGENTS.md and its archived G-008 detail file. A light layout should make this failure impossible by construction, giving hand-lightness without giving up startup semantics. + +## Approach + +- Default mechanism (user decision 2026-07-14): vendor punk::libunknown + punk::packagepreference into the light layout as the bootstrap minimum, so generated projects get punkshell's package-resolution control rather than relying on bare path ordering alone. The seeded preamble stays small: project path setup plus the bootstrap requires, before anything else runs. +- Pure-Tcl path ordering remains the inner layer the bootstrap itself depends on - the preamble must be correct before any package require, including the requires that load the bootstrap modules themselves. +- Related goals: G-012 (template payload safety - inert VCS-config payloads apply to this layout too), G-027 (derived-project pull updates - how light projects receive infrastructure refreshes), G-035 (mixed .tm/pkgIndex provision characterization backing libunknown/packagepreference behaviour), G-029 (packaged test modules - the light harness should stay compatible with that direction).