punkshell 0.12.38: G-087 hygiene stage closeout

- punkproject.toml 0.12.37 -> 0.12.38 with CHANGELOG entry covering the G-087
  layout-system hygiene stage (exact punk.project default, junk refs gone,
  no-handler/registration fixes, README rewrite, dead residue removal).
- src/modules/AGENTS.md: manually-versioned module documentation now covers
  punk::mix::base alongside punk::libunknown (base was already fixed-version
  without a buildversion.txt; its first bump to 0.1.1 followed the documented
  mechanics, requires verified unversioned 2026-07-17).

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

CHANGELOG.md

@@ -5,6 +5,10 @@ The latest `## [X.Y.Z]` header must match the `version` field in `punkproject.to
 Entries are newest-first; one bullet per notable change. See the root `AGENTS.md`
 "Project Versioning" section for the bump policy.
 
+## [0.12.38] - 2026-07-17
+
+- G-087 hygiene stage (layout system): `dev project.new`'s default -layout now resolves the exact name `punk.project` (layout ref renamed to carry the alias; previously tcl::prefix ambiguity between punk.project-0.1 and punk.project-0.1_overrides). Junk/test layout refs no longer selectable (test2, a duplicate sample-0.1, and the a.txt-only punk.shell-0.1 whose ref name lied about its content). No-handler warning paths in punk::mix::commandset::{layout 0.1.1, project 0.2.2, module 0.1.1, scriptwrap 0.1.1} and punk::mix::base 0.1.1 fixed ('put' -> 'puts', and return empty dict instead of erroring on an unset variable); punk::cap::handlers::templates 0.1.1 fixes the non-braced expr that errored on any absolute-pathtype template provider registration, and the duplicate-registration guard that errored ('key not known in dictionary') for any second provider package registering the same capability. src/project_layouts/README.md rewritten to describe the implemented punk.templates+layout_refs mechanism including the ref filename grammar; dead modpod templates/layouts payload (punk::mix::templates 0.1.4) and make.tcl old_layout_update_list residue removed.
+
 ## [0.12.37] - 2026-07-15
 
 - tablelist vendored 6.22 -> 7.11, now as a pkgIndex-based vendorlib package (src/vendorlib/tablelist7.11) instead of .tm vendormodules, propagated to _vfscommon.vfs; _vfscommon built punk modules refreshed (ansi 0.1.3, args 0.12.3, lib 0.5.0, ns 0.8.0, repl 0.5.2).

punkproject.toml

@@ -1,4 +1,4 @@
 [project]
 name = "punkshell"
-version = "0.12.37"
+version = "0.12.38"
 license = "BSD-2-Clause"

src/modules/AGENTS.md

@@ -15,7 +15,7 @@ Source of truth for all editable Punk project modules. This is where agents shou
 
 - Module filenames use the literal suffix `-999999.0a1.0.tm`.
 - Corresponding `<modulename>-buildversion.txt` files hold the real version number.
-- The exception is `punk::libunknown`, which is manually versioned: its real `major.minor.patch` version lives in the filename (`libunknown-<version>.tm`) and there is no buildversion.txt. The same bump rules apply as for buildversion-tracked modules (see "Versioning And Releases"); the mechanics differ — see the manual-versioning bullet there.
+- The exceptions are `punk::libunknown` and `punk::mix::base`, which are manually versioned: the real `major.minor.patch` version lives in the filename (e.g `libunknown-<version>.tm`, `mix/base-<version>.tm`) and there is no buildversion.txt. The same bump rules apply as for buildversion-tracked modules (see "Versioning And Releases"); the mechanics differ — see the manual-versioning bullet there.
 - `#modpod-*` directories contain internal files packed into `.tm` archives during build; do not flatten or edit them without understanding the modpod format.
 - `_build/` directory holds build intermediates and should not be manually edited.
 - Always declare dependencies explicitly using `package require <name>` near file tops.
@@ -321,7 +321,7 @@ return
   This keeps the changelog discoverable alongside the version number without requiring a separate CHANGES file.
 - **Bootstrap-tracked files only** — `punkcheck-buildversion.txt`, `punk/repo-buildversion.txt`, `punk/mix-buildversion.txt` (the top-level `punk::mix` file only; `punk::mix::util`, `punk::mix::cli`, and `punk/mix/commandset/*` version independently and are not covered by this check), `punk/tdl-buildversion.txt`, and `punk/args-buildversion.txt` (added by G-030: make.tcl dogfoods punk::args for dispatch/help; only the parsing contract is tracked — the punk::ansi/textblock rendering stack degrades instead): bump at least **minor** whenever a call site inside that file is updated to use a new API, even if the file's own interface is unchanged. `src/make.tcl` reads only these five files to classify bootsupport staleness (major=abort, minor=prompt, patch=silent-proceed); under-bumping one of them to patch when the call-site change is more significant causes `make.tcl` to mis-classify and either wrongly proceed without prompting or wrongly abort. See `src/bootsupport/AGENTS.md` "Bootsupport Staleness Handling" for the full contract.
 - **All other modules** (including `punk::mix` submodules): call-site updates follow ordinary judgement from the Patch/Minor/Major rules above — a behavior-preserving call-site change is a patch (or no bump if genuinely a no-op); reserve minor for changes that add capability to the module's *own* API. `src/make.tcl` does not read these versions, so there is no automated consequence, but keep the changelog accurate since it is the only record of the module's real semantic version.
-- **Manually versioned modules** (currently only `punk::libunknown`): the real `major.minor.patch` version is the filename suffix and the `package provide` block value; there is no `<name>-buildversion.txt` and the build does not stamp a version. The Patch/Minor/Major bump rules above apply identically — an agent changing such a module bumps by (1) renaming the file (`git mv`) to the new version, (2) updating the `# Application <name> <version>` Meta line, the doctools `manpage_begin` version and the provide-block `set version`, and (3) appending a changelog comment line to the version-history block in the module header (it substitutes for the buildversion.txt changelog). Before the first bump of such a module, verify nothing requires it by exact version or hardcoded filename (for punk::libunknown: punk_main.tcl and punk::repl glob `libunknown-*.tm` and pick the highest by vcompare, bootsupport's include_modules.config lists it by name only, and all requires are unversioned - verified 2026-07-11). New modules should use the magic version mechanism instead.
+- **Manually versioned modules** (currently `punk::libunknown` and `punk::mix::base`): the real `major.minor.patch` version is the filename suffix and the `package provide` block value; there is no `<name>-buildversion.txt` and the build does not stamp a version. The Patch/Minor/Major bump rules above apply identically — an agent changing such a module bumps by (1) renaming the file (`git mv`) to the new version, (2) updating the `# Application <name> <version>` Meta line, the doctools `manpage_begin` version and the provide-block `set version` (where each exists - punk::mix::base has only the provide block), and (3) appending a changelog comment line to the version-history block in the module header (it substitutes for the buildversion.txt changelog). Before the first bump of such a module, verify nothing requires it by exact version or hardcoded filename (for punk::libunknown: punk_main.tcl and punk::repl glob `libunknown-*.tm` and pick the highest by vcompare, bootsupport's include_modules.config lists it by name only, and all requires are unversioned - verified 2026-07-11; for punk::mix::base: all requires unversioned, bootsupport include_modules.config lists it by name only - verified 2026-07-17). New modules should use the magic version mechanism instead.
 - Modules with the magic version number must not appear in output paths such as `<projectdir>/modules`.
 - When referencing ranges, use bounded specs such as `1.2.3-2.0.0`.
 - Convert loose versions to bounded form in module metadata; helper utilities exist in boot modules for this purpose.