From 331e894c03e66a2320ef1dadabd7ffdc535af881 Mon Sep 17 00:00:00 2001 From: Julian Noble Date: Sat, 11 Jul 2026 17:33:26 +1000 Subject: [PATCH] goals: add G-062/G-063/G-064 licensing and lib.search machine-output goals G-062: canonical project license - root BSD-2-Clause LICENSE.txt with SPDX-identified references in README.md, root AGENTS.md and a machine-readable license field in punkproject.toml. G-063: per-package license tracking - SPDX-normalized Meta license indications via a friendly-name mapping module (authors need not know SPDX ids), copyleft/viral-license flagging audit surface, and fixing the literal %license% template placeholder seeding. G-064: dev lib.search machine-parsable returns - ansi-free -return dict/json with documented structure (G-049 pattern) plus an option surfacing per-package license indications in table and machine returns. All three proposed with user-approved wording (2026-07-11). Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com --- GOALS.md | 12 +++++++++ goals/G-062-project-license-file.md | 21 +++++++++++++++ goals/G-063-package-license-tracking.md | 34 ++++++++++++++++++++++++ goals/G-064-libsearch-machine-returns.md | 23 ++++++++++++++++ 4 files changed, 90 insertions(+) create mode 100644 goals/G-062-project-license-file.md create mode 100644 goals/G-063-package-license-tracking.md create mode 100644 goals/G-064-libsearch-machine-returns.md diff --git a/GOALS.md b/GOALS.md index 6afaaf0e..1db11578 100644 --- a/GOALS.md +++ b/GOALS.md @@ -265,3 +265,15 @@ Detail: goals/G-060-qemu-test-matrix.md ### G-061 [proposed] Pseudoconsole expect-alternative for interactive shell testing (ConPTY + unix pty) Scope: test-harness support (location TBD during the work: src/tests/testsupport/ and/or a small punk module), src/tests/shell/ (capability-gated interactive suites), goals/G-061-pseudoconsole-expect.md Detail: goals/G-061-pseudoconsole-expect.md + +### G-062 [proposed] Canonical project license: BSD-2-Clause LICENSE file with SPDX-identified references +Scope: LICENSE.txt (new, repo root), README.md, punkproject.toml ([project] license field), AGENTS.md (Repo-wide Notes license mention) +Detail: goals/G-062-project-license-file.md + +### G-063 [proposed] Per-package license tracking: SPDX-normalized indications with copyleft audit +Scope: src/modules (Meta license headers), src/vendormodules/ + src/vendorlib/ (vendored license recording), punk::mix module templates (%license% seeding), mapping module (new, name TBD), audit surface (src/make.tcl or dev commandset - TBD) +Detail: goals/G-063-package-license-tracking.md + +### G-064 [proposed] lib.search machine-parsable returns (dict/json) and license surfacing option +Scope: src/modules/punk/mix/commandset/loadedlib-999999.0a1.0.tm, src/tests/modules/punk/mix/ (new testsuite), G-063 mapping module (as consumed) +Detail: goals/G-064-libsearch-machine-returns.md diff --git a/goals/G-062-project-license-file.md b/goals/G-062-project-license-file.md new file mode 100644 index 00000000..1d7b382a --- /dev/null +++ b/goals/G-062-project-license-file.md @@ -0,0 +1,21 @@ +# G-062 Canonical project license: BSD-2-Clause LICENSE file with SPDX-identified references + +Status: proposed +Scope: LICENSE.txt (new, repo root), README.md, punkproject.toml ([project] license field), AGENTS.md (Repo-wide Notes license mention) +Goal: the repository declares exactly one canonical license: a root LICENSE.txt containing the verbatim BSD-2-Clause text, with README.md and root AGENTS.md naming the license by its SPDX identifier and pointing at LICENSE.txt, and punkproject.toml carrying the identifier machine-readably so tooling (the G-063 audit, derived-project seeding) can read the project license without parsing prose. +Acceptance: LICENSE.txt exists at the repo root containing the standard BSD-2-Clause text with a real copyright line; README.md names BSD-2-Clause and points at LICENSE.txt; root AGENTS.md Repo-wide Notes names the license precisely; punkproject.toml [project] carries license = "BSD-2-Clause"; a repo-sweep for top-level license claims finds none contradicting it (sweep result recorded here). + +## Context + +README has said only "BSD license" since 2023 with no LICENSE file anywhere at the +repo root - every LICENSE file in-tree belongs to a vendored library. "BSD" without +a variant is not a specific license; BSD-2-Clause is the chosen variant +(decision 2026-07-11). + +## Notes + +- Copyright line content (holder name, year range) to be confirmed with the user at + write time. +- Seeding LICENSE.txt into generated project layouts is a natural follow-on but is + deliberately not part of this goal's acceptance (src/project_layouts sync is + restricted; see G-012/G-027 territory). diff --git a/goals/G-063-package-license-tracking.md b/goals/G-063-package-license-tracking.md new file mode 100644 index 00000000..0580fbf7 --- /dev/null +++ b/goals/G-063-package-license-tracking.md @@ -0,0 +1,34 @@ +# G-063 Per-package license tracking: SPDX-normalized indications with copyleft audit + +Status: proposed +Scope: src/modules (Meta license headers), src/vendormodules/ + src/vendorlib/ (vendored license recording), punk::mix module templates (%license% seeding), mapping module (new, name TBD), audit surface (src/make.tcl or dev commandset - TBD) +Goal: every package punkshell ships - first-party modules, vendored modules, vendored libs - carries a license indication resolvable to an SPDX identifier, without requiring module authors to know SPDX: authors write familiar names ("BSD", "MIT", "Tcl license") in the existing Meta license header slot and a mapping layer normalizes them; an audit surface reports per-package license posture and loudly distinguishes copyleft/viral licenses and unresolved/unspecified entries, so GPL-family code cannot enter the tree unnoticed. +Acceptance: a mapping facility (punk module, name decided in the work) resolves friendly license names to SPDX ids - tolerant of case/spacing variants, covering at least every value currently present in Meta license headers, and returning a distinct "unresolved" result for unknown strings rather than guessing; an audit command (make.tcl subcommand or dev commandset command, decided in the work) enumerates packages under src/modules, src/vendormodules and src/vendorlib and reports each one's SPDX id, unresolved raw value, or unspecified; a documented copyleft policy list (GPL, AGPL and LGPL families at minimum) is flagged distinctly in audit output; module templates no longer emit the literal %license% placeholder; first-party headers are populated or the remainder listed here as pending with reasons. + +## Context + +Module files already carry a teapot-style "Meta license" header slot, but it is +mostly unpopulated: a 2026-07-11 tally across src/modules + src/vendormodules found +69 , 19 literal %license% template placeholders, 31 MIT, ~36 BSD, +1 ISC, 1 . Vendored libraries under src/vendorlib carry their upstream +LICENSE files in their directories but nothing aggregates them. The project's +copyleft caution is already on record (G-060's GPL-safe posture); this goal makes +it auditable per package. + +## Approach + +- Reuse the existing Meta license slot rather than inventing new header syntax; + normalization happens at read time. +- Mapping data lives in a punk module so the shell (lib.search per G-064) and + make.tcl share one implementation. A vendored subset of the SPDX license list + plus pass-through of already-valid SPDX ids is expected to suffice; the full + list is large and mostly irrelevant to the Tcl ecosystem. +- Audit starts read-only (report/warn). Enforcement (abort on copyleft match) + follows the G-026 pattern: policy with explicit override, only after a cleanup + pass proves it won't block routine work. + +## Notes + +- Related: G-026 (vendorupdate is the natural hook for capturing vendored license + provenance), G-060 (recorded GPL-safe posture), G-062 (project's own license id), + G-064 (lib.search as the interactive surface for these indications). diff --git a/goals/G-064-libsearch-machine-returns.md b/goals/G-064-libsearch-machine-returns.md new file mode 100644 index 00000000..6bab4c47 --- /dev/null +++ b/goals/G-064-libsearch-machine-returns.md @@ -0,0 +1,23 @@ +# G-064 lib.search machine-parsable returns (dict/json) and license surfacing option + +Status: proposed +Scope: src/modules/punk/mix/commandset/loadedlib-999999.0a1.0.tm, src/tests/modules/punk/mix/ (new testsuite), G-063 mapping module (as consumed) +Goal: dev lib.search results are consumable by programs as well as humans: ansi-free -return options producing a Tcl dict and json with a documented structure (package name, available versions, present version as data fields), plus an option that surfaces each package's license indication in both the human table and the machine returns - so an agent piping 'dev lib.search -return json', or Tcl code using -return dict, needs no ansi stripping or list-position guessing. +Acceptance: -return gains dict and json choices whose output contains no ansi escapes regardless of -highlight; the returned structure is documented in the command's punk::args definition; the present version is conveyed as a data field, not highlight markup; a license option adds a per-package license field (SPDX id, unresolved raw value, or unspecified - per the G-063 mapping) to table, dict and json returns; new tests pin dict/json shape, ansi-freeness, and the license option's unspecified fallback. + +## Context + +Current -return choices are {table tableobject list lines}; list/lines embed ansi +highlight codes unless -highlight 0 is passed, and the list structure is +undocumented positional {name versions} pairs. G-049 (achieved 2026-07-10) +established the machine-parsable -return dict pattern on punk::ns::cmdhelp; this +goal applies it to lib.search and adds json for agent consumers (the G-017 +piped-call direction). + +## Notes + +- The dict/json returns do not depend on G-063 and can land first; the license + field consumes G-063's mapping when present (progress tracked here if split). +- json serialization mechanism decided in the work: a quick sweep found no obvious + json writer in-tree (options: minimal local serializer, vendored tcllib + json::write, or a punk-native helper).