G-033 revised: proj: scope prefix, kit-first canonical, help text persisted
Design review outcomes (2026-07-07):
- Syntax: proj is not a fifth ordered token (category error - the dash
list is an ordered sequence of path blocks whose order IS the
same-version tie-break dial, per the verified tm rules and punk_main''s
own comment). Decided form: [proj:]<block>[-<block>...] - the prefix
scopes WHICH project root dev/src resolve against (cwd walk-up to the
nearest VCS repo root vs exe-relative), staying outside the ordered
list whose semantics are untouched. Explicit prefix = no silent rebind
on cd. Rejected: auto-detection, an explicit flag (less convenient),
token-attached qualifiers.
- Shadowing: visitor mode makes cross-lineage same-version-different-code
ties structurally expected (binary and visited project snapshots are
different vintages by definition). Order only arbitrates exact ties -
dev-versioned, higher-versioned and kit-absent modules come from the
project in either order. Canonical documented invocation is
proj:internal-src (kit-first: the visiting shell''s infrastructure
survives ties; for a standalone downloaded binary the kit is its only
trustworthy lineage and internal is location-independent); proj:src
documented as the faithful-vintage variant. Trimmed kits (G-019)
compose gracefully - kit-first only arbitrates ties.
- Required boot notice: detected root + effective precedence.
- packagemode help text drafted and persisted in the detail file as the
designated G-032 source (live only when the prefix ships); G-032 detail
cross-references it.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
Goal: the default launch dispatch defines its subcommands via punk::args - `<punkexe> -help` and argument errors render the tabled usage enumerating built-in and project-registered subcommands with summaries, and subcommand options parse through punk::args so projects can declare complex arguments - with the G-030 degradation rules (boot never fails and help degrades to plain text when punk::args or the ANSI rendering stack is unavailable).
Acceptance: `<punkexe> -help` renders tabled usage listing all subcommands including project-registered ones, each with a summary; at least one built-in subcommand's options are declared and parsed via punk::args with tabled usage errors on invalid input (the G-015 script subcommand or the G-025 version-report subcommand are the natural candidates); a project-registered subcommand's help appears by registration alone - no edits to the shared dispatch; with punk::args or the rendering stack unloadable, boot proceeds and help degrades to a plain subcommand list; verified on both a zipfs-based and a non-zipfs kit where both remain supported.
### G-033 [proposed] `proj` package-mode: visitor binary detects the cwd's project and explores it
### G-033 [proposed] `proj:` package-mode scope prefix: visitor binary resolves dev/src against the cwd's project
Goal: an explicit `proj` package-mode token lets an installed ("visitor") punkshell binary - one not built from the project - detect the punk project containing the current working directory (walking up to the nearest VCS repo root, the marker punk::repo::is_project_root already uses) and set up source/dev library resolution against THAT project, so a user can run e.g. `punkshell proj shell` from anywhere inside a project (which need not build its own shell-capable binary, or any binary at all) and explore it interactively; the token gates the behaviour so no `cd` silently rebinds a normal launch.
Acceptance: `<installed-punkexe> proj shell` launched from within a punk project's tree (the binary not belonging to that project) discovers the project root by walking up from cwd to the nearest VCS repo root and adds that project's src/modules, src/bootsupport/modules and src/vendormodules to the module path and src/lib to auto_path (the existing src-mode path machinery, parameterised on the cwd-detected root), so the session loads the project's dev-versioned modules; the detection marker matches punk::repo::is_project_root (a git or fossil repo root, not reliance on punkproject.toml); with no project found by walking up from cwd, `proj` warns and proceeds as `internal` with no false rebind; it works for a project that builds no executable of its own (proven against tomlish or a modules-only project); exe-relative `src`/`dev` discovery is unchanged for a binary that IS in a project's bin/; `proj` composes with the built-vs-source selectors (at least a documented default - proj implying source-tree resolution - with proj+dev / proj+src semantics recorded).
Goal: a`proj:` prefix on the package-mode string (e.g. `punkshell proj:internal-src shell`) makes the dev/src path blocks resolve against the punk project containing the current working directory - walking up to the nearest VCS repo root, the marker punk::repo::is_project_root already uses - instead of the executable's own project, so an installed ("visitor") punkshell binary, including one downloaded standalone with no source tree around it, can interactively explore a project that builds no shell-capable binary or no binary at all; the prefix scopes WHICH project, staying outside the ordered dash-list whose block order remains the same-version tie-break dial, and the explicit prefix gates the behaviour so no `cd` silently rebinds a normal launch.
Acceptance: `<installed-punkexe> proj:internal-src shell` (the documented canonical visitor invocation - kit copies win same-version ties, protecting the visiting shell's infrastructure; `proj:src` is the documented faithful-vintage variant where the project's copies win) launched from within a punk project's tree discovers the project root by walking up from cwd to the nearest VCS repo root and feeds it to the existing src-mode path machinery (src/modules, src/bootsupport/modules, src/vendormodules on the module path, src/lib on auto_path), so the session loads the project's dev-versioned modules while ordinary version resolution still lets the project supply anything the kit lacks or exceeds; the launch reports the detected project root and effective path precedence (never a silent rebind); with no project found walking up from cwd, or a `proj:` string containing no root-using block (dev/src), it warns and proceeds without false rebind; proven for a standalone binary outside any source tree (internal = kit contents regardless of binary location) against a project that builds no executable (tomlish is the natural first); exe-relative `src`/`dev` discovery is unchanged for a binary that IS in a project's bin/; the packagemode help text drafted in the detail file becomes the live punk::args documentation when implemented (rendered via G-032).
### G-034 [proposed] Zip-based #modpod modules mount in the shell code-interp on Tcl 8.6
Scope: src/modules/punk/mix/ (modpod mount path), vfs::zip availability in the repl code interp, src/modules/punk/cap/ (templates capability handler)
