G-087 stage 2: layout refs migrated to fauxlink (bespoke .ref grammar retired)

punk::cap::handlers::templates 0.2.0: layout refs are fauxlink files
(<alias>#<encodedtarget>.fauxlink|.fxlnk, target relative to
<projectroot>/src/project_layouts, resolved via the fauxlink module).
get_itemdict_projectlayoutrefs selects *#*.fauxlink/.fxlnk with fauxlink-derived
names; get_itemdict_projectlayouts derives the layout folder from the resolved
targetpath; the <alias>@<target>.ref parser is removed and .ref files are no
longer recognised. Alias-less (leading-#) refs and unresolvable refs are
skipped with a warning - punkcheck-based tooling excludes leading-# filenames,
so layout refs must carry a non-empty nominal name. Also fixes the ignore*
skip, which previously matched against the full glob path and never applied.

All 7 live-tier refs renamed via a fauxlink::link_as-driven migration script
(each generated name round-trip-verified through fauxlink::resolve before
rename): decktemplates vendor/punk x4 (alias-less refs gained their target-tail
aliases: basic, minimal, sample-0.1), custom/_project x2, and the
module-shipped modpod ref (punk::mix::templates 0.1.5). Zero-byte property and
all visible layout names unchanged. src/project_layouts/README.md ref-grammar
section rewritten for fauxlink.

Note: git's rename pairing crosses two of the zero-byte vendor/punk refs
(sample-0.1 <-> project) - content-identical empty files; the true mapping is
alias-preserving as described above.

Verified: stage-2 scratch checks 7/7 (name parity incl exact punk.project,
decoy alias-less ref warned+skipped, old-grammar decoy ignored); runtests
prune/fossilmove/multishell/libsearch pass; end-to-end dev project.new
materializes a full project from the default punk.project layout.

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

src/modules/punk/cap/handlers/templates-999999.0a1.0.tm

@@ -19,6 +19,7 @@
 ##e.g package require frobz
 
 package require punk::repo
+package require fauxlink ;#layout refs are .fauxlink/.fxlnk files (G-087 stage 2 - bespoke .ref grammar retired)
 
 
 # ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++
@@ -511,14 +512,12 @@ namespace eval punk::cap::handlers::templates {
                     set sourceinfo [dict get $refinfo sourceinfo]
                     set path [dict get $refinfo path]
                     set reftail [file tail $path]
-                    set atparts [split [file rootname $reftail] @]
-                    #may be two @s if referencing a renamed layout override?
-                    # e.g ref may be @vendor+punks+othersample@sample-0.1  or layoutalias-1.1@vendor+punk+othersample@sample-0.1
-                    #there must always be an @ before vendor or custom . There is either a template-name alias or empty string before this first @
-                    #trim off first @ part
-                    set tailats [join [lrange $atparts 1 end] @]
-                    # @ parts after the first are part of the path within the project_layouts structure
-                    set subpathlist [split $tailats +]
+                    #layout refs are fauxlink files: <alias>#<encodedtarget>.fauxlink|.fxlnk
+                    #target is relative to <projectroot>/src/project_layouts
+                    # e.g project#vendor+punk+project-0.1.fauxlink
+                    #an @ within a target segment is literal fauxlink content (derived-layout folder names such as othersample@sample-0.1)
+                    #unresolvable refs were already skipped (with a warning) by get_itemdict_projectlayoutrefs
+                    set targetpath [dict get [fauxlink::resolve $reftail] targetpath]
                     if {[dict exists $refinfo sourceinfo base]} {
                         #some template pathtypes refer to the projectroot from the template - not the cwd
                         set ref_projectroot [dict get $refinfo sourceinfo base]
@@ -528,7 +527,7 @@ namespace eval punk::cap::handlers::templates {
 
                     if {$ref_projectroot ne ""} {
                         set layoutroot [file join $ref_projectroot src/project_layouts]
-                        set layoutfolder [file join $layoutroot {*}$subpathlist]
+                        set layoutfolder [file join $layoutroot $targetpath]
                         if {[file isdirectory $layoutfolder]} {
                             #todo - check if layoutname already in layoutdict append .ref path to list of refs that linked to this layout?
                             set layoutinfo [list path $layoutfolder basefolder $layoutroot sourceinfo $sourceinfo]
@@ -546,31 +545,37 @@ namespace eval punk::cap::handlers::templates {
                 @values -maxvalues -1 -unnamed 1
             }]
             method get_itemdict_projectlayoutrefs {args} {
+                #layout refs are fauxlink files: <alias>#<encodedtarget>.fauxlink|.fxlnk (target relative to <projectroot>/src/project_layouts)
                 set config {
                     -templatefolder_subdir "layout_refs"\
                     -command_get_items_from_base {apply {{base} {
-                        set matched_files [glob -nocomplain -dir $base -type f *@*.ref]
+                        set matched_files [glob -nocomplain -dir $base -type f {*#*.fauxlink} {*#*.fxlnk}]
                         set items [list]
                         foreach rf $matched_files {
-                            #puts stderr "--> $rf"
-                            if {[string match ignore* $rf]} {
+                            set ftail [file tail $rf]
+                            if {[string match ignore* $ftail]} {
                                 continue
                             }
-                            #we silently skip .ref files that don't match - todo - more verification - and warn of invalid .refs?
-                            if {[string match *@vendor+* $rf] || [string match *@custom+* $rf]} {
-                                lappend items $rf
+                            if {[string index $ftail 0] eq "#"} {
+                                #alias-less ref: punkcheck-based tooling treats leading-# filenames as hidden/aside,
+                                #so such a ref would silently vanish from punkcheck-driven installs of the containing tree.
+                                puts stderr "punk::cap::handlers::templates get_itemdict_projectlayoutrefs WARNING - skipping layout ref '$rf' - layout refs must carry a non-empty nominal name (leading-# filenames are excluded by punkcheck-based tooling)"
+                                continue
+                            }
+                            #only accept refs whose encoded target is rooted at vendor or custom (within src/project_layouts)
+                            if {!([string match {*#vendor+*} $ftail] || [string match {*#custom+*} $ftail])} {
+                                continue
                             }
+                            if {[catch {fauxlink::resolve $ftail} resolve_result]} {
+                                puts stderr "punk::cap::handlers::templates get_itemdict_projectlayoutrefs WARNING - skipping unresolvable layout ref '$rf' ($resolve_result)"
+                                continue
+                            }
+                            lappend items $rf
                         }
                         return $items
                     }}}\
                     -command_get_item_name {apply {{vendor basefolder itempath} {
-                        set itemtail [file rootname [file tail $itempath]]
-                        set alias [lindex [split $itemtail @] 0]
-                        if {$alias eq ""} {
-                            set itemname [lindex [split $itemtail +] end]
-                        } else {
-                            set itemname $alias
-                        }
+                        set itemname [dict get [fauxlink::resolve [file tail $itempath]] name]
                         if {$vendor ne "_project"} {
                             set itemname $vendor.$itemname
                         }

src/modules/punk/cap/handlers/templates-buildversion.txt

@@ -1,5 +1,6 @@
-0.1.1
+0.2.0
 #First line must be a semantic version number
 #all other lines are ignored.
+#0.2.0 - G-087 stage 2: layout refs are now fauxlink files (<alias>#<encodedtarget>.fauxlink|.fxlnk, resolved via the fauxlink module; target relative to <projectroot>/src/project_layouts). Bespoke <alias>@<target>.ref grammar removed - .ref files are no longer recognised. Alias-less (leading-#) refs and unresolvable refs are skipped with a warning (punkcheck excludes leading-# filenames). New dependency: fauxlink. Also fixes the ignore* skip (previously matched against the full glob path, so it never applied).
 #0.1.1 - fix: pkg_register 'absolute' pathtype branch had a non-braced expr 'if {!file exists $normpath}' which raised an expr syntax error on any absolute-pathtype provider registration; now correctly tests ![file exists $normpath]
 #0.1.1 - fix: pkg_register duplicate-registration guard did 'dict get $provider_info $pkg' without a dict exists check, erroring for any second provider package registering the same capability

src/modules/punk/mix/templates-buildversion.txt

@@ -1,4 +1,5 @@
-0.1.4
+0.1.5
 #First line must be a semantic version number
 #all other lines are ignored.
+#0.1.5 - G-087 stage 2: module-shipped layout ref migrated to fauxlink grammar (project#vendor+punk+project-0.1.fauxlink)
 #0.1.4 - removed dead templates/layouts/project payload subtree (design-generation residue: no reader; layout payloads live in src/project_layouts, located via layout_refs - G-087 hygiene)

src/project_layouts/README.md

@@ -26,24 +26,33 @@ suffixed #2, #3, ...
 Layout refs
 -----------
 
-A layout ref is a zero-byte file in a layout_refs/ folder under a template
-base (e.g. src/decktemplates/vendor/punk/layout_refs/, or a module-shipped
-templates/layout_refs/). The entire meaning is in the filename:
+A layout ref is a zero-byte fauxlink file in a layout_refs/ folder under a
+template base (e.g. src/decktemplates/vendor/punk/layout_refs/, or a
+module-shipped templates/layout_refs/). The entire meaning is in the filename,
+which follows the standard fauxlink grammar (see the fauxlink package
+documentation) resolved by the vendored fauxlink module:
 
-    <alias>@<segment>+<segment>+...  .ref
+    <alias>#<segment>+<segment>+...  .fauxlink   (or .fxlnk)
 
-- The text before the first @ is the alias - the layout's nominal name.
-  If the alias is empty the last + separated segment is used as the name.
-- The text after the first @ is a + separated path relative to
-  <projectroot>/src/project_layouts identifying the layout folder.
-  Segments after the first @ may themselves contain @ (derived-layout folder
-  names such as othersample@sample-0.1).
+- The text before the first # is the alias - the layout's nominal name.
+  Layout refs MUST carry a non-empty alias: punkcheck-based tooling treats
+  leading-# filenames as hidden/aside, so an alias-less ref would silently
+  vanish from punkcheck-driven installs. The handler warns about and skips
+  such refs.
+- The text after the first # is the fauxlink-encoded target: a + separated
+  path relative to <projectroot>/src/project_layouts identifying the layout
+  folder. Segments may contain literal @ (derived-layout folder names such
+  as othersample@sample-0.1); other special characters use fauxlink %XX
+  encoding. fauxlink::link_as generates conformant names programmatically.
 - The visible layout name is prefixed with the vendor folder name and a dot
   unless the vendor is the pseudo-vendor _project
-  (e.g. project@vendor+punk+project-0.1.ref in a vendor/punk/layout_refs
+  (e.g. project#vendor+punk+project-0.1.fauxlink in a vendor/punk/layout_refs
   folder presents as layout name "punk.project").
-- Only filenames matching *@vendor+*.ref or *@custom+*.ref are recognised;
-  files named ignore* are skipped.
+- Only filenames whose encoded target starts at vendor+ or custom+ are
+  recognised; files named ignore* are skipped; unresolvable fauxlink names
+  are skipped with a warning.
+- The pre-fauxlink <alias>@<target>.ref grammar was retired 2026-07-17
+  (G-087 stage 2) - .ref files are no longer recognised.
 
 The ref indirection exists to break recursion: layout payloads may embed
 module trees (including the punk::mix::templates module itself), so modules