punkshell/goals/G-068-vendored-moduledoc-workflow.md

G-068 Agent-assisted moduledoc generation workflow for vendored third-party libraries

Status: proposed Scope: goals/G-068-vendored-moduledoc-workflow.md (workflow doc), src/modules/punk/args/moduledoc/ (generated companion modules), src/tests/modules/punk/args/ (probe verification where feasible) Goal: a vendored third-party library that neither ships nor references punk::args documentation can be given a punk::args::moduledoc companion through a documented, repeatable agent-assisted workflow - the G-055 pattern generalized beyond core.tcl-lang.org projects: upstream doc text (man pages, README, doctools) carried verbatim under the G-055 fidelity policy, synopses translated into punkshell's synopsis syntax, safe probe verification applied where feasible, upstream source/version provenance recorded with the definitions - run as a separate optional step after vendoring, so basic vendoring (G-065) never requires agent availability, with each vendored package's moduledoc status (present / absent / stale against the vendored version) trackable. Acceptance: the workflow is documented in this file (inputs, fidelity and synopsis-translation policy by reference to G-055, probe-verification gate including the criteria for declaring probing infeasible for a command, provenance recording, and how the workflow consumes a vendored payload rather than a core source tree); a moduledoc companion produced through the workflow exists for at least one vendored library - src/vendorlib/tcl_oauth2_library as the proving case - loading alongside the untouched vendored source and surfacing in the help system; the vendoring path demonstrably completes without this step (a package vendored with no moduledoc loads and audits normally); moduledoc status per vendored package is queryable from a defined surface (G-065 manifest field or the G-063/G-064 audit surface - decided in the work) and distinguishes present, absent and stale-against-vendored-version.

Context

External Tcl libraries will almost never carry punk::args documentation unless future authors adopt it; giving them punkshell-quality help means authoring a moduledoc companion. G-055 built the workflow shape for tclcore (verbatim fidelity, synopsis translation, probe gates, provenance) and explicitly anticipated extension to other projects while keeping them out of scope. Doc authoring needs judgement, so this is likely always agent-assisted - which is exactly why it must be decoupled from basic vendoring: a developer on a machine without agents vendors now and generates (or receives) the moduledoc later. A published artifact (G-067) can carry its moduledoc with it, so the generation cost is paid once per ecosystem, not once per developer.

Approach

• Inputs per run: the vendored payload path + recorded upstream version (from G-065 provenance), plus whatever docs the upstream ships (man pages like oauth2.man, README, doctools sources).
• Companion placement: a moduledoc module under src/modules/punk/args/moduledoc/ loading on 'package require ' (tkcore pattern noted in G-055), or embedded in a G-066 repackaged artifact - placement decision recorded in the work; the vendored source itself is never modified (src/vendorlib contract).
• Probe verification: where commands are safe/pure enough, the G-055 real-vs-model error/ok agreement gate applies; for network-touching or stateful commands (the oauth2 case) the workflow documents the infeasibility criteria and falls back to doc-fidelity review only.
• Staleness: moduledoc records the upstream version it was authored against; status compares that to the currently vendored version.

Notes

• Related: G-055 (workflow pattern source; its modelability-gap scan discipline applies here too), G-063/G-064 (audit surfaces that could report moduledoc status), G-065 (manifest tracking, agent-free vendoring guarantee), G-066/G-067 (carrying moduledocs inside repackaged/published artifacts).