goals_xref: ship commented goals/xref.conf template; house comment convention

- goals/xref.conf: new template - every key present but disabled ('#' lines),
  per-item '##' explanation blocks; inert by construction (loader skips
  comment lines), so compiled-in defaults apply unchanged
- goals_xref.tcl header: house comment convention documented ('##'
  explanations stay, '#' prefixes disabled configuration lines)
- goals/AGENTS.md: orphan rule carves out xref.conf; Verification notes the
  shipped template
Verified: goals_lint exit 0; goals_xref report byte-identical with the
template in place.

Assisted-by: harness=opencode; primary-model=openrouter/moonshotai/kimi-k3; api-location=openrouter.ai

goals/AGENTS.md

@@ -70,7 +70,7 @@ When user-directed work on an `active` goal lands without satisfying its `Accept
 - At the achieved flip, record the verification evidence in the detail file body (`## Progress` or `## Notes`): what was verified, on which kits/runtimes, design outcomes worth keeping, and any remaining manual items. The `Status:` line itself carries only `achieved YYYY-MM-DD` (header field grammar above).
 - The archive move is content-identical: the file lands in `archive/` byte-for-byte as it left `goals/`, with the flip's content edits (Status line, evidence write-up) made before or after the move so the move diff is a pure rename (root `AGENTS.md` "Doc Restructures").
 - Reference sweep at archive time: grep the live tier (`goals/*.md`, `GOALS.md`) for the archived goal's ID. (a) Rewrite pending-tense phrasing ("once G-x lands", "after G-x is achieved") to reflect achievement, with the archive path - e.g. "(G-x, achieved - see goals/archive/G-x-<slug>.md)". (b) For each note in the archived detail file carrying actionable content for a live goal (a follow-on, dependency detail, or design decision that goal will need), add a one-line pointer to that live goal's `## Notes`: "G-x (archived) recorded <thing> - see goals/archive/G-x-<slug>.md". Mentions that are pure history need nothing. Rationale: an archived file is no longer edited, so its forward-pointing insights must be pushed to their targets when it leaves the active set. These are non-contract Notes updates - no pre-approval needed, report in the completion summary.
-- No orphan detail files: every file here (excluding `archive/` and this `AGENTS.md`) corresponds to a `proposed`, `active`, `abandoned` or `superseded` entry in root `GOALS.md`; every file under `archive/` corresponds to a record in `GOALS-archive.md`.
+- No orphan detail files: every file here (excluding `archive/`, this `AGENTS.md`, and `xref.conf`) corresponds to a `proposed`, `active`, `abandoned` or `superseded` entry in root `GOALS.md`; every file under `archive/` corresponds to a record in `GOALS-archive.md`.
 
 ## Work Guidance
 
@@ -80,7 +80,7 @@ LF line endings (per root AGENTS.md user preferences).
 
 `tclsh scriptlib/developer/goals_lint.tcl` — run after editing goal files or either index. Validates the detail-file header grammar (including the bare-`Status:` rule), index/detail orphan rules in both tiers, and the Status/Scope mirror consistency (plain tclsh, no dependencies; exit 0 clean, exit 1 with one line per finding). Informational, never fatal: warnings for stale references to archived goals lacking an achieved/archive marker, and for references to goal IDs present in neither index (dangling).
 
