Browse Source
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.commaster
4 changed files with 90 additions and 0 deletions
@ -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). |
||||
@ -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 <unspecified> 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 <unspecified>, 19 literal %license% template placeholders, 31 MIT, ~36 BSD, |
||||
1 ISC, 1 <unknown>. 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). |
||||
@ -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). |
||||
Loading…
Reference in new issue