punkshell 0.12.40: G-087 stage 2 closeout (fauxlink layout refs)

CHANGELOG + version bump for the fauxlink ref migration; G-087 detail file
gains the stage-2 Progress increment with verification record and findings
(stale snapshot-payload .ref copies pending stage 3; shellproject decktemplates
declaration points at repo root so outside-project cwd lists no layouts -
pre-existing, stage-3 candidate; punkcheck MAX_PATH relative-source hazard;
make.tcl self-lock on mounted modpod prune).

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.40] - 2026-07-17
+
+- G-087 stage 2: layout refs migrated to fauxlink files. fauxlink 0.2.0 (vendored from upstream) implements fauxlink::link_as - the encoder counterpart of resolve with a round-trip guarantee - and the migration script used it to generate every new ref name. punk::cap::handlers::templates 0.2.0 resolves layout refs via the fauxlink module (<alias>#<encodedtarget>.fauxlink|.fxlnk, target relative to src/project_layouts); the bespoke <alias>@<target>.ref grammar is retired (.ref files no longer recognised). Layout refs must carry a non-empty alias - alias-less (leading-#) refs are warned about and skipped (punkcheck excludes leading-# filenames). All 7 live refs renamed (alias-less ones gained their target-tail aliases); visible layout names unchanged. punk::mix::templates 0.1.5 carries the migrated module-shipped ref. Verified end-to-end: dev project.new resolves the default punk.project layout through fauxlink refs and materializes a full project.
+
 ## [0.12.39] - 2026-07-17
 
 - fauxlink 0.1.2 vendored from upstream (c:/repo/jn/tclmodules/fauxlink, now under fossil version control with a 62-test suite): punk::args documentation for the whole developer-facing API including a (package)fauxlink id (inert until G-075 surfaces package ids); fixes for decode_unicode_escapes dropping the first character when a hexless %U was present, single-comment (3-section) links skipping validation/decoding, and the link_as stub silently no-oping (now raises 'not yet implemented'). Consumers (fcat redirect-follow, make.tcl merge_over/startup-script check, kit boot fallback) unchanged.

goals/G-087-thin-project-layouts.md

@@ -210,9 +210,60 @@ Verification (2026-07-17, native tclsh 8.7/9 runtests + rebuilt root modules):
 - Resulting layout names: punk.sample-0.1 punk.project punk.minimal punk.basic
   punk.shell-0.1_overrides punk.project-0.1_overrides.
 
-Remaining for acceptance (pivot stage - Approach stages 2-5):
+### 2026-07-17 stage 2 complete: fauxlink layout refs (increment 2)
+
+Landed (punk::cap::handlers::templates 0.2.0, punk::mix::templates 0.1.5;
+fauxlink 0.2.0 vendored from upstream):
+
+- fauxlink::link_as implemented upstream (fauxlink 0.2.0, checkin 1e6b4ee8):
+  name + forward-slash target (+ optional -tags/-comments/-extension) -> fauxlink
+  filename with a resolve round-trip guarantee. 83-test upstream suite.
+- Handler cutover: get_itemdict_projectlayoutrefs selects *#*.fauxlink/.fxlnk
+  and derives names via fauxlink::resolve; get_itemdict_projectlayouts derives
+  the layout folder from the resolved targetpath; the bespoke <alias>@<target>.ref
+  parser is gone and .ref files are no longer recognised. Alias-less (leading-#)
+  refs and unresolvable refs are skipped with a warning (punkcheck hazard per
+  Approach stage 2). Bonus fix: the ignore* skip previously matched against the
+  full glob path so it never applied.
+- All 7 live-tier refs migrated via a link_as-driven script (each new name
+  round-trip-verified before rename): decktemplates vendor/punk x4 (alias-less
+  refs gained their target-tail aliases: basic, minimal, sample-0.1),
+  custom/_project x2, module-shipped modpod ref x1. Zero-byte property kept.
+- src/project_layouts/README.md ref-grammar section rewritten for fauxlink.
+
+Verification (2026-07-17): stage-2 scratch script 7/7 - layout names identical
+to the pre-migration set with exact punk.project resolution; refs dict paths all
+.fauxlink; planted alias-less decoy warned + skipped; planted old-grammar .ref
+decoy ignored; module-shipped ref lists as punk.project#2 (resolution still dead
+pending stage 3). runtests prune/fossilmove/multishell/libsearch all pass.
+End-to-end `dev project.new <abs-path> -confirm 0` (punk902z src, piped,
+FOSSIL_HOME diverted) resolved the default punk.project layout through fauxlink
+refs and materialized the full project tree; the run's trailing in-project
+fossil commit failed on a binary-data prompt (layout payload ships no
+binary-glob - G-012 territory, unrelated to refs).
+
+Notes from the work:
+
+- Stale-snapshot payload copies of the old .ref grammar remain under
+  src/project_layouts/*/src/bootsupport/... and the fat vendor snapshot's inner
+  trees - stale-by-design, retired with the snapshots in stage 3. Generated
+  projects' decktemplates payloads currently carry no layout_refs at all.
+- project.new from a cwd outside any project has an empty layout list even with
+  a shell built from a project: the punk::mix::templates shellproject_multivendor
+  declaration points at <shellproject>/decktemplates (repo root - nonexistent),
+  not src/decktemplates. Pre-existing; natural stage-3 fix alongside module-ref
+  resolution.
+- punkcheck::install source reads can exceed Windows MAX_PATH when the relative
+  source chain is long (deep target dir + many ../ segments, unnormalized path);
+  surfaced as 'could not read ... no such file' during a deep-scratchpad
+  generation. Pre-existing, candidate for a punkcheck normalization fix.
+- make.tcl bootsupport prune of punk/mix/templates-<v>.tm fails with permission
+  denied when the running make.tcl process itself has that modpod mounted
+  (self-lock); the stale copy must be deleted manually afterwards. Candidate
+  small fix: unmount or defer-prune modpods the process mounted.
+
+Remaining for acceptance (pivot stage - Approach stages 3-5):
 
-- fauxlink ref migration (stage 2).
 - thin layouts + generation-time bootsupport injection, retire make.tcl layout
   bootsupport-sync, module-shipped thin punk.project layout for bare kits (stage 3).
 - staging-directory overlay merge primitive exercising the sample-0.1/othersample

punkproject.toml

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