G-089 proposed: scriptlib in kits + packagemode-aware lib: resolution

New goal (user-approved wording): make.tcl bakes a curated scriptlib into
kit vfs app/scriptlib so standalone binaries have working lib: scripts, with
precedence following the packagemode mental model - kit-internal-wins only
for the default 'internal' launch, src/dev modes putting the live project
scriptlib first, and proj: (G-033) adding the visited project's scriptlib.
Context records the 2026-07-18 findings: kit-internal resolver branch never
exercised (no build path exists), not-overridable policy scoped to default
mode per user direction, missing boot->runtime packagemode hint, cookfs
mount-root gap, and the out-of-scope app-shellspy mapping. goals_lint clean.

Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com

GOALS.md

@@ -333,3 +333,7 @@ Detail: goals/G-087-thin-project-layouts.md
 ### G-088 [proposed] textblock table footer block + bottom-edge subtitle (arg_error examples marker)
 Scope: src/modules/textblock-999999.0a1.0.tm (class::table options and bottom border assembly), src/modules/punk/args-999999.0a1.0.tm (arg_error usage-table examples marker), src/tests/modules/punk/args/testsuites/args/examples.test + textblock table coverage
 Detail: goals/G-088-textblock-table-footer-subtitle.md
+
+### G-089 [proposed] Scriptlib in kits + packagemode-aware lib: resolution (visitor scriptlib via proj:)
+Scope: src/make.tcl, src/vfs/ (kit vfs payloads), src/modules/punk/path-999999.0a1.0.tm, src/vfs/_config/punk_main.tcl, scriptlib/
+Detail: goals/G-089-scriptlib-kits-and-modes.md

goals/G-089-scriptlib-kits-and-modes.md

@@ -0,0 +1,58 @@
+# G-089 Scriptlib in kits + packagemode-aware lib: resolution
+
+Status: proposed
+Scope: src/make.tcl, src/vfs/ (kit vfs payloads), src/modules/punk/path-999999.0a1.0.tm, src/vfs/_config/punk_main.tcl, scriptlib/
+Goal: built kits carry an internal scriptlib (baked by make.tcl into the kit vfs at app/scriptlib, curated - test fixtures/logs excluded) so a standalone punk binary has working lib: scripts, and scriptlib precedence follows the same mental model as the module path blocks: kit-internal-wins applies to the default 'internal' launch only, src/dev package modes put the project's live scriptlib first (un-masking edits during development), and a proj:-prefixed launch (G-033) additionally resolves lib: against the visited project's scriptlib.
+Acceptance: a kit built with the baked scriptlib, relocated outside any source tree, runs '<exe> script lib:<name>' for a baked script; from <projectroot>/bin the default launch runs the kit copy while 'src' mode runs an edited live <projectroot>/scriptlib copy of the same name (proven by differing markers); cookfs kits either resolve their internal scriptlib too or are explicitly documented as excluded; the packagemode reaches scriptlib_resolve via a boot-provided hint rather than being re-derived; with G-033 implemented, 'proj:' adds the cwd-project's scriptlib to the search (deferred to G-033 if that lands later, recorded here).
+
+## Context
+
+Findings from the 2026-07-18 lib: extensionless work (punk::path 0.3.0):
+
+- The kit-internal branch of `punk::path::scriptlib_resolve`
+  (`<zipfs-root>/app/scriptlib`, or `<exepath>/scriptlib` for a mounted
+  tclkit) has never been exercised: no `.vfs` layout contains a `scriptlib/`
+  folder and `src/make.tcl` never references scriptlib. `lib:` works today
+  only because the repo's executables sit in `<projectroot>/bin`, making
+  `<exedir-parent>/scriptlib` the repo's `scriptlib/`. A standalone installed
+  binary currently has NO working `lib:` source at all.
+- The documented "internal scripts are deliberately NOT overridable"
+  policy was intended for the default launch behaviour only (user direction
+  2026-07-18), not as an absolute - once kits carry a baked scriptlib, an
+  unconditional kit-first rule would mask live `scriptlib/` edits in the dev
+  workflow (exe in `<projectroot>/bin`) until the next rebuild. The
+  packagemode dash-list is already the user's precedence dial for module
+  paths; scriptlib should ride the same mental model.
+- Nothing currently records the chosen packagemode anywhere
+  `punk::path` can see - punk_main consumes arg0 and rearranges paths but
+  exposes no mode hint to the runtime layer. A small boot-interface addition
+  is needed (candidate: a `::punkboot::` or `punk::config` "running" value
+  seeded at boot).
+- `scriptlib_resolve` checks only the zipfs root and the
+  exepath-as-directory (tclkit) cases for the kit-internal dir; cookfs kits
+  (e.g punk9cook) mount elsewhere (`//cookfstemp:/...` style roots tracked by
+  punk_main's `internal_paths`) and would miss a baked scriptlib.
+- The bake itself: a punkcheck-managed copy of `scriptlib/` into the
+  target vfs during make, curated - `_punktest/` fixtures, `*.log`, and other
+  non-shippable content excluded. Baking policy per kit class (dev-built vs
+  release/standalone) is an open decision within this goal.
+- Visitor semantics follow G-033's decisions: `proj:` is an explicit
+  opt-in (no silent cwd rebind), and kit-first remains the canonical robust
+  default for ties in visitor mode - the visited project's scriptlib joins
+  the search *after* kit-internal under `proj:internal-...`, with block order
+  controlling precedence as for module paths.
+- Out of scope: app-shellspy's `do_script_process` keeps its own simpler
+  `lib:` mapping (external-interpreter semantics, any extension); the
+  `script`/`shell` subcommands are the surfaces this goal covers.
+
+## Notes
+
+- Related goals: G-033 (proj: scope prefix - the visitor root discovery this
+  goal's proj: scriptlib clause rides on; its notes already flag that
+  `proj:... script` benefits), G-018/G-019 (installable/trimmed kits),
+  G-015 (achieved - script subcommand, goals/archive/G-015-script-subcommand-piped-stdin.md).
+- `lib:<name>.kit` dispatch (restored in punkshell 0.14.0 via punk::path
+  0.3.0's known-extensions fix) has no committed test fixture - a `.kit`
+  archive would violate the no-new-binaries rule (G-004); if kit-dispatch
+  coverage is wanted, generate a throwaway kit at test time or defer until
+  G-005/G-006 tooling exists.