punkshell/goals/G-063-package-license-tracking.md

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).
• Archived-goal references in this file: G-062 achieved 2026-07-11 (goals/archive/G-062-project-license-file.md).