goals: G-085 proposed - cmdtrace source-file vs live-proc line attribution + machine-parseable output

User-approved wording (drafted from the 2026-07-14 cmdtrace investigation):
an attribution option (live|sourcefile|auto - sourcefile mode doubling as a
practical workaround for the upstream nested-switch mis-attribution, tcl
tktview 5d5b1052280c976ea3d4) and a documented machine dict return for
future hotspot-analysis/repl consumers (implies no interactive pause).
Context records the unexplored regime boundary (module .tm procs trace
relative, plain sourced procs absolute) as goal groundwork. goals_lint clean.

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

GOALS.md

@@ -317,3 +317,7 @@ Detail: goals/G-083-punkargs-argument-relations.md
 ### G-084 [proposed] punk::args -parsekey completeness: cross-member -multiple collection, leaders/values support, defined default precedence
 Scope: src/modules/punk/args-999999.0a1.0.tm (parse paths, resolve directive handling for @leaders/@values), src/modules/punk/args/moduledoc/tclcore-999999.0a1.0.tm (sites carrying '#todo - fix -parsekey for leaders and values'), src/tests/modules/punk/args/testsuites/args/parsekey.test + testsuites/dev/parsekey-knownbugs.test (GAP/known-bug flips)
 Detail: goals/G-084-punkargs-parsekey-completeness.md
+
+### G-085 [proposed] punk::ns::cmdtrace: source-file vs live-proc line attribution option, and machine-parseable trace output
+Scope: src/modules/punk/ns-999999.0a1.0.tm (cmdtrace, _cmdtrace_* trace callbacks, argdoc), src/tests/modules/punk/ns/testsuites/ns/cmdtrace.test
+Detail: goals/G-085-cmdtrace-attribution-and-machine-output.md

goals/G-085-cmdtrace-attribution-and-machine-output.md

@@ -0,0 +1,58 @@
+# G-085 punk::ns::cmdtrace: source-file vs live-proc line attribution option, and machine-parseable trace output
+
+Status: proposed
+Scope: src/modules/punk/ns-999999.0a1.0.tm (cmdtrace, _cmdtrace_* trace callbacks, argdoc), src/tests/modules/punk/ns/testsuites/ns/cmdtrace.test
+Goal: punk::ns::cmdtrace can attribute traversed lines against either the live proc body (current corp -n based display) or the proc's originating source file (absolute path + file line numbers, when the definition location is recoverable), selectable by option with a sensible auto default - and can return its trace results as a documented machine-parseable dict (per target: attribution basis, cmdtype, per-line type/call counts, success/error/subcommand counts) instead of, or alongside, the ANSI-marked display - so the output is usable programmatically (future hotspot analysis, repl integration) and line reporting can be exact for file-defined procs even where live-relative tracing is degraded by the upstream nested-switch mis-attribution (tcl tktview 5d5b1052280c976ea3d4) or by line-continuation drift between source file and info body.
+Acceptance: an attribution option (spelling decided in the work, e.g. -linesource live|sourcefile|auto) defaults to current behaviour with existing cmdtrace.test passing unchanged; sourcefile mode, for a fixture proc whose definition location is known, reports marks as file path plus line numbers pinned against the actual file content - including a fixture with a backslash line continuation where live mode's known display drift is pinned alongside sourcefile mode's exact result - and degrades with a clear indication (not an error) for procs without a recoverable source location; a machine-output option (e.g. -return display|dict) returns a documented dict carrying per-target attribution basis, target name, cmdtype, line records (line -> type/calls), successcalls, errorcalls and subcommand count, asserted without parsing ANSI, with the default display return unchanged and machine mode implying no interactive pause; the upstream-mismark GAP pins are unaffected or deliberately updated; the cmdtrace argdoc documents both options; full punk::ns suite passes.
+
+## Context
+
+Grew out of the 2026-07-14 cmdtrace investigation (punk::ns 0.6.0, commit
+cabde42e, ns/cmdtrace.test added):
+
+- Which attribution regime a traced proc currently lands in depends on how it
+  was defined: module-loaded punk::ns procs trace as RELATIVE eval/proc frames,
+  while procs defined at the top level of a plainly sourced script yield
+  absolute source-typed frames with correct lines throughout. The boundary is
+  unexplored residue from that investigation (small sourced files retain
+  correlation even inside namespace eval; the punk::ns .tm does not).
+- In the relative regime, the upstream nested-switch mis-attribution applies
+  (core.tcl-lang.org tktview 5d5b1052280c976ea3d4; punk-free minimal repro at
+  scriptlib/developer/tcl_switch_traceline_repro.tcl, identical on
+  8.6.17/8.7a6/9.0.3): an arm body whose split pattern/body list index lands on
+  a literal word of the switch command reports container-relative lines. In the
+  absolute-source regime the raw probes showed no mis-attribution - so a
+  sourcefile mode is also a practical workaround for the upstream bug.
+- The cmdtrace argdoc has long documented that line continuations in a source
+  file make traced line numbers drift against info body lines, and suggests the
+  rename + redefine-from-body workaround; that same trick is a candidate
+  mechanism for deliberately forcing the live-relative regime.
+- ns/cmdtrace.test already asserts on the internal ::punk::ns::linedict data
+  because the ANSI display is not machine-friendly - evidence the machine
+  contract is needed.
+
+## Approach
+
+- auto attribution: prefer sourcefile when the target's frames report
+  source-typed absolute lines (or the definition location is otherwise
+  recoverable), else live. Explicit live|sourcefile override both directions.
+- Machine dict: extend rather than replace the existing ::punk::ns::linedict
+  shape - either promote that structure to documented contract or supersede it
+  explicitly (cmdtrace.test's marked_lines helper migrates to the contract).
+- -return dict implies -pause 0 unless -pause is explicitly supplied.
+- The sourcefile-regime boundary investigation (why module .tm procs lose
+  correlation) belongs to this goal's groundwork and may yield a further
+  addition to the upstream ticket.
+
+## Notes
+
+- Motivating consumers for machine output: hotspot/coverage analysis over
+  per-line call counts, and repl integration (the user flagged hotspot analysis
+  as a possible future use of cmdtrace's traversal marking).
+- cmdtrace output-channel discipline (its stdout/stderr noise) is deliberately
+  NOT part of this goal's acceptance - it can ride the planned punk::ns
+  comment/doc hygiene pass or a follow-on; machine mode only requires that the
+  RETURN VALUE be clean.
+- Related: the planned punk::ns hygiene pass (gated on coverage - ns/corp.test,
+  ansi/grepstr.test, ansi/untabify.test and ns/cmdtrace.test landed 2026-07-14
+  as precursors).