From 6dedcd27299b4047b2df60dc8c3373401467529a Mon Sep 17 00:00:00 2001 From: Julian Noble Date: Fri, 24 Jul 2026 23:55:14 +1000 Subject: [PATCH] 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 | 4 +-- goals/xref.conf | 39 ++++++++++++++++++++++++++++++ scriptlib/developer/goals_xref.tcl | 2 ++ 3 files changed, 43 insertions(+), 2 deletions(-) create mode 100644 goals/xref.conf diff --git a/goals/AGENTS.md b/goals/AGENTS.md index cde0774f..81026c44 100644 --- a/goals/AGENTS.md +++ b/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-.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 - see goals/archive/G-x-.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 ` 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 ` 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 ` 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 ` 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 diff --git a/goals/xref.conf b/goals/xref.conf new file mode 100644 index 00000000..6802cbe3 --- /dev/null +++ b/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 // or /-*.tm present). +# module_dirs_add lib/modules +# module_dirs_remove src/vendormodules diff --git a/scriptlib/developer/goals_xref.tcl b/scriptlib/developer/goals_xref.tcl index 70b8b3d0..37fd95dc 100644 --- a/scriptlib/developer/goals_xref.tcl +++ b/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