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
G-031: split the monolithic vfs main (punk_main.tcl: 1190-line apply
block - ~1060 lines boot machinery, ~100 lines dispatch tail) into a
layout-owned boot core (shipped via _vfscommon.vfs, sourced by
vfs-relative path since no package paths exist at boot; pull-updatable
per the G-027 ownership model) and a thin project-owned main declaring
app subcommands at commented customization points. Fork cost measured:
tomlish_main.tcl carries ~20 custom lines on a stale 500-line 2025
vintage copy; project_main.tcl (901 lines) same at template vintage -
boot improvements never reach derived projects. Acceptance: behaviour
parity across dispatch cases and vfs types, project subcommand added by
editing only the thin main (tomlish the proving ground), boot core
versioned/reportable (G-025).
G-032: the default dispatch defines subcommands via punk::args - tabled
-help enumerating built-in and project-registered subcommands, parsed
options with tabled usage errors (script/G-015 or version-report/G-025
as first candidates), G-030 degradation rules (guarded require; parsing
falls back to switch semantics, help to a plain list; rendering degrades
independently). Parked decision: the silent unknown-arg->script
reclassification should stop swallowing typos (candidate rule:
reclassify only when the argument names an existing file).
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
Julian Noble