-`tclsh scriptlib/developer/goals_xref.tcl` - advisory relationship analysis (plain tclsh, no dependencies; always exit 0). Cross-references the live goals against scope overlap: `report` lists UNLINKED overlap pairs (overlapping goals that never reference each other) plus ONE-DIRECTIONAL pairs (back-pointer candidates), with path/term evidence per pair; `paths <p...>` lists the goals whose Scope intersects the given repo paths (the instrument for the "read intersecting goals before editing" step in root `GOALS.md` and for drafting-time overlap surveys); `score <G-id>` shows one goal's overlap pairs classified linked/one-directional/unlinked; `refs` lists dangling references. Scoring is IDF-weighted so ubiquitous anchors count for little; it ranks lexical overlap honestly but cannot see purely conceptual relationships - treat its output as a survey aid, never a gate. Repo-specific scoring vocabularies (path roots, stop words, file extensions, reference-container damps, module dirs, bare-root anchoring) may be adjusted per repo via an optional `goals/xref.conf` (key list in the tool's header comment); with no config file the compiled-in punkshell defaults apply unchanged.
+`tclsh scriptlib/developer/goals_xref.tcl` - advisory relationship analysis (plain tclsh, no dependencies; always exit 0). Cross-references the live goals against scope overlap: `report` lists UNLINKED overlap pairs (overlapping goals that never reference each other) plus ONE-DIRECTIONAL pairs (back-pointer candidates), with path/term evidence per pair; `paths <p...>` lists the goals whose Scope intersects the given repo paths (the instrument for the "read intersecting goals before editing" step in root `GOALS.md` and for drafting-time overlap surveys); `score <G-id>` shows one goal's overlap pairs classified linked/one-directional/unlinked; `refs` lists dangling references. Scoring is IDF-weighted so ubiquitous anchors count for little; it ranks lexical overlap honestly but cannot see purely conceptual relationships - treat its output as a survey aid, never a gate. Repo-specific scoring vocabularies (path roots, stop words, file extensions, reference-container damps, module dirs, bare-root anchoring) may be adjusted per repo via an optional `goals/xref.conf` (key list in the tool's header comment; a template ships at `goals/xref.conf` with every line disabled, so the compiled-in punkshell defaults apply unchanged).
 
 ## Child DOX Index
 

goals/xref.conf

@@ -0,0 +1,39 @@
+## goals_xref repo profile for punkshell - consumed by scriptlib/developer/goals_xref.tcl.
+##
+## Comment convention (house style): '##' introduces an explanatory comment
+## that stays; '#' prefixes a disabled configuration line - uncomment (delete
+## the leading '# ') to activate. This file ships with every configuration
+## line disabled, so the compiled-in punkshell defaults apply unchanged.
+## Key semantics are documented in the tool's header comment.
+
+## bare_path_roots: when 1, a bare scope token exactly naming a path root
+## (e.g. a sibling repo name) anchors as that root even without a '/'.
+# bare_path_roots 1
+
+## prefix_anchors: when 1, an admitted multi-segment path anchor also anchors
+## its leading segments (src/modules/punk/x also anchors src/modules), so
+## file-level and area-level scopes relate.
+# prefix_anchors 1
+
+## path_roots_add/remove: which top-level segments admit '/'-carrying
+## scope tokens as path anchors.
+# path_roots_add myrepo-lib myrepo-app
+# path_roots_remove temp_reference
+
+## stopwords_add/remove: the term-tier stop-word list.
+# stopwords_add myprojectterm
+# stopwords_remove tcl
+
+## file_extensions_add/remove: which extensions make a bare token a file anchor.
+# file_extensions_add conf
+# file_extensions_remove zig
+
+## reference_containers_add/remove: top-level dirs whose anchors damp x0.2
+## (reference dumps, not live scope).
+# reference_containers_add reference_dumps
+# reference_containers_remove temp_reference
+
+## module_dirs_add/remove: dirs scanned for module-key vocabulary
+## (isdir <root>/<d>/<name> or <d>/<name>-*.tm present).
+# module_dirs_add lib/modules
+# module_dirs_remove src/vendormodules

scriptlib/developer/goals_xref.tcl

@@ -84,6 +84,8 @@ proc read_lines {path} {
 # Line format: 'key value...' - blank lines and lines whose first character is
 # '#' are ignored (full-line comments only, so '#name' stays a valid module
 # token value). Unknown keys warn on stderr and are otherwise ignored.
+# House comment convention: '##' introduces an explanatory comment that stays;
+# '#' prefixes a disabled configuration line (uncomment to activate).
 #
 #   bare_path_roots 0|1           when 1, a bare scope token that exactly names
 #                                 a path root (e.g. a sibling repo name such as