User-directed activation and implementation in one arc (proposed -> active at
the user's word with the activation-freshness survey recorded, -> achieved +
archived on acceptance). Co-location kills the doc-drift class: the actual
'-e' parsing and its punk::args documentation now live in the same file.
app-punkscript 1.2 + new package app-punkscript-docs 1.2 (same file):
src/lib/app-punkscript/punkscript.tcl carries the (script)::punkexe::script
definition (the G-168 selection-sound shape moved VERBATIM - value strings
byte-identical, renders match the pre-handover moduledoc) in
::app::punkscript::argdoc with an idempotent docs section - a plain
namespace-variable set plus a membership-guarded lappend to
::punk::args::register::NAMESPACES; no package requires, no punk::args
dependency, no definition evaluation (lazy on the first query naming the id -
the docpackages mechanism pinned ahead in docpackages.test). pkgIndex.tcl
provides app-punkscript-docs from the SAME file via an execution gate
(::app::punkscript::docs_only set around the source; the file returns after
the docs section when the gate is up, and 'package provide app-punkscript'
sits below the gate) - requiring the docs NEVER runs a script, and a later
app require re-sources with the gate down so the app runs normally (probed:
docs-then-app in one process, file/'-e' one-liner/'-e'-alone usage error all
behave identically through the new file).
punkboot core 0.6.0: new launcher_builtin_docpackages map (script ->
app-punkscript-docs); launcher_show_help's built-in arm does a guarded lazy
'package require' of the mapped docs package before the usage query -
help-path only, never on boot/dispatch (ready-probe and dispatch untouched).
The G-031 registration-model header comment now names the durable doc id and
records the app-owned 'package'-key option. Copies synced byte-identical:
project-0.1 layout + modpod-template layout.
punkexe moduledoc 0.8.0 (single-definer handover): (script)::punkexe::script
is no longer defined here - a pointer comment stands in its place and the
Overview records the ownership rule (docs live with the owning code:
app-owned for app-handled subcommands, this moduledoc for core-owned
surfaces like tclsh/buildinfo/help and the top-level dispatch). Single
definer verified: loading both sources raises no duplicate-definition
(undefine) notices - the handover withdraws the moduledoc entry in the same
change-set per the docpackages last-loaded-wins pre-test pin.
Durable-doc decision (the acceptance's 'location decided in the work'): the
registration definition id (script)::punkboot::registration IS the durable
doc for the *_main.tcl declaration keys (summary/argsid/package/parse incl
the parse=1 gate, all already documented there); punkboot moduledoc 0.3.1
extends its 'package' key text with the app-owned docs-package pattern (gate
shape pointed at src/lib/app-punkscript/pkgIndex.tcl). Kit authors reach it
from the core header contract, the punkexe moduledoc Overview and the
project_main.tcl worked examples.
Help-path load cost measured and recorded (goal file): the app-ownership
marginal cost is the guarded docs require - 3.5 ms (inert). The ~396 ms
first-render total is the one-time punk::ansi/textblock render-stack load +
definition evaluation, incurred identically wherever the definition lives;
boot/dispatch cost is zero.
Tests: launcherhelp.test 25/25 - 24 existing pins unchanged plus new
launcherhelp_appowned_script_docs: the fake-main harness (G-031 shape, no
bake) run through the baked kit's tclsh subcommand in SRC package mode,
where the source tree serves the nested boot with version precedence - the
src moduledoc defines no script id, so the successful tabular render
carrying the G-168-era scriptfile help text (line-break-safe markers; the
oneliner form's rows are not in the default form-0 table) proves the
app-owned lazy resolution; stderr asserted free of 'clearing existing data'
notices. Harness lesson recorded: manual tm/auto_path prepends in a fake
main are WIPED by the nested boot's path configuration - the src package
mode is the correct lever. Full modules/punk/args subtree 337 passed / 3
pre-existing skips / 0 failed on BOTH tclsh90 and tclsh87 - the G-168
punkexemodel.test/formcheck.test pins now load the script id via
app-punkscript-docs (src/lib derived from the test file location) and guard
the handover shape at its new home. The 10 failures in maketclbakelist.test
/ maketcllibfetch.test are PRE-EXISTING (reproduced identically at HEAD
with this change-set stashed; the G-139 libfetch-test reading is a recorded
pending user decision). Degraded/plain path intact (PUNKBOOT_PLAIN pin
unchanged; mixed promotion states degrade gracefully by construction).
Minted punkexe-0.8.0.tm + punkboot-0.3.1.tm via make.tcl modules.
Goals: G-169 entry moved to GOALS-archive.md, detail file to goals/archive/
with mechanism, decisions, measured costs and verification evidence; two
open Follow-ons (the coherent-set vfscommonupdate/bake promotion carrying
lib/app-punkscript 1.2 + core 0.6.0 + punkexe 0.8.0 together; extending app
ownership to shell/punk/shellspy). Reference sweep: G-170's Related line
updated (the defs' home now decided - its formhint un-suppression edits
both homes). src/lib AGENTS.md app-punkscript bullet + src/tests/modules
AGENTS.md punk/args bullet extended. goals_lint clean (81 active / 89
archived).
Claude-Session: https://claude.ai/code/session_0156PuejSCGjgeGb7jiABrDU
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
Julian Noble
97e4aacd4